Hooks

How hooks work

Clients expose different lifecycle events, payloads, trust controls, and blocking semantics. TRW installs only the adapters supported by the selected client profile; the behavior is intentionally not identical everywhere.

Most policy adapters fail open on infrastructure errors. A few adapters intentionally block on a policy result, and Cursor CLI marks its before-shell and before-MCP security gates as fail closed. Treat the client row below as the source of blocking posture, not a universal exit-code rule.

Client support is not uniform

TRW maps only the events each client actually exposes. A missing hook does not remove the protocol: instruction files and MCP tool middleware remain available across clients.

Hook events

These are the behaviors registered by the bundled Claude Code template. Other clients use different names and smaller event sets; see the support matrix above.

Registered Claude Code set

The package ships 17 top-level hook scripts, including compatibility scripts that are not active by default. The bundled Claude template registers the subset below through .claude/settings.json. Presence in .claude/hooks/ alone does not mean a script will run.

Hook registration

This excerpt uses the same project-root-safe command path as the bundled Claude template. Each client has its own schema; do not copy this JSON into Cursor, Codex, Copilot, or Antigravity configuration.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [{
          "type": "command",
          "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\"",
          "timeout": 5000
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "mcp__trw__trw_deliver",
        "hooks": [{
          "type": "command",
          "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-deliver-gate.sh\"",
          "timeout": 5000
        }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "sh \"$CLAUDE_PROJECT_DIR/.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. The full template registers separate SessionStart entries for startup, resume, compact, and clear. The abbreviated example shows only startup.

Custom hooks

You can add your own hooks alongside TRW's registered set. This non-blocking Claude Code example is intentionally client-specific; use your client's schema elsewhere.

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

A blocking hook needs to distinguish an intentional policy denial from an infrastructure failure. An unconditional trap 'exit 0' EXIT would erase an intentional exit 2. The bundled shell gates use an explicit flag instead:

#!/bin/sh
set -e
intentional_exit=0
trap '[ "$intentional_exit" = "1" ] || exit 0' EXIT

if policy_is_unmet; then
  echo "BLOCKED: explain the required action" >&2
  intentional_exit=1
  exit 2
fi

exit 0

Phase-change suppression

user-prompt-submit.sh avoids repeating phase guidance when the inferred phase has not changed. This keeps repeated prompts in one phase quiet.

The hook caches the last emitted phase in .trw/context/last_ups_phase. It emits again when the phase changes, when there is no active run, or after session-start logic clears the cache.

Contextual learning injection

In clients that register user-prompt-submit.sh, a phase-change event can scan recent local learning entries and add a bounded set of keyword matches to hook output. This lightweight adapter is separate from the ranked trw_recall tool and should not be described as equivalent retrieval.

1. Extract bounded keywords from the user's prompt
2. Scan recent files in .trw/learnings/entries by keyword match
3. Score each result; keep entries where score ≥ auto_recall_min_score (default 0.7)
4. Emit up to auto_recall_max_results matches within the configured token cap
5. Session dedup: skip learnings already injected this session
6. 500ms timeout guard - if search exceeds limit, inject nothing (fail-open)

Troubleshooting

Next steps