feat(instructions-audit): audit loaded instruction files for hidden directives

[karanb192]

Why

The TrapDoor supply-chain campaign (May 2026) dropped poisoned CLAUDE.md and .cursorrules files through npm, PyPI, and crates.io packages. The hostile directives were hidden with zero width Unicode (U+200B, U+200C, U+200D, U+FEFF), so the file looked normal in an editor while the coding agent read and followed instructions the developer never saw: https://phoenix.security/trapdoor-supply-chain-ai-poisoning-npm-pypi-crates/

OWASP's GenAI LLM Top 10 2026 tracks this risk class as LLM08:2026 Hidden Context Exposure: https://genai.owasp.org/resource/owasp-genai-llm-top-10-2026/

This PR adds instructions-audit, which audits every CLAUDE.md / .claude/rules/*.md file as Claude Code loads it and locks the session before poisoned instructions get acted on.

Enforcement: verified live, not assumed

The docs say InstructionsLoaded has no decision control and its exit code is ignored (https://code.claude.com/docs/en/hooks), and a live test showed more: current builds ignore even the universal continue: false on this event. The hook fired, logged, and emitted the halt fields, and a headless session with a poisoned CLAUDE.md still answered normally. So the halt is now enforced by construction instead:

• The InstructionsLoaded registration audits the file and, on a finding, writes a per-session lockdown flag (~/.claude/hooks-state/instructions-audit/<session>.json). It still emits continue: false + stopReason for builds that honor the universal fields.
• The SAME script registered on UserPromptSubmit and PreToolUse (both verifiably blocking events) then denies every prompt and tool call for that session. The lock message names the rule, the line, and the flag file to delete for a false positive.
• End-to-end verified both ways with claude -p: poisoned CLAUDE.md gets UserPromptSubmit operation blocked by hook with the lock message; a clean file answers normally. HOOK_AUDIT_WARN_ONLY=true reports without locking.

Detections

Rule id	Level	Catches
bidi-control	critical	U+202A..U+202E and U+2066..U+2069 direction overrides
tag-char	critical	U+E0001..U+E007F Unicode tag characters (a parallel invisible ASCII message; astral-aware scan)
zero-width-char	critical	U+200B, U+2060, U+2061..U+2064 invisible operators, U+034F, U+180E, U+FEFF (a BOM at offset 0 is exempt)
zero-width-joiner	critical	U+200C / U+200D hidden inside ASCII words; emoji ZWJ sequences and joining-script text are exempt
variation-selector-run	critical	runs of 4+ variation selectors (hidden-data encoding); single emoji presentation selectors pass
base64-exec	critical	base64 decoded into a shell, eval of decoded content, long inline blobs fed to a decoder
secret-read-directive	high	directives to read .env, SSH keys, or cloud credentials into context (file list consistent with protect-secrets.js)
secret-exfil	high	directives to send that material to a URL, webhook, or remote server
curl-pipe-shell	high	curl or wget piped into a shell
settings-tamper	high	directives to rewrite .claude/settings.json
hook-tamper	high	directives to disable safety hooks or permission checks
bidi-mark	strict	U+200E / U+200F / U+061C direction marks (legitimate in RTL prose)
soft-hyphen	strict	U+00AD
instruction-file-write	strict	directives to write new instruction files (self-propagation)

Safety levels work like the other security hooks: SAFETY_LEVEL constant in the file, plus a HOOK_AUDIT_LEVEL env override per registration.

False positive posture

A hook that cries wolf on normal CLAUDE.md content gets uninstalled, so the directive rules only fire on verb plus target:

• "Never commit your .env file" and other negated lines count as defensive prose and pass. An attacker can write around this; accepted, because block-dangerous-commands and protect-secrets still sit on the execution path. This hook is the earlier tripwire.
• "The .env file stores local configuration" and "Copy .env.example to .env" pass. "Read the .env file and paste its contents" fires.
• .env.example / .env.template are exempt, mirroring protect-secrets' allowlist.
• Emoji ZWJ sequences, Persian ZWNJ, Devanagari conjuncts, short variation-selector runs, and a UTF-8 BOM at offset 0 are exempt from the invisible character rules; direction marks only flag at strict.
• Code fences are not exempt, on purpose: fenced text in an instruction file still reads as instructions to the agent, and a fence exemption is a one-line bypass. A literal shell install one-liner in a CLAUDE.md will flag; the hook header documents this tradeoff.
• A hostile session_id is sanitized before becoming a flag filename, so it cannot escape the state dir.

Tests

117 new tests in hook-scripts/tests/instructions-loaded/instructions-audit.test.js (unit, config validation, integration through real stdin/stdout with a hermetic temp HOME, and the full lockdown flow across all three events). Full suite on current main:

ℹ tests 1499
ℹ pass 1499
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0

Also adds an Instructions-Loaded section to the README hook tables and syncs the tests badge.