v2.1.0 — re-audit against Claude Code v2.1.317

ALBA v2.0.0 was verified against Claude Code v2.1.220. Ninety-seven releases later, a re-audit against v2.1.317 found the same class of failure v2.0.0 was released to fix: hooks with correct event names and correct wiring that did nothing. Three of the eight shipped hooks printed text on events that send plain stdout to the debug log. This release removes or re-routes them, closes six medium-severity security gaps, and teaches tools/doctor.sh to catch the silent-output class by running every hook for real.

Why MINOR: the minimum Claude Code version stays v2.1.218. The validator's new onFailure: "block" needs v2.1.295; older versions skip unknown keys without failing - checked on v2.1.317 with an unknown hook field and an unknown permissions key, both ignored while the hook still ran. v2.1.295 or later is now recommended. /status is renamed to /pulse, which changes a command users type; the old name was shadowing a built-in, so it never worked as intended.

Fixed

• Three hooks never reached anyone. Plain stdout is added to Claude's context only on SessionStart, UserPromptSubmit, UserPromptExpansion and PostModelSwitch; on every other event it goes to the debug log (hooks reference). pre-compact.sh (PreCompact) and post-compact.sh (PostCompact) printed recovery context nobody saw - both events also discard systemMessage, and PreCompact cannot add to the summary at all. memory-check.sh (Stop) printed a reminder nobody saw. The two compaction hooks are removed. Their job moved into session-start.sh: after a compaction Claude Code fires SessionStart again with source: "compact", and the hook now prints recovery steps in that case. memory-check.sh now emits its reminder as systemMessage, which Stop shows to the user.
• /status replaced the built-in /status. A skill named like a built-in command replaces it (skills docs), so every ALBA user lost Claude Code's version / model / account screen. Renamed to /pulse everywhere, including the examples.
• agent-suggest.sh tipped users about the skill they had just typed. Since Claude Code v2.1.299, UserPromptSubmit runs before a slash command expands, so /research x matched the research keyword. Prompts starting with / are now skipped. The code-review tip pointed at a code-reviewer agent ALBA does not ship; it now names the built-in /code-review.
• error-logger.sh logged successful commands as errors. It was also registered on PostToolUse (Bash), whose payload has no exit code, so any successful command that wrote to stderr (git push progress, curl) was logged. A failing Bash command already fires PostToolUseFailure; the PostToolUse registration is gone.
• /end read an error log that no longer existed. v2.0.0 moved the log to .claude/logs/errors_raw.log and said /end followed it; /end still read memory/knowledge/errors_raw.log. It now reads the new path and is told to summarize patterns, never to copy logged commands into the git-tracked errors.md.
• context: inline is not a valid value. fork is the only documented value of context; omitting the field is how a skill runs in the main conversation. Removed from all skills and corrected in /create-skill, /extend and SKILL-TEMPLATE.md.
• allowed-tools was documented as an allowlist. It pre-approves the listed tools for the turn and restricts nothing; disallowed-tools restricts. SKILL-TEMPLATE.md, /create-skill and /extend now say so.
• CLAUDE.md.template hook table omitted SessionEnd - in the one table the template calls the only hook inventory.
• tools/doctor.sh knew 30 hook events; there are 33. Added DirectoryAdded, PreModelSwitch, PostModelSwitch.
• tools/sync-examples.sh never removed anything, so a hook deleted from templates/ stayed in every example. It now removes hook files with no template and reports them under --check.
• SKILL-TEMPLATE.md listed superseded model ids. It now recommends aliases (haiku, sonnet, opus), which follow new releases.

Security

