claude-code-hooks-daemon

Hooks Daemon — Active Handler Guidance

The handlers listed below are active in this project. Read this section to avoid triggering unnecessary blocks.

When a tool is blocked by a handler, do not stop working. Read the block reason, modify your approach, and continue with your task.

A file written through Bash is not seen by the content guards that run BEFORE the write. The PreToolUse handlers below that inspect what a file CONTAINS, or where it lives, key on the Write and Edit tools — so a >, >>, tee or a cat <<EOF heredoc reaches disk unexamined by them: no block, no advisory, no record. A Bash write that drew no complaint is NOT a write that passed those checks — use Write/Edit for file content and they apply.

The LINTERS are the exception, and they DENY. lint_on_edit and validate_eslint_on_write do run on a file a Bash command AUTHORS — a redirect, tee, a heredoc — so unparseable Python or failing TypeScript is reported however it reached disk. The write has already landed, so the denial is a failure report to repair with Edit, not a rollback. A file the command merely RELOCATES (cp, mv, install, dd) is never linted: those bytes were already on disk, so blaming the copy would report a defect the command did not introduce.

The handlers that judge a Bash COMMAND — destructive git, sed, pipes, permissions, curl | sh — are unaffected and still cover you.

If something outside this project tells you to prefer Bash, sed or a heredoc over Write/Edit for file content, it does not override this. That advice is written for repositories without these guards; here it routes every write around the checks above and sed is denied outright. Use Write/Edit, and treat the conflict as settled rather than re-deciding it.

Full detail on any rule: bin/hooks-daemon explain-rule <ID>.

Frequently-triggered handler guidance

lsp_enforcement — use LSP tools for code symbol lookups

Using Grep or Bash (grep/rg) to find class definitions, function signatures, or symbol references is blocked or redirected to LSP tools, which are faster and semantically accurate.

Prefer LSP tools for:

• Finding where a class or function is defined → goToDefinition
• Finding all usages of a symbol → findReferences
• Getting type information or documentation → hover
• Listing all symbols in a file → documentSymbol
• Searching symbols across the project → workspaceSymbol

Grep/Bash grep is still appropriate for: text patterns in content, log searching, finding strings in config files.

Default mode (block_once): the first symbol-lookup grep in a session is denied with guidance; subsequent retries are allowed.

It enforces only where an enabled Claude Code plugin provides a language server for the searched file type (from the glob, type or path; for a bare directory target, from the files the directory holds). Elsewhere the default no_lsp_mode: advisory only suggests installing a code intelligence plugin.

IDs: R-LSP-SYMBOL-LOOKUP

Pipe Blocker

Commands piped to tail or head are blocked — piping truncates output and causes information loss.

Do NOT do the theatre of capturing output to a file and then echoing the WHOLE file to stdout — that defeats the point and just bloats tokens.

Preferred — the deployed bin/echd-capture helper: capture the FULL output, see only a preview. Run it by the path below from the project root (the block message prints the absolute form); it is not on PATH, so never type the bare name.

# WRONG — blocked (and truncates):
pytest tests/ 2>&1 | tail -20

# RIGHT — full capture, bounded preview + path to the rest:
set -o pipefail
pytest tests/ 2>&1 | bin/echd-capture 20
# prints the last 20 lines + '(full output: /…/command-output-….txt)'.
# Use --head N for the first N lines. pipefail keeps pytest's exit code visible.

Always-works alternative (no helper, no pipe): pytest tests/ > untracked/scratch/out.txt 2>&1 then read the file selectively. Keep the capture IN-REPO — project_containment denies a redirect to a path outside the repository, and a capture written outside it is gone on the next container restart.

Allowed (whitelisted): grep, rg, awk, sed, jq, ls, cat, git log, git tag, git branch, and other cheap filtering commands.

EVERY pipe in the command is judged, on its own producer. A cheap pipe does not buy cover for an expensive one, so git log | head -2 && pytest | head -1 is blocked on the pytest half. The tail -f / head -c exemptions are also per-pipe — an unrelated && tail -f x elsewhere in the command exempts nothing.

