Skip to content

Lesson Hook Type Matters

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

type: synthesis up: "Home_llm-wiki-memory-template" criticizes: "PostToolUse-Hook" tags: [lesson, claude-code, hook]

Lesson: Hook Type Matters

PR #1's PostToolUse hook was originally a type: "prompt" hook with "advisory, do not block" wording in the prompt. The wording had no effect. The hook actively broke wiki ingests. Priscila's point 7 diagnosed the issue from a live session.

What went wrong

Prompt-type hooks are sandboxed single-turn model calls with two terminal outcomes: allow or block. They cannot read the filesystem or transcript. There is no advisory mode.

The original prompt asked the evaluator to check whether the index, log, and cross-references had been updated. The evaluator could not access any of those files. It correctly returned not-ok, and the turn stopped, mid-ingest, with the new page created but nothing committed.

The "advisory" wording was wishful thinking. The mechanism does not support advisory prompt hooks; the contract is enforce-or-allow with no third option.

The fix

Switch to a type: "command" hook with an exit-0-always shell script:

#!/usr/bin/env bash
# Read PostToolUse event JSON on stdin, extract written file path,
# print a reminder if the path is a wiki page, exit 0 unconditionally.

The shell script cannot evaluate the wiki, but it does not need to. It nudges the agent (which can evaluate the wiki) to run the actual gate. 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.

The corrected script lives at wiki/agents/claude-code/templates/posttooluse-hook.sh and is installed by setup.sh --posttooluse-hook into .claude/hooks/, with the matcher "Write|Edit".

The general principle

When the design intent is advisory, a reminder, a nudge, a soft check, the only hook type that supports it is command. Prompt hooks are for hard gates: "this action must satisfy criterion X, evaluated by a model call, or be blocked."

If the prompt of a prompt-type hook contains the word advisory, that is a contradiction. Redesign as a command hook.

How it was caught

Live behavioral testing in a real Claude Code session, run from a freshly-instantiated project. Structural tests passed (the hook installed correctly to the right path with the right matcher); only the behavioral test exposed the issue. The lesson generalizes: see Lesson-Validation-Methodology.

See also

Clone this wiki locally