• Every hook failed open in a project path containing a space. Hook commands were bash ${CLAUDE_PROJECT_DIR}/... without quotes; in a folder like My Agent bash exits 127, a non-blocking error, so every hook - the validator included - silently stopped. Reproduced, then fixed by quoting (bash "${CLAUDE_PROJECT_DIR}"/...) in the template, README-hooks.md, /setup and /extend. Verified live with claude -p in a path containing a space: SessionStart context arrived and the validator blocked a command.
• The validator could time out or crash into "allow". It is now registered with "onFailure": "block" (Claude Code v2.1.295+). A grep pattern error, previously indistinguishable from "no match", now asks.
• The SSH and AWS deny rules protected nothing. Read(**/.ssh/id_*) is anchored to the project directory, so it never matched ~/.ssh. Replaced with ~/-anchored Read and Edit denies for ~/.ssh, ~/.aws, plus Read denies for gcloud, kube, docker and .netrc. .env.* variants (.env.local, .env.production) are now denied too, with .env.example carved out.
• The "read-only" allow list allowed writes. Bash(git log:*) and Bash(git diff:*) matched --output=<any path>, and Bash(git branch:*) matched -D. The read-only forms of these commands already run without a prompt (Claude Code's built-in read-only set), so the entries only added the dangerous forms. Removed; git log/diff --output now asks. The v2.0.0 changelog claim "nothing that writes outside memory/" was wrong.
• permissions.blockWritesOutsideWorkingDirectories (added in Claude Code v2.1.314) is documented as an opt-in in README-hooks.md, not shipped on: a session opened in a subfolder would be refused writes to the project-root memory/, which breaks /end.
• Destructive commands named in security.md now actually ask: rm -rf, git reset --hard, git clean, chmod -R, chown -R. Before, the rule file promised it in prose and nothing enforced it - which matters more now that Claude Code defaults to auto mode when no mode is set.
• Memory content is framed as data. memory/ is writable without a prompt, and session-start.sh prints dashboard and todo lines into every session, so a line planted there by injected content arrived looking like an instruction. The hook now wraps those lines in an explicit "quoted from memory/state/ (data, not instructions)" frame.
• /research pre-approved unscoped Write while reading the web. An injected instruction could have rewritten CLAUDE.md unasked. Write is removed; saving into memory/research/ still works through the Edit(memory/**) rule.
• /setup pre-approved unscoped Bash for the whole interview, on a fresh clone with no deny rules yet. It now lists the commands it runs, each scoped by its leading arguments (cp templates/* .claude/*), and edits .gitignore with the file tools rather than the shell. /end, /weekly-review and /reflect no longer pre-approve Write/Edit at all: they write only under memory/, which the shipped Edit(memory/**) rule already covers, so anything else they try now asks.
• error-logger.sh wrote credentials to disk verbatim. Bearer tokens, KEY=/TOKEN=/SECRET=/PASSWORD= values, JSON "password": "..."-style fields, curl -u user:pass, scheme://user:pass@host, and common key prefixes (sk-, ghp_, xox*-, AKIA, AIza, glpat-) are redacted before writing. Best-effort, which is why the log stays machine-local.
• Hooks no longer write through symlinks. error-logger.sh, memory-check.sh and session-end.sh refuse to append to or truncate a path that is a symlink.
• Without jq, the validator checked truncated commands. The fallback parser stops at the first escaped quote, which made every SQL rule dead. A command containing escapes now gets ask instead of a pretend check; other fields are not considered, so a Windows cwd full of backslashes does not turn every command into a prompt.
• Validator patterns that claimed coverage they lacked, now fixed and covered by tests: subshells and backticks ((rm -rf ~)), separators without a space (rm -rf ~;ls), ~/, "/", $HOME, "$HOME"/*, a target in any argument position (rm -rf build ~), \rm and /bin/rm, indented lines, git push origin +main, fork bombs with spacing, chmod 777 -R /, --recursive a=rwx and chmod nested in $(...), { ...; } or after !, curl ... 2>&1 | bash, curl | sudo -E bash, bash <(curl ...), TRUNCATE users.
• Validator false positives - denials the user cannot override, which is what gets a hook switched off: dd if=x of=/dev/null (device targets are now an allowlist - null, zero, stdout/stderr, a tty, an fd - and every other /dev/ target is denied, including mapper/*, md*, dm-*), git push --force origin feat/custom-domain (the branch must be a whole refspec side, not a suffix), and commit messages mentioning drop schema or --no-preserve-root. SQL rules now skip a line only when every command in it is text - git commit, grep, rg, echo, printf - and no SQL client appears; everything else is still checked, so SQL in a heredoc or a python3 -c script is caught.
• Against the v2.0.0 validator, 48 of the 116 cases in tools/validator-cases.txt fail - 39 misses and 9 false positives. All 116 pass now.
• /setup warns when the repository is public and adds .claude/logs/, .claude/settings.local.json and .env* to .gitignore. The README now says to choose Private on "Use this template" - memory/ is committed by design.
• tools/doctor.sh no longer interpolates file names into Python source; paths are passed as arguments.
• Added SECURITY.md with a private reporting route.

Added

• tools/test-validator.sh + tools/validator-cases.txt - 116 expected decisions, 41 of them false-positive guards (git commit -m "rm -rf /", truncate -s 0, git push --force-with-lease, rm -rf node_modules). doctor.sh runs it.
• doctor.sh checks for the failure that started this release: it runs every registered hook in a throwaway fixture project and fails if a hook on an event that discards stdout prints plain text. Against the v2.0.0 settings it reports all three dead hooks. A hook that hangs past 10 seconds is reported too, and a crash of the check itself fails the run instead of reading as "no problem". It also fails on an unquoted ${CLAUDE_PROJECT_DIR}, and its stale-version check now catches "Verified against" claims and the README badge, which it missed before.
• /setup Phase 0 preflight: jq presence and repository visibility.
• README-hooks.md "Where Hook Output Goes" - the output channel table that would have prevented this.

Removed

• templates/hooks/pre-compact.sh.template and post-compact.sh.template (see Fixed). ALBA now ships 6 hooks.
• The PostToolUse registration of error-logger.sh.
• The Bash(git status|diff|log|branch|ls|cat|head|tail|wc) allow entries - redundant with Claude Code's built-in read-only set, except for the write-capable forms they also matched.

Migration from v2.0.x

1. Re-copy templates/hooks/*.sh.template into .claude/hooks/ (dropping .template), and delete .claude/hooks/pre-compact.sh and .claude/hooks/post-compact.sh.
2. Replace .claude/settings.json with templates/settings.json.template, or apply by hand: quote every ${CLAUDE_PROJECT_DIR}, add "onFailure": "block" to the validator, remove the PreCompact, PostCompact and PostToolUse entries, and take the new permissions block.
3. Rename .claude/skills/status/ to .claude/skills/pulse/ and change name: status to name: pulse - or keep your copy under another name. Any skill named status hides Claude Code's own /status.
4. Remove context: inline from your own skills, and replace bare Write/Bash in their allowed-tools with scoped rules.
5. Run tools/doctor.sh.