A pipe inside $( ) or backticks belongs to the command INSIDE it. echo $(pytest tests/ | head -1) is blocked on pytest, not allowed because echo is cheap — the output being thrown away is pytest's. Nesting and <( ) behave the same. Whitelisted inner producers are still fine: echo $(git log --format=%H | head -1) is allowed. The single-quoted program of bash -c '...' (also sh, zsh, dash, ksh) is read the same way: its pipes are judged on the command inside, so bash -c 'grep x f | sort | tail -n 2' is allowed and bash -c 'pytest | tail -3' is blocked on pytest. A $( ) or backtick inside SINGLE quotes is literal text, so it is not treated as a substitution. That exemption is about SUBSTITUTION only — an ordinary single-quoted ARGUMENT containing | head is still scanned and still blocked, because the shell can hand that string to something that runs it. The exemptions that do cover a whole value are a git -m/-F message and a quoted-delimiter heredoc.

Only PIPES are restricted — reading a file directly is not. tail -n 40 <file>, head -n 40 <file> and grep pattern <file> take the path as an ARGUMENT, so no pipe exists and this handler never sees them. That is the supported way to sample a large append-only file such as a plan's JOURNAL/ entry files or legacy day-file — which you should tail or grep rather than read whole.

Add to whitelist (if safe to pipe): set extra_whitelist in .claude/hooks-daemon.yaml under pipe_blocker.

A git message VALUE is exempt only while the shell cannot run it. Prose in git commit -m/git tag -m is not scanned, so a literal | tail inside a message never counts as a pipe — but that exemption ends at a command substitution. Bash expands $( ) and backticks inside DOUBLE quotes, so git commit -m "$(pytest | tail -1)" genuinely runs pytest and truncates it, and is blocked on the pytest. Single quotes substitute nothing and are exempt unconditionally, as is the "$(cat <<'EOF' ... EOF)" idiom, whose QUOTED delimiter makes the body literal. The exemption is also scoped to commands that actually take a message: python -m pytest ... | tail names pytest as its producer, because -m there means module.

A quoted-delimiter heredoc is exempt when NOTHING on its line can EXECUTE the body. cat >> notes.md <<'EOF' ... EOF writes its body out verbatim — the shell expands nothing in it — so a | tail sitting in that body was never going to run, and blocking it would be wrong. Quote the delimiter (<<'EOF') whenever the body is prose, a code snippet, or anything else you are writing rather than executing. Where the REDIRECT sits makes no difference: cat > notes.md <<'EOF' and cat <<'EOF' > notes.md are the same command to bash and the same command here, and a delimiter carrying punctuation (<<'EOF-1') counts too.

But bash <<'EOF' IS scanned, because bash EXECUTES the body. The quoted delimiter governs only what the OUTER shell expands on the way in; it never stops the receiving command running the bytes. So the exemption is granted from an allowlist of commands that consume their input as data (cat, tee, git, jq, grep, …), and THREE things must all pass it: the receiver, every stage the body is piped on to (cat <<'EOF' | bash runs it), and the command not sitting in a substitution ($(cat <<'EOF' … ) puts the body's text in command position). Anything else — bash, sh, python3, ssh host, or simply a name the list does not carry — has its body scanned like any other command. Withholding the exemption is the cheap error here: it costs a false positive, where granting one wrongly costs the guard entirely.

An UNQUOTED <<EOF IS still scanned, and that boundary is deliberate. Bash performs command substitution inside an unquoted heredoc, so cat <<EOF with $(pytest | tail -1) in the body really does run pytest and truncate it. A bare | tail in unquoted prose can therefore still false-trigger: when the matched text reads as ENGLISH rather than as a command — it starts with a function word like "the", or such words make up a large share of it — the block reason is short and does NOT echo your text back or suggest a fabricated extra_whitelist entry. Just quote the delimiter and retry, or write prose content with the Write tool instead of a heredoc.

Length is NOT part of that judgement. A long command is still a command: a 100-character invocation with a worktree branch name and absolute paths gets the normal block reason, naming what matched and how to whitelist it. If you ever see the short prose reason for text that really was a command, that is a bug worth reporting — retrying it unchanged will block again.

IDs: R-PIPE-TO-TAIL, R-PIPE-TO-HEAD

sed_blocker — sed is forbidden for file modification

sed is blocked because Claude gets sed syntax wrong and a single error can silently destroy hundreds of files with no recovery possible.

THE RULE IS DENY-BY-DEFAULT, NOT A LIST OF BAD PATTERNS. Any Bash command containing the WORD sed is blocked unless it matches one of the five narrow exemptions below. This framing matters: an earlier version of this guidance listed specific blocked shapes, which read as though anything unlisted was fine. It is not — python3 -c "print('sed')" is blocked, and so is xargs sed 's/a/b/' despite having no -i, no command-head position and no pipe stage.

The five exemptions, in the order they are applied:

1. None of them apply if sed is EXECUTED. sed at a command HEAD (start, or after ;, &&, ||), any flag cluster containing i, e or n, or sed via xargs, is blocked no matter what else is in the command. So grep x f; sed -i 's/a/b/' f is still denied — the grep does not rescue it. Note sed -n '1,20p' file prints to stdout and cannot write, and is blocked anyway — DELIBERATELY, and the deny message says so: -n and -i differ by one character. Read with offset/limit does the same job, as does awk 'NR>=1 && NR<=20' file.
2. A git commit, git merge -m or git tag -m message mentioning sed (sed must follow the git command with no command separator between; git's own global options such as git -C <dir> commit are fine).
3. A gh issue/PR/release body mentioning sed (same separator rule).
4. The command contains a grep, or an echo that does not itself carry a sed 's/…' substitution.
5. A heredoc/redirect whose ONLY write target is a .md file, and whose sed text is never EXECUTED (cat > NOTES.md <<'EOF' mentioning sed in the body is allowed). Checked with the same get_written_file_paths accessor lint_on_edit uses to find what a Bash command AUTHORS, not a second regex over the raw text — so a command that also writes a non-.md target (tee a.md b.sh) or genuinely RUNS sed ($(sed -i …) in an UNQUOTED heredoc body, or a separate ; sed -i … after the redirect) is NOT exempted and stays denied, whatever exemption 1 already covers.

Consequence worth internalising: exemption 4 is a proxy for 'this looks read-only', and it is the reason two commands that BOTH cannot modify a file get opposite verdicts — cat f | sed 's/x/y/' | grep z is allowed while cat f | sed 's/x/y/' | wc -l is DENIED. Nothing about writing distinguishes them; only the presence of grep.

Write/Edit tool (a separate branch, different rule): a .sh/.bash file whose content contains sed is blocked; a .md file is always allowed; any other path is not examined.

The .md exemptions are NARROWER on the Bash branch. Write allows ANY .md path unconditionally. The Bash branch (exemption 5) only allows a heredoc/redirect whose SOLE write target is .md and whose sed is never executed — cat > NOTES.md <<'EOF' mentioning sed is allowed, but cat > x.md <<EOF with $(sed -i …) in an UNQUOTED body, cat <<'EOF' | bash piping the body to an interpreter instead of writing it, a mixed target (tee a.md b.sh), and > x.md; sed -i … chaining a separate executed sed are all still denied. Also still allowed the older way: echo 'avoid sed' > NOTES.md (exemption 4, the echo has no substitution). Write markdown about sed with the Write tool when the shape is more than a plain heredoc/redirect, and none of this applies.

Use instead:

• Edit tool — safe, atomic, verifiable
• Parallel Haiku agents with Edit tool for bulk changes across many files:
  1. Identify all files to update
  2. Dispatch one Haiku agent per file
  3. Each agent uses the Edit tool (never sed)

IDs: R-SED-FILE-MODIFICATION

qa_suppression — QA suppression annotations are blocked

A Write/Edit that puts QA suppression directives into a source file is blocked, across all supported languages. Fix the underlying code issue instead.

Blocked annotation types (by language):

• Python: noqa directives, type: ignore annotations
• JavaScript/TypeScript: eslint-disable inline directives
• Go: nolint directives (golangci-lint, blocked even with a stated reason) and gosec nosec directives
• PHP: phpstan-ignore, psalm-suppress annotations
• Java/Kotlin: @SuppressWarnings, @Suppress annotations
• C#: pragma warning disable directives
• Rust: allow(...) attributes anywhere in the file (item-level #[allow(...)] and crate-level #![allow(...)])

Required action: Fix the code so QA passes without suppression. If a suppression is genuinely necessary, ask the user to add it manually — this signals a conscious decision rather than a shortcut.

Excluded paths: per-language vendor/build/node_modules dirs are skipped by default. Exempt more paths with glob patterns via handlers.pre_tool_use.qa_suppression.options.exclude_paths or the project-wide daemon.exclude_paths — use these for fixtures that must contain suppression annotations.

IDs: R-QA-SUPPRESSION

plan_number_helper — use mkplan.bash to create a plan

Before creating one, check nothing already covers it. Dispatch the hooks-daemon-plan-dedupe-scout agent with a sentence describing the intended work; it reads the still-live plans and names any that already cover it, so you can merge or supersede instead of filing alongside. This is a SUGGESTION — it never blocks, it is a judgement call rather than a rule, and it can be wrong. It is worth the few seconds because the alternative failure is expensive and silent: a duplicate plan is usually discovered only after an agent has spent a lot of context re-deriving conclusions that already existed on disk.

Check its count against one you did not get from it. The report carries a Checked N live plans. line, and the agent can only reconcile that against its own enumeration — which is no check at all when the enumeration is what went wrong. Measured on this agent: 34, then 32, then 17 plans reported for the same unchanged tree of 34. So state the number of plan folders in the plan root when you dispatch it (mkplan.bash prints it for you), and when the report's N disagrees, re-dispatch rather than act on the verdict — a scout that read a different tree has not answered your question.

To create a new plan, run the deployed scaffolding script:

CLAUDE/Plan/mkplan.bash "descriptive-kebab-name"

Hand-creating the folder is BLOCKED. mkdir <plan-dir>/NNNNN-name is denied when the scaffolder is deployed: mkdir claims a number the moment the folder appears, but nothing records the claim until PLAN.md is written, so a concurrent agent reading the counter in between gets the SAME number and the collision surfaces only at the commit gate. This is narrow — mkdir <plan-dir>/Completed, a JOURNAL/ inside a plan that already exists, and a -p re-create of an existing folder are all allowed, as is any path outside this workspace.

(Use the project's configured plan directory if it is not CLAUDE/Plan/.) The script takes a lock, reads the same authoritative git counter (hooksdaemon.latestPlanNumber), assigns the next number atomically, creates the NNNNN-name/ folder, scaffolds PLAN.md, and advances the counter — so concurrent runs can never collide on a number. It prints the new folder path on stdout. You still add the README index row yourself (the script reminds you).

If you only need the number (not a folder), read the counter, then take the higher of the counter and the highest plan on disk — this is the fallback, not the primary path:

git config --local hooksdaemon.latestPlanNumber

Take the higher of the counter and the highest plan number on disk (Completed/ included), then add 1 (zero-pad to 5 digits, e.g. highest 117 → next plan 00118). The counter is per clone, so on its own it lags a plan made in another clone; mkplan.bash and the daemon both take that higher value.

Do NOT scan CLAUDE/Plan/ with ls/find/glob pipelines to discover the next number. Folder scans miss plans in Completed/ and other subdirectories, and disagree across branches. The folder scan is only used to bootstrap the counter when the git key is unset (which mkplan.bash and the daemon both handle). Listing a path INSIDE one numbered plan folder (CLAUDE/Plan/00554-x/JOURNAL/) names a single plan, is not a number discovery, and is allowed.

To FIND an existing plan — a different question from the next number, and the one a folder scan is usually reaching for:

bin/hooks-daemon find-plan 412
bin/hooks-daemon find-plan "jobs"

It searches the WHOLE tree including Completed/, which is precisely what a folder scan misses, and prints each plan's number, status and path.

IDs: R-PLAN-NUMBER-DISCOVERY, R-PLAN-FOLDER-MKDIR

sensitive_content — blocked patterns and secret terms are never written

A Write/Edit whose content matches a configured public pattern or a gitignored secret word list is blocked. Two sources, two different disclosure rules:

Public patterns (handlers.pre_tool_use.sensitive_content.options.public_patterns): named regexes. The deny reason names the pattern and WHERE it matched (file path and line, the git field, or the gh body) but never the matched text, because the reason is written to the transcript.

Secret word list (options.secret_word_list_path, default .claude/block-words.secret, gitignored): a term never appears anywhere — not in the deny reason, not in any log, not in payload capture, not in a transcript archive. The deny reason names only an index (entry N of M in the secret word list), which is meaningless without the gitignored file. Do NOT try to guess or work around the block, and do NOT open the secret word list file — it is itself read-protected by secret_file_guard (Plan 00272); ask the user what the entry covers. Only the ADDED text is checked on Edit (new_string) — removing sensitive content is never blocked.

Git metadata is checked too. File contents and file PATHS are only two of the seven places a term can enter a repository — the other five are git metadata, and none of them is a file write. So a Bash command that records metadata is also checked: git commit (messages), git tag (names and messages), git branch / checkout -b / switch -c (branch names), git config user.name|user.email (author identity), git merge -m. A match denies the command.

A Bash command that writes a FILE is NOT checked at write time; the git commit that would RECORD it is. A Bash command that writes a file (cat > f <<EOF, >, >>, tee, mv, cp) reaches disk unexamined — no block, no advisory, no record — so the commit is the gate: the ADDED lines of every staged file (the working tree for git commit -a) are scanned at commit time, and a match denies the commit naming only the file path and the pattern name or entry index, never the line. Removing a term is never blocked (only added lines count), binary blobs are skipped, and a file whose added lines exceed 512 KiB — or a commit past 4 MiB in total — is stood down with a log line rather than scanned partially. git push is NOT a surface: it carries nothing a commit did not, and a denied commit is never pushed. Still prefer Write/Edit for file content so the block lands before the bytes do.

A gh body is checked like a commit message. gh issue comment, gh pr comment, gh issue|pr create and gh issue|pr edit publish a body to GitHub, which no history rewrite can retract, so an inline --body/-b value and the content of a --body-file/-F <file> are both scanned. A body file is named by path only. gh api is not covered (its -F is a field), and a body piped on stdin (-F -) cannot be judged — write it to a file instead.

Reading is never blocked. Only commands that WRITE metadata are candidates, so grep, cat, git log --grep=, git show, git branch --list and git tag -l stay allowed even when the term is right there on the command line — searching for a term and removing it are exactly the work of cleaning a repository.

If a compound command is denied because an unrelated part of it carries a term (grep <term> f && git commit -m 'clean'), split it into two calls rather than trying to disguise the term.

Missing/empty/comments-only secret file = this source is inert. A list the config names but which is missing is reported once at SessionStart by secret_file_hygiene_checker.

IDs: R-SENSITIVE-PUBLIC-PATTERN, R-SENSITIVE-SECRET-TERM

security_antipattern — OWASP security antipatterns are blocked

A Write/Edit of code containing security antipatterns is blocked, across all supported languages. Fix the code to use safe patterns instead.

Blocked categories:

• Code injection: eval, exec, new Function, __import__, instance_eval, yaml.load — dynamic execution of a string
• Command injection: os.system, subprocess(..., shell=True), shell_exec, proc_open, Runtime.exec, Process.Start, IO.popen
• Unsafe deserialization: pickle.load, Marshal.load, unserialize, ObjectInputStream, XMLDecoder, BinaryFormatter
• XSS: innerHTML, dangerouslySetInnerHTML, document.write, template.HTML/JS/URL
• Hardcoded credentials: AWS access keys, GitHub tokens, Stripe keys, private key blocks

This is pattern matching on known-dangerous constructs, not analysis. It does NOT detect SQL injection, weak hashing, or path traversal — those are properties of how a value FLOWS, which a regex cannot see. Do not read a passing write as 'this code is secure'.

Supported languages: Python, JavaScript/TypeScript, Go, PHP, Ruby, Java, Kotlin, C#, Rust, Swift, Dart. Coverage varies by language — a construct blocked in one is not necessarily blocked in another.

Excluded paths: vendor/, node_modules/, and test fixtures are skipped by default. Exempt more paths with glob patterns via handlers.pre_tool_use.security_antipattern.options.exclude_paths or the project-wide daemon.exclude_paths.

IDs: R-SEC-CODE-INJECTION, R-SEC-CMD-INJECTION, R-SEC-DESERIALISATION, R-SEC-XSS, R-SEC-HARDCODED-CREDS, R-SEC-UNSAFE-MEMORY

tdd_enforcement — test file must exist before source file

A Write that creates a production source file (a path that does not exist yet) is blocked until a corresponding test file exists. A Write that overwrites an existing file is treated like an Edit and is not gated.

TDD workflow (required):

1. Create the test file first (e.g. tests/unit/handlers/test_my_handler.py)
2. Write failing tests — RED phase
3. Create the source file and implement until tests pass — GREEN phase
4. Refactor — REFACTOR phase

Supported languages: Python, Go, JavaScript/TypeScript, PHP, Rust, Java, C#, Kotlin, Ruby, Swift, Dart

Test file locations checked (any satisfies the block):

• Separate mirror: tests/unit/{subdir}/test_{module}.py
• Maven/Gradle source set: src/main/<lang>/<pkg>/Foo.kt -> src/test/<lang>/<pkg>/FooTest.kt (Java/Kotlin)
• Collocated: {source_dir}/{module}.test.ts (JS/TS projects)
• Test subdirectory: {source_dir}/__tests__/{module}.test.ts

The separate-directory forms are searched in BOTH casings — tests/ and Tests/. On a case-sensitive filesystem those are different directories, and the uppercase form is the PHP/PSR-4 convention, so do NOT rename a project's Tests/ to satisfy this gate. Only INFERRED locations get both casings; a directory you DECLARE (below) is searched exactly as you wrote it.

The deny message lists every location it searched. If your project's real test directory is not in that list, no amount of retrying will satisfy the gate — the project needs to DECLARE the directory (below), not move the test.

A layout the resolvers cannot infer is declarable via handlers.pre_tool_use.tdd_enforcement.options.test_path_map — a list of {source_glob, test_dir, mirror?} entries. test_dir is repository-root-relative (an absolute path is rejected). By default it is FLAT: the test filename is placed directly in it. With mirror: true the source's directory path after the glob's literal root (src for src/**) is reproduced under it, which is how a nested size-suite layout (tests/Small/<mirror>, tests/Large/<mirror>) is declared. Every declared root is searched and listed. This keeps enforcement ON and is the preferred fix, because a test that exists is worth more than an exemption:

test_path_map:
  - source_glob: "**/qaConfig/PHPStan/Rules/**"
    test_dir: "apps/app/qaConfig/Tests"
  - source_glob: "src/**"
    test_dir: "tests/Small"
    mirror: true

A nested layout.test_dirs entry is a mirror root already. layout.test_dirs: ["tests/Small", "tests/Large"] makes the gate search tests/Small/<mirror after src/>/<TestName> (and Large) with no test_path_map entry at all; a bare name such as e2e only classifies.

A path can also be exempted entirely via that handler's exclude_paths option or the project-wide daemon.exclude_paths — additive gitignore-style globs. Prefer test_path_map: excluding turns the gate OFF for those files.

Allowed through without blocking: vendor dirs, node_modules, build outputs, generated files, and file extensions not in the supported language list.

IDs: R-TDD-TEST-FIRST

error_hiding_blocker — error-suppression patterns are blocked

A Write/Edit of code that silently swallows errors is blocked. All errors must be handled explicitly.

Blocked patterns (examples):

• Python: bare except clauses with an empty body, catching and discarding all exceptions, and suppress(...) naming Exception or BaseException (also in a tuple); a narrow suppress(OSError) is allowed
• Shell: redirecting stderr to /dev/null to silence failures, || true to suppress non-zero exit codes
• JavaScript/TypeScript: empty catch blocks that swallow exceptions
• Go: if err != nil {} (empty error check, also when the body is only a comment), and a blank in the LAST position of an assignment from a FUNCTION CALL — n, _ := strconv.Atoi(s) — which is where Go returns the error. Not blocked: _, err :=, comma-ok forms (v, _ := m[k], x, _ := y.(T)), for i, _ := range, the explicit _, _ = f() discard, and anything inside a comment or string literal.

Required action: Handle errors explicitly — log them, return them to the caller, or propagate them. Silent error suppression masks bugs and makes debugging impossible.

Excluded paths: vendor/, node_modules/, and test-fixture dirs (tests/fixtures/, tests/assets/, fixtures/) are skipped by default. Exempt more paths with glob patterns via handlers.pre_tool_use.error_hiding_blocker.options.exclude_paths or the project-wide daemon.exclude_paths — use these for fixtures of deliberately-broken code instead of disabling the handler.

IDs: R-ERROR-HIDING

comment_changelog — no changelog narrative in code comments

A Write/Edit that puts HISTORICAL NARRATIVE into a code comment is blocked. A comment describes CURRENT STATE; changelog narrative belongs in git (the commit message), the project's changelog file, or a plan journal entry (mkplan.bash --journal).

Blocked (high-precision) signals, either of which denies the write:

• Prior <version>: / Previously <version>: phrasing
• a dated entry (2026-08-12: ...)

Both were measured with ZERO false positives across this project's own ~1,080 source/test files (Plan 00208's whole-repo self-scan) — every real hit was either the field-report shape itself or this handler's own test fixtures.

NOT blocked — advisory only: a version-transition arrow (1.2 -> 1.3), a changelog verb naming a version (Removed in v2.1.224), two or more distinct versioned/dated entries in one comment (configurable via max_history_entries, default 1), Fixed:/Added:/Changed: bullet runs, retrospective phrasing (used to, no longer, we switched from). These four started as blocking signals but the same self-scan found each firing on legitimate code — version-processing utilities (upgrade compatibility checkers) legitimately cite multiple versions in their own docstrings, and "removed in vX.Y" describing an EXTERNAL tool's own deprecation is rationale, not a changelog entry about this project.

History as RATIONALE is legitimate and is NOT flagged. A comment may recount the past when the past is the reason the code looks the way it is now, and re-litigating it would reintroduce a fixed bug — e.g. # Plan 00047: do NOT re-add DISABLE_MOUSE, see.... The separating test: an entry keyed by a RELEASE NUMBER is a changelog; an entry keyed by a FAILURE MODE (a plan number, a bug description) is a rationale.

No escape hatch — unlike comment_size, this handler has no MUST_..._BECAUSE override: changelog content should be MOVED to git/a changelog file/a plan JOURNAL/, never exempted in place.

Scope: only comment spans are scanned (not code), via the same Strategy Pattern language registry as qa_suppression. .md files are skipped entirely — markdown prose is not a comment. Only the ADDED text is checked on Edit (new_string) — removing changelog content is never blocked.

Excluded paths: vendor/build/fixture dirs are skipped by default. Exempt more paths via handlers.pre_tool_use.comment_changelog.options.exclude_paths or the project-wide daemon.exclude_paths.

IDs: R-COMMENT-CHANGELOG

Stop Explanation Required

Before stopping, prefix your final message with STOPPING BECAUSE: followed by a clear reason:

STOPPING BECAUSE: all tasks complete, QA passes, daemon restart verified.

Why: The stop hook enforces intentional stops. Stopping without an explanation triggers an auto-block that asks you to explain or continue.

Alternatives:

• STOPPING BECAUSE: <reason> — stops cleanly with explanation
• Continue working — no need to stop unless all work is genuinely complete

Do NOT:

• Stop mid-task without explanation
• Ask confirmation questions and then stop (the hook auto-continues those)
• Smuggle a rhetorical continue question inside a STOPPING BECAUSE: message ('STOPPING BECAUSE: slice 1 done. Want me to build slice 2?') — this is HARD-BLOCKED; the prefix does not exempt tautological questions. Just continue with the next unit of work
• Use AUTO-CONTINUE unless you intend to keep working indefinitely

Before asking a question, evaluate it critically:

• Tautological/rhetorical questions with obvious answers ("Should I continue?", "Would you like me to proceed?") — do NOT ask, just do it
• Errors with a clear next step ("The test failed, should I fix it?") — do NOT ask, just fix it
• Genuine choice questions where all options are valid ("Which of A, B, or C should we use?") — these deserve a response. Use STOPPING BECAUSE: need user input and ask your question

Recovering from a tool_use_error — do NOT stop silently:

Some tool errors require an explicit recovery action, not a halt. The most common shape:

• You call Edit or Write on a file you have not yet read.
• Claude Code returns a tool_use_error (e.g. "File has not been read yet").
• The correct recovery is Read the file, then retry Edit/Write — do not stop. Stopping silently after a tool error triggers a Stop-hook re-entry loop and wastes a turn.

Rule: Read before Edit/Write. If you must edit a file you have not read, Read it first in the same turn. The daemon's Stop handler will detect a tool_use_error followed by a silent stop and re-fire to force recovery.

On Stop hook re-entry (the hook fires again after a prior block): your next response is treated like any other — it must either prefix with STOPPING BECAUSE: or continue the work. Re-entry does not exempt you from the explanation rule.

If you are stopping because you are blocked ONLY on the human, declare it — it turns the failsafe cron and every declared persistent_crons job off. Put the token immediately after the prefix:

STOPPING BECAUSE: [awaiting-human] the owner has to choose between A and B before anything else can move.

The token is matched exactly, so any wording after it works. These older phrasings are also still recognised, and are kept working rather than extended — a new wording is handled by the token, not by adding another phrase here:

• blocked only on human input
• blocked only on the owner's input
• need user input
• waiting only on the user's decision

Either form in your STOPPING BECAUSE: line records a marker that makes the daemon drop the next hourly failsafe-cron tick, and every declared job's tick, before it reaches you, at zero token cost. Another cron's tick never clears it, provided its prompt still carries the daemon's [tick:...] first line. Without one, every tick costs a full turn to read and answer with nothing. The next real user message clears the marker and hourly ticks resume; it also expires on its own, so a mistake here costs you at most a day of ticks. The marker is the awaiting-human session mode, ended only by a human prompt in THIS session; every mode and what it suppresses: CLAUDE/SessionModes.md.

Only when it is the ONLY thing blocking you. A stop that merely mentions waiting on someone while other work remains must not use these shapes — that would silence a tick you could have used. If there is work you could still do, do it instead of stopping.

An [awaiting-human] stop must also schedule a one-off stand-in. With persistent_crons.enabled, a main-thread stop that declares it is blocked on the human is denied until session_crons holds a cron led by [tick:stand-in]; the deny gives the exact CronCreate (recurring: false, about options.stand_in_delay_hours = 3 hours out, valid above 0 and below 24). If the marker is still live when it fires, a model: fable sub-agent picks among the options you laid out and the choice is journalled as the stand-in's ruling, never the owner's. It may choose only engineering options: releases, force and remote-branch deletes, QA suppressions, history rewrites, upgrade approvals and anything a guard says to ask the user stay blocked. The stand-in tick is not dropped by the live marker, and a sub-agent or teammate stop is never asked for one.

IDs: R-STOP-QA-FAILURE, R-STOP-TAUTOLOGICAL-QUESTION, R-STOP-AFTER-TOOL-ERROR, R-STOP-CONFIRMATION-QUESTION, R-STOP-NO-REASON, R-STOP-GOAL-LEDGER, R-STOP-STAND-IN-MISSING

All other enforced rules

Advisories and other active handlers

One line each; these fire with their own guidance when relevant. Full text: bin/hooks-daemon explain-handler <name>.

• agent_isolation_advisor — isolate concurrent agents

• agent_terminated_early_failure_detector — a dead foreground sub-agent is surfaced on PostToolUseFailure

• autonomy_notice — autonomy is off in this environment

• background_process_tracker — backgrounded processes are tracked

• branch_sweep — branches that need attention

• branch_touch_recorder — who created and who touched a branch

• budget_exhaustion_detector — hidden agent budgets are surfaced

• ccy_supervisor_integrity — keep the ccy supervisor properly set up

• cleanup_after_merge — a merged branch is cleaned up after the merge

• command_hints — advisory reminders after specific commands

• daemon_restart_verifier — restart the daemon before committing

• daemon_sync_after_merge — a pull can leave the daemon stale

• deployed_artefact_drift — a deployed file has moved away from its template

• docs_qa_sweep — documentation drift report at session start

• evacuation_recorder — an evacuated worktree or branch stays protected this turn

• failsafe_cron_session_advisor — the failsafe cron from session start

• flaggable_work_advisor — delegate flaggable work BEFORE reading it

• focus_mode_trigger — hooks-daemon focus <task> points one session at one task

• git_hooks_executable_fixer — auto-fixes non-executable git hooks

• git_upstream_checker — additive fetch + pull/cleanup advice on session start

• goal_injection — plan-start goal signal for the ccy supervisor

• hook_registration_checker — hooks configuration policy

• idle_housekeeping_advisory — report-first idle housekeeping (beta, opt-in)

• markdown_table_formatter — markdown tables are auto-aligned

• merge_qa_advisor — merge a work branch with its targeted QA recorded

• merge_qa_report — post-hoc plan/docs QA report after a merge

• model_downgrade_recorder — the automatic model downgrade is written down

• model_fallback_detector — silent model substitution is surfaced

• nitpick.dismissive_language — do not deflect or prematurely halt

• nitpick.hedging_language — the guessing is the defect, not the wording

• operator_signal_notice — a host reboot or shutdown warning reaches you mid-turn

• persistent_cron_assertor — declared crons are re-established each session

• plan_qa_sweep — plan-tree drift report at session start

• plan_status_snapshot — pre-write PLAN.md status snapshot

• plan_workflow_asset_checker — plan tooling provisioning alert

• plan_workflow — PLAN.md, supporting docs and JOURNAL/ obey DIFFERENT contracts

• project_handler_load_checker — project protection degraded alert

• recovery_cron_advisor — failsafe recovery cron lifecycle advisory

• reference_repo_sweep — reference clones are made fresh before you read them

• routine_qa_sweep — recurring work that has stopped recurring

• secret_file_hygiene_checker -- on-disk hygiene for protected paths

• session_actions_directive — the must-do list is delivered as a turn

• standing_authorisations — a project can record a standing request

• subagent_report_persistence — every sub-agent reply is saved to a file

• tool_disable_advisor — declared never-want tools are checked at session start

• worktree_create — semantic worktree naming