perf(claude-ops): audit only transcript lines appended since last Stop - #4192
Conversation
…ields without jq run-guards.sh sources its guards into its own shell instead of one command-substitution subshell per guard: `exit` is a dispatcher function that records the guard's status and runs the next guard from inside the call, stdout documents are collected through hook::emit_document, and a guard that dies of a hard error hands its status to the abort boundary's new chain slot (_GAB_CONTINUE), which runs the guards still owed in one subshell. Per-invocation analysis state (the alias memo) is reset before each guard, so a later guard's alias walk is not answered by an earlier guard's memo. lib/hook-utils.sh answers a well-formed payload's plain-string fields with its builtin JSON parser (hook::_fast_fields) and runs jq only for a shape it cannot prove; hook::jq_fields_uncached names the same body for the dispatcher's cache, hook::emit_document is the one stdout path, and hook::extract_bash_subject_to is the in-shell telemetry subject. The 17 carrying plugins take the synced copy with a patch bump. Measured on Windows 11 + Git Bash with an exact job-object census of the harness's own invocation: the Bash-lane chain went from 23 process creations to 3 and 880 ms to 285 ms isolated p50; the PowerShell lane from 100 to 80 creations and 3.3 s to 2.7 s. Decisions are byte-identical (rc, stdout, stderr) against 0.33.11 over the perf baseline's 17-command corpus in both tool modes, over 653 commands harvested from the guard suites on the Bash lane and 200 on the PowerShell lane, and over the Write, Edit and drive-root-tmp lanes. Handoff item: 20260913-034031 (program 20260915-153000). Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
hook::extract_bash_subject_to assigns SUBJECT through a nameref, which shellcheck 0.11 cannot follow; CI's lint lane failed SC2154 on the two guards that read it in emit_tel. Declaring the variable empty first is the idiom block-hook-bypass already uses. block-no-verify 256/0 and flag-commit-pr-skill-bypass 35/0 unchanged. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The Stop hook re-read the whole tail window on every turn: a `wc`, a `grep`, and the library's stdin validation probe fired before it could learn that nothing new had failed. The transcript is the session's own JSONL and grows every turn, so no mtime or size sentinel on the file can answer "nothing new to audit" — the signal has to be about the appended content. A per-session cursor beside the warning marker records how many transcript lines have been audited. A later Stop reads only the lines past it with `mapfile`, pre-filters them with the same fixed string the grep used, and exits having created no process. The cursor advances only once the lines it covers are disposed of: no candidate, an empty structural selection, nothing left unwarned, or a warning emitted. A jq failure leaves it where it stood. Missing, malformed, pruned, ahead of a shortened transcript, or recorded against a different transcript_path all reset it to a full rescan, and a rescanned line cannot re-warn because the (hookName, command) marker still decides that. Job-object process accounting on Windows Git Bash, five runs per arm against a 3-creation harness floor (`bash -c`, `env`, `bash`): turn with no new failure 10 -> 3 (the floor: the hook creates nothing) first Stop of a session 10 -> 5 (7 when the data dir is created) turn with a failure 30 -> 21 Wall clock is not the record here — the same before-arm measured 0.36 s and 1.38 s an hour apart on this host — but the after-arm held 0.23-0.36 s across both runs where the before-arm ran 0.36-1.38 s. Findings are unchanged byte for byte. Proven by diffing this hook's output against the pre-change script over five fixtures (single record, three mixed classes, several registrations with both false-positive shapes, an over-cap transcript, a last line with no trailing newline) and over a two-turn incremental sequence; the suite now asserts the same equality in-tree, plus a PATH shim that fails loudly if any of jq/grep/wc/tail/sed/find/cat/mkdir runs on a second Stop. The payload fields now ride on `hook::buffer_stdin_to`, which fuses the library's `jq -e .` probe into the field read. That is why this branch first merges guardrails-run-guards-in-process-no-subs, which carries PR #4185's lib/hook-utils.sh sync: `hook::jq_fields` answers plain-string payload fields (transcript_path, session_id) with a builtin parser and spawns no jq. `hook::require_jq` moves after the fused call, because without jq the library returns an empty field array and reading it under `set -u` would kill the hook rather than fail open. The cold path keeps the tail cap — it is the one read the cursor cannot bound — and pays one `wc -lc`, which answers the cap decision and the cursor's starting line count in a single process. Bumps claude-ops 0.56.14 -> 0.56.15. The sibling branch claude-ops-session-event-log-spawns-whil (PR #4189) also bumps claude-ops to 0.56.14, so whichever lands second needs its entry renumbered. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
CI's machine-specific-paths hygiene check refuses a Windows user path in a fixture. The value is opaque to the parser under test; hook-utils 504/0 unchanged. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ps-hook-failure-audit-sets-the-s
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 6m 28s —— View job Claude finished the
|
|
Claude finished @kyle-sexton's task in 1m 35s —— View job Security review (
|
|
Last security-reviewed head: |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d41207a57c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
plugins/claude-ops/*.md is declared purged in scripts/em-dash-purged-paths.txt, so the lint lane treats one as a regression. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ty lint The shell-portability lint reads the backslash-w in the previous spelling as a GNU-only regex class. The value is opaque to the parser under test. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
hook-failure-audit.sh validated the cursor's line count with a bare
^[0-9]+$ test, so a value like 08 passed but then failed bash's
octal-reading ((...)) arithmetic (08/09 error outright; a long enough
digit string wraps silently). Either way the Stop hook stopped running
its scan cleanly.
Tighten the check to ^(0|[1-9][0-9]{0,14})$: a canonical decimal capped
at 15 digits, well under 2^63. Anything else is rejected outright, not
coerced with 10#, and falls through to the existing CURSOR=0 cold-scan
path exactly like any other malformed cursor.
Adds cursor tests for a leading-zero value and a 20-digit value: no
shell diagnostic, a cold scan runs, and the cursor is rewritten to a
canonical value afterward. Adds a CHANGELOG bullet under claude-ops'
existing 0.56.15 entry.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…ts key bound hook::_fast_fields indexes the payload's key strings with an associative array, which Bash added in 4.0, and it ran on every hook::jq_fields call. On the 3.2 shell macOS ships, and which these hooks document support for, `local -A` fails per call. hook::_fast_fields_supported is the predicate, split out the way hook::read_supports_nchars is so a test can force the below-floor branch on a modern host, and hook::jq_fields_uncached asks it before entering the fast path. Below the floor jq answers, unchanged. The index loop also skipped any string body longer than a fixed 60 bytes before decoding it, while nothing capped the key names a caller may ask for. Two wrong answers came out of that: a requested key longer than 60 characters was proven ABSENT while present, and a key of 11 or more characters spelled with \u escapes (hook_event_name is 15, 90 escaped) was missed the same way. The bound is now six times the longest requested key name, the width of `\uXXXX` per identifier character, which is the bound the header comment always described. The suite gains four cases: the below-floor branch forced with the fast path replaced by a tripwire, a present 70-character key, an absent one, and hook_event_name spelled entirely in \u escapes. Each compares the fast path against jq rather than against an expectation. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The chain-slot paragraph asks a function plugged into _GAB_CONTINUE to be builtins only, never exit, and never touch the trap, and the slot's own comment says it must not return. run-guards.sh's consumer does none of that: run_guards::guard_died forks a subshell for the guards still owed, spawns jq to merge their documents, and ends at `builtin exit`. Say so. run-guards.sh is the one documented exception, and it is one because it is the dispatcher finishing the run the process owes rather than a hook doing exit-time work. The discipline is unchanged for everyone else, and the slot comment now matches it: a chained function that returns hands control back and the handler settles the status. Comment only. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…lliding plugins Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The base branch merged origin/main and renumbered its own claude-ops bump to 0.56.15, colliding with this branch's 0.56.15. This branch's two entries move to 0.56.16, above the base branch's hook-utils 0.56.15 and main's 0.56.14, and plugins/claude-ops/.claude-plugin/plugin.json now reads 0.56.16. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…anged (#4193) No related issue: handoff-inbox item 20260913-034032 under program item 20260915-153000 (spawn budget per tool call); no GitHub issue was filed. Stacked on #4185 (base branch `guardrails-run-guards-in-process-no-subs`): the envelope parse rides on that PR's `hook::jq_fields` builtin parser in the synced lib. GitHub retargets it to main when #4185 merges. ## Summary context-guard's `zone-crossing-inject.sh` fires on every `PostToolBatch` and `UserPromptSubmit`. Each fire spawned a jq for the envelope and then the zone resolver (its own bash plus a jq) even when nothing the resolver reads had changed since the last fire, which is the common case: the statusline snapshot is rewritten only when the statusline renders. ## Fix - An unchanged-input skip. A `$STATE_DIR/$SESSION.seen` mark records the inputs behind the last completed resolve in two ways: its mtime, stamped with a redirection and compared with `-nt`, and one flags line (`z=<0|1> c=<0|1>`) recording whether `zones.json` and the compaction marker existed when that resolve ran, read back with builtin `read`. The fire exits before starting a process only when the per-session snapshot, `zones.json` and the compaction marker are all no newer than the mark AND both existence flags still match the current `-e` results; a mark with no readable flags line never takes the skip. The mark moves only after the resolve persisted its markers, so a resolver failure, an `unknown` reading and a failed marker write are each retried next fire. A missing snapshot is never skippable. Skipping can only choose silence: no arrangement of timestamps or existence changes can manufacture an injection the full path would not have made. - The envelope parse is size-branched. Under 64 KiB it goes through `hook::jq_fields`' builtin parser (zero spawns); above it keeps the single here-string jq (2 creations), because the helper's oversize fallback reads through a process substitution and measured 4. Plain routing through the helper would have made the large-payload path 9 to 11 creations; the branch is what keeps every cell at or below before. The `65536` literal mirrors the helper's private proof ceiling and is documented at the site. - `STATE_DIR` resolution moves ahead of the resolver, so a session with no state root exits one process earlier. context-guard is bumped 0.7.64 to 0.7.65 with the numbers in the CHANGELOG, and the README gains a "Skipping the resolve when nothing moved" subsection carrying the table. ## Verification Job-object census (n=5, identical across reps; subject floor 3 = `bash -c`, `env`, bash): | Fire | Payload | Creations before | Creations after | |---|---|---|---| | first (resolves) | small | 11 | 9 | | repeat, nothing moved | small | 9 | 3 | | snapshot rewritten | small | 9 | 7 | | first | 150 KB | 11 | 11 | | repeat, nothing moved | 150 KB | 9 | 5 | | snapshot rewritten | 150 KB | 9 | 9 | No cell is worse than before. Small repeat fire wall p50 1448 ms to 237 ms (re-run 365 ms; the host is bimodal). On Windows a resolve costs 4 creations rather than 2 because `bash "$RESOLVER"` hits the `bin\bash.exe` wrapper, which re-spawns `usr\bin\bash`. Crossing messages are byte-identical, asserted in the suite against a control session driven through the same zone sequence with no skipped fire. Suite: `zone-crossing-inject.test.sh` 78/1 to 97/2, where both failures are `strace: no usable trace` on this host (Git Bash's cygwin strace rejects `-e trace=`; the second is the new strace block, not a regression); `zone-gate` 26/0, `post-compact-mark` 18/0. shellcheck clean; `check-changelog-parity.sh --check-bump origin/main` and `--check` green. Residuals: the strace pins (steady fire 0 creations / 1 execve; resolving fire 2 / 3) are set by reasoning and verified only on CI's Linux lane. The one miss window is the resolve itself: a snapshot written between the resolver's read and the stamp is marked seen and its crossing is reported one fire late, never lost, since the statusline rewrites the snapshot on its next render; on a filesystem or bash build that compares mtimes at whole-second granularity the window is up to one second. The README still carries the older "0.7.49 brought it to 3" paragraph; the new subsection supersedes it. ## Related - #4185 (base of this stack). Program item 20260915-153000; siblings #4188, #4189, #4190, #4191, #4192. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
…ump claude-ops to 0.56.17 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
No related issue: handoff-inbox item 20260913-034033 under program item 20260915-153000 (spawn budget per tool call); no GitHub issue was filed.
Stacked on #4185 (base branch
guardrails-run-guards-in-process-no-subs): this hook rides on that PR'shook::buffer_stdin_tofield read in the synced lib. GitHub retargets it to main when #4185 merges.Summary
claude-ops'
hook-failure-audit.shStophook set the per-turn wall: it re-scanned the whole session transcript on every stop (awc, agrep, a jq over every candidate) to discover that no newhook_non_blocking_errorrecord had appeared, which is the common case.Fix
${CLAUDE_PLUGIN_DATA}/hook-failure-audit/<session>.cursor, holds the count of complete lines already audited and thetranscript_pathit was taken against, beside the existing warning marker and under the same 7-day prune.Stopreads withmapfile -sfrom one line before the cursor (that line is an anchor: the same read that fetches new lines proves the file still has that many; an empty result means shrinkage), prefilters candidates in bash with the same fixed string the grep used, and runs jq only for a candidate line.mapfileruns without-tso joined candidates are byte-identical to$(grep …); a final line with no newline is scanned but not counted, so it is re-read next turn.transcript_path, fewer lines than the cursor, pruned cursor, or bash withoutmapfile(the old grep path). It advances only at the four disposal points (no candidate, empty summary, nothing new, after the system message); a jq failure leaves it put. Rescanning cannot re-warn, because the marker still decides that.wc -lcnow answers both the cap decision and the cursor's starting line count.hook::buffer_stdin_to INPUT '.transcript_path' '.session_id', which fuses the library's validation probe into the builtin field read;hook::require_jqmoves after it.claude-ops is bumped 0.56.14 to 0.56.15 with the numbers in the CHANGELOG. Sibling #4189 also claims 0.56.14 on its branch; whichever merges second needs its version and CHANGELOG re-based (parity is checked against origin/main).
Verification
Job-object census (n=5, Windows Git Bash; floor 3 =
bash -c,env,bash):Wall clock after 0.23 to 0.36 s where before ran 0.36 to 1.38 s across two runs; the host drifts about 4x within an hour, so the creation count is the record.
Byte identity, old versus new hook on fresh data dirs, identical stdout: a single record; three mixed classes; multiple registrations plus both false-positive shapes; an over-cap transcript; a last line without a trailing newline; and a two-turn incremental sequence where turn 2 appends a failure past the cursor. The suite asserts the same in-tree: incremental turn-2 output equals a full rescan against identical marker state.
Suites:
hook-failure-audit.test.sh84/4 to 94/4 (10 new assertions; the 4 failures are pre-existing on this host, a Windows CRLF artefact injq … @tsvonHAS_COMPLETED). Discrimination checked: the jq PATH-shim test fails against the old hook, and the path-reset test fails against a copy with the path check removed. Degraded paths: a no-mapfilecopy warns then dedups, an unwritable marker home still warns, an empty transcript is silent. shellcheck, shfmt, markdownlint andcheck-changelog-parity.sh --check-bump origin/mainclean.Unproven: the strace budget block runs only on CI's Linux lane; the warm ceiling (0 creations, 0 execs) follows from the Windows census at floor, the cold ceilings (6 creations, 2 execs) are conservative estimates and are what to adjust if CI reports otherwise. The bash 3.2 fallback was exercised by forcing
HAVE_MAPFILE=0, not on a real bash 3.2. An over-cap cold scan sets the cursor from the whole file's line count while reading only the last 2 MB; pre-window lines were never read before either, and the cursor makes that permanent for the session.Related
🤖 Generated with Claude Code