Skip to content

PostToolUse Hook

Jump to bottom
Chris Sweet edited this page Jun 12, 2026 · 2 revisions

type: concept up: "Agent-Overlays" extends: "Verification-Gate" tags: [hook, claude-code, advisory]

PostToolUse Hook

An optional, advisory Claude Code hook that fires after every Write or Edit and reminds the agent to run the Verification-Gate before committing. Installed via wiki/agents/claude-code/setup.sh --posttooluse-hook. Not installed by default.

What it does

When the agent Writes or Edits a file inside the wiki sub-repo, the hook prints a short reminder of the verification-gate criteria. The reminder lands in the agent's context for the next turn. The hook does not block; the action proceeds either way.

The mechanism (and a lesson learned)

The hook is a command-type hook (type: "command"), not a prompt-type hook. This distinction is load-bearing:

  • A prompt-type hook is a sandboxed single-turn model call with two terminal outcomes: allow or block. It cannot read the filesystem or transcript. There is no advisory mode. If the prompt asks for a check that requires reading state, the evaluator returns not-ok and the turn stops.
  • A command-type hook is a shell script. Exit code controls block vs allow. The script can read the PostToolUse event JSON on stdin, print to stderr or stdout, and exit 0 (advisory) or non-zero (block).

The original PR #1 implementation used type: "prompt" with "advisory, do not block" wording in the prompt. The wording had no effect. Prompt hooks cannot be advisory, and the hook actively broke ingests in live testing. The corrected version (wiki/agents/claude-code/templates/posttooluse-hook.sh) is a shell script that reads the event JSON, checks whether the written file is a wiki page, prints a reminder if so, and exits 0 unconditionally. See Lesson-Hook-Type-Matters for the full diagnosis.

Matcher

matcher: "Write|Edit". The original PR shipped "Write" only, which missed the Edit calls used for index, log, and cross-reference updates, exactly the places the gate matters most. Priscila's review caught this as point 2.

Why it cannot evaluate the wiki itself

A shell script reading event JSON on stdin has no agent tools. It cannot follow cross-references, read other pages, or run SPARQL queries. So the hook does not check the criteria; it reminds the agent (which does have those tools) to check them. The contract becomes: the hook adds a reminder to context, the agent decides what to do with it. This is the correct division of labor.

Optional and opt-in

The hook is not installed by default. Users add it explicitly via the --posttooluse-hook setup flag. The reasoning: many users will find the hook redundant if they already run the verification gate proactively, and adding a hook everyone has to dismiss is worse than no hook.

See also

Clone this wiki locally