Hooks

How Hooks Work

Claude Code fires hook events at specific points in its lifecycle — when a session starts, before a tool runs, after a file is modified, and when the session ends. TRW registers shell scripts against these events in .claude/settings.json. When an event fires, Claude Code runs the matching script and reads its output.

Each hook follows a fail-open pattern: if the script errors, it exits 0 silently so your session is never broken by hook infrastructure. Hooks that enforce gates (like the delivery blocker) use exit code 2 to signal a block with an explanation message.

Hook Events

Claude Code provides the hook events. TRW registers scripts against each one.

Built-in Hooks

TRW ships these 13 hook scripts. They are installed into .claude/hooks/ and registered in .claude/settings.json automatically.

Hook Registration

Hooks are registered in .claude/settings.json under the hooks key. Each event maps to an array of matchers, and each matcher contains a shell command and timeout. The TRW installer generates this configuration automatically.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [{
          "type": "command",
          "command": "sh .claude/hooks/session-start.sh",
          "timeout": 5000
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "mcp__trw__trw_deliver",
        "hooks": [{
          "type": "command",
          "command": "sh .claude/hooks/pre-tool-deliver-gate.sh",
          "timeout": 5000
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "sh .claude/hooks/stop-ceremony.sh",
          "timeout": 10000
        }]
      }
    ]
  }
}

The matcher field filters when the hook fires. An empty string matches all events of that type. A specific value like mcp__trw__trw_deliver matches only that tool call. SessionStart uses source matchers ( startup, resume, compact, clear) to fire on each session source.

Custom Hooks

You can add your own hooks alongside TRW's built-in ones. Add a new entry to the appropriate event array in .claude/settings.json. Your hook script receives the same JSON payload from stdin that TRW's hooks receive.

// In .claude/settings.json, add to the PostToolUse array:
{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "sh .claude/hooks/my-bash-audit.sh",
    "timeout": 3000
  }]
}

Custom hooks follow the same conventions: exit 0 to allow, exit 2 to block (with a message on stderr). Use the fail-open pattern — trap 'exit 0' EXIT — so errors never break the agent's session.

Real-Time Security Scanning

Every Write and Edit tool call is automatically scanned for 9 OWASP-aligned security patterns. The scan runs in ~10ms and warns the agent without blocking — giving it a chance to self-correct before the code ships.

Phase-Change Suppression

Prior to Sprint 79, user-prompt-submit.sh fired on every prompt — injecting a reminder even when nothing had changed. In sessions with many back-and-forth prompts this produced 20–100 hook emissions, adding noise and token overhead without value.

The hook now caches the last emitted phase in .trw/run/last-hook-phase. It only fires when the active phase differs from the cached value, reducing typical emissions to 3–5 per session — one per phase transition.

Contextual Learning Injection

When user-prompt-submit.sh fires on a phase change, it also searches prior learnings for content relevant to the user's current prompt. Matching learnings are injected directly into the prompt, giving the agent relevant institutional knowledge at the exact moment it needs it — without requiring the agent to call trw_recall manually.

1. Extract keywords from the user's prompt
2. Search .trw/learnings/ index by keyword match
3. Score each result; keep entries where score ≥ auto_recall_min_score (default 0.7)
4. Inject top 3 matching learnings (≤ auto_recall_max_tokens tokens)
5. Session dedup: skip learnings already injected this session
6. 500ms timeout guard — if search exceeds limit, inject nothing (fail-open)

Performance

Hooks are designed to be fast. Every hook uses the fail-open pattern (errors exit 0) and has strict timeouts. The total overhead per Edit/Write call is under 100ms. Session hooks fire once, not on every tool call.

Troubleshooting

Next Steps