Hooks

How hooks work

Clients that expose lifecycle events do so at specific points in their workflow - when a session starts, before a tool runs, after a file is modified, and when the session ends. TRW binds its policy to those events so the same guardrails can be enforced without relying on the user to remember them.

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 exposes the raw event names shown here, and the other clients with native automation surfaces map equivalent behavior onto the same intent.

Built-in hooks

TRW ships these 15 hook scripts. In Claude Code they live in .claude/hooks/ and are registered through .claude/settings.json. Other supported clients translate the same behavior into their own configuration surfaces.

Hook registration

This section shows the raw Claude Code registration format. Each event maps to an array of matchers, and each matcher contains a shell command and timeout. The TRW installer generates the equivalent configuration automatically for the clients you selected.

{
  "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. The example below uses Claude Code syntax, but the general pattern is the same everywhere: attach a fast script to the relevant event and let TRW keep the policy surface close to the repo.

// 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.

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, so overhead per call stays low. Session hooks fire once, not on every tool call.

Troubleshooting

Next steps