Blocking hooks

Some instructions keep being missed however they are worded. A blocking hook stops asking and checks instead: a PreToolUse hook that looks at a tool call before it runs, denies the wrong ones, and tells the agent what to do. It must also decide what happens when it breaks. A blocking hook that fails closed blocks the call when it can't do its job; one that fails open lets the call through, and a crash quietly becomes a pass.

Know PreToolUse hooks already? Skip to In Terrarium.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep."
  }
}

In Terrarium

Terrarium calls its blocking hooks guards. docs/agents/guards.md is the roster: each guard, what it denies, where the rule it enforces lives, and its issue. It lists the hints too, which add guidance and deny nothing. Each guard's own script header holds its reasons and the cases it can't see.

A guard is a small script in scripts/hooks/: a registry of the cases it knows, a pure check, and a message. scripts/hooks/hook-io.ts holds the plumbing they share: reading the payload and the transcript, the deny JSON, and a --dry-run mode. A guard's main shows the pattern. An empty stdin, a bare run by hand, passes; a payload it can't read is denied:

98export function main(): void {
99  const result = readHookPayload()
100  if (result.kind === 'none') return
101  if (result.kind === 'invalid') return denyUninspectable(LABEL, REF, 'the hook payload was not valid JSON')
102  if (result.kind === 'no-tool') return denyUninspectable(LABEL, REF, 'the hook payload named no tool')
103
104  const { payload } = result
105  const output = denyOutputFor(checkSkillInlineCall(payload.tool_input, readTranscript(payload.transcript_path)))
106  if (output) process.stdout.write(JSON.stringify(output))
107}

A transcript it can't read denies too. denyUninspectable says the block is a guard fault, not the agent's mistake. Every guard starts through runGuard, which turns a thrown error into the same kind of deny:

126  const onCrash = (err: unknown): void => {
127    if (opts.failOpen) return
128    denyUninspectable(opts.label, opts.ref, `the guard itself crashed (${err instanceof Error ? err.message : String(err)})`)
129  }
130  try {
131    const done = opts.dryRun && argv.includes('--dry-run') ? opts.dryRun(argv) : opts.main()
132    if (done instanceof Promise) done.catch(onCrash)
133  } catch (err) {
134    onCrash(err)
135  }

A crash before that try, such as a TypeScript runner that won't start or an import that throws, prints nothing and exits nonzero. The wiring in .claude/settings.json covers that case: each guard's hook sets onFailure, except the ones docs/agents/guards.md lists as wired with || true. The first entry here is such an exception; the second is the usual wiring:

15      {
16        "matcher": "TaskCreate|Monitor",
17        "hooks": [
18          {
19            "type": "command",
20            "command": "cd \"${CLAUDE_PROJECT_DIR:-.}\" && node_modules/.bin/tsx scripts/hooks/deferred-tool-guard.ts || true"
21          }
22        ]
23      },
24      {
25        "matcher": "ScheduleWakeup",
26        "hooks": [
27          {
28            "type": "command",
29            "command": "cd \"${CLAUDE_PROJECT_DIR:-.}\" && node_modules/.bin/tsx scripts/hooks/loop-only-tool-guard.ts",
30            "onFailure": "block"
31          }
32        ]
33      },

scripts/hooks/deferred-tool-guard.ts catches a tool called with another tool's arguments. It passes failOpen: true to runGuard, and its hook ends in || true, which turns any exit into 0, with no onFailure. The Stop hook scripts/hooks/harness-tag-stop.ts, which the roster lists with the guards, and every hint are wired with || true too.

A test holds the wiring in place. tests/unit/guards-wiring.spec.ts finds every scripts/hooks/*-guard.ts, checks a PreToolUse hook runs it, and, for all but the fail-open list, checks the hook sets onFailure and holds no || true:

8const FAIL_OPEN = ['deferred-tool-guard']
⋯// …
15describe('every scripts/hooks/*-guard.ts is wired', () => {
16  it.each(guards)('%s runs from a PreToolUse hook', (guard) => {
17    const wired = entries.filter((h) => h.command.includes(`scripts/hooks/${guard}.`))
18    expect(wired, `no PreToolUse hook runs ${guard}`).not.toHaveLength(0)
19    if (FAIL_OPEN.includes(guard)) return
20    for (const h of wired) {
21      expect(h.onFailure, h.command).toBe('block')
22      expect(h.command, 'a `|| true` exits 0, so onFailure never fires').not.toContain('|| true')
23    }
24  })

Each guard has its own unit test in tests/unit/, such as tests/unit/skill-inline-guard.spec.ts: it calls the pure check with recorded and adversarial inputs, an unreadable transcript included, and runs the real script once through stdin and once through --dry-run. Most guards' Usage: headers show the --dry-run command that prints the decision for a given call, with no deny.

Where next

• LessonClaude Code hooks
• LessonProtected paths
• LessonSubagents
• LessonMCP servers
• LessonTesting