perf(post-tool): give PostToolUse the #227 env-cache fast path

[fdaviddpt]

Closes #350 (part 1 only — the save-session.sh position sidecar is deliberately not here; see "What is not in this PR" below).

The problem

scripts/post-tool-hook.sh registers with no matcher, so it runs after every single tool call and the agent blocks on it. Every invocation sourced the whole chain unconditionally — resolve-paths.sh → detect-tools.sh → bootstrap-dirs.sh → log.sh — which is a git rev-parse, a slug, a three-layer config merge, a one-pass flatten, and a python3 -V spent only to validate an interpreter.

The reporter measured 750–1000 ms per tool call on Windows 11 / Git Bash, against ~90 ms for user-prompt-hook.sh on the same machine — the hook that already replays. Their measurement is a claim I did not reproduce (no Windows box); I re-measured the shape on macOS and it holds there too.

The change

The #227 fast path now covers this hook. When lib-env-cache.sh can replay a published resolution and no executable listener is installed under hooks.d/after_post_tool/, the chain is skipped.

Observed, macOS / bash 3.2.57, external spawns per warm tool call:

fixture	before	after
no save yet	14 spawns / 336 ms	6 / 130 ms
a save behind it	15 spawns / 405 ms	8 / 248 ms

The first tool call of a session — and the first after any config edit — still takes the whole chain, and now publishes it, so the cost is paid once per project per config change instead of per tool call.

The objection #227 raised, answered rather than dropped

tests/test_post_tool_hook_spawns.py says in its own docstring why #227 skipped this hook: it needs config(), and therefore the merged config file, "caching which is a materially bigger risk than caching a handful of paths". That is right, and the merged config file is still never cached — it can carry a live haiku.oauth_token, which is why lib-memory-dir.sh creates it 0600 per PID under an EXIT trap (#232/#68).

What is cached are the two scalars log.sh resolves out of it — cooldowns.save_seconds and thresholds.delta_lines_trigger — in the same 0600 file that has carried REMEMBER_TZ since #227, under the same config-mtime invalidation, with the same "required, not defaulted" upgrade rule #301 gave REMEMBER_PROMPT_STAMP. A cooldown and a line threshold are neither secret nor expensive to be one prompt stale about.

Four things that were easy to get wrong

The gate asks for an executable, not a directory. user-prompt-hook.sh tests [ ! -d hooks.d/after_user_prompt ] and gets away with it because the distribution ships no such directory. It does ship hooks.d/after_post_tool/.gitkeep (checked: git ls-files hooks.d), so the same -d test here would have refused the fast path for every user who never installed a listener — which is all of them. It asks what dispatch() asks, from one shared definition, so the gate and the dispatch cannot come to disagree about whether a listener exists.

PYTHON is not replayed. lib-env-cache.sh validates config mtimes and environment identity; it does not validate binaries, and it was not asked to. detect-tools.sh is sourced at the one site that needs an interpreter — reading the saved position, which a store only reaches once a save has landed — so the Microsoft Store alias that passes command -v and fails -V is still caught by exactly the check that has always caught it.

log is upgraded, not stubbed. dispatch is stubbed, because the gate only let us in when there is nothing to dispatch to. log is different: the branches that call it are the ones where this hook is malfunctioning — a slug matching no session directory (#144) — and dropping those diagnostics to save a process is #144 arriving inside its own fix. The first call sources log.sh; the runs that never take those branches never pay for it.

That upgrade has to install a no-op when log.sh cannot be sourced at all, and the obvious guard — type log — is true on macOS regardless, because /usr/bin/log is Apple's unified logging CLI. Found by running it: the hook execed that binary once per diagnostic, printed nineteen lines of log: Unknown subcommand 'hook', and exited 64 from a hook documented "EXIT CODES: 0 Always". It asks declare -F.

The #200 wiring marker survives a store with no tmp/. bootstrap-dirs.sh is what creates $REMEMBER_DIR/tmp. tmp/post-tool-ran is how /remember:doctor answers "is PostToolUse wired at all", so it now creates the directory on the failing write rather than assuming one. Silently skipping it would tell users a wired hook had never fired — the exact regression #200 fixed.

Also done by hand, because the fast path skips whatever set them: the #204 nested-summarizer guard, umask 077 (#68), SYS_TMPDIR, REMEMBER_HOOKS_DIR, and bootstrap-dirs.sh's exec 2>> into hook-errors.log — without that last one a diagnostic lands in front of the user instead of in the log.

Tests

tests/test_post_tool_fast_path_350.py, 13 cases, written before the implementation and watched failing (9 red, 2 green-for-the-right-reason). Every "the chain did not run" assertion is paired with a positive control in the same fixture:

• the spawn budget, with the cold run asserted to spawn git and jq (so "no git, no jq" on the warm run is evidence of something) and the warm run asserted to spawn ls (so it is evidence of a hook that ran);
• the threshold and the saved position, each parametrised both ways — a value that must suppress the fork and one that must produce it, because only asserting the first passes on a hook that stopped forking altogether;
• the session_dir_slug() mis-slugs non-ASCII (CJK) paths under byte-wise sed, silently disabling saves #144 diagnostic, with the inverse control that a healthy run says nothing;
• the Silent no-op when the plugin is enabled mid-session: PostToolUse never registers, no error surfaced #200 marker with tmp/ deleted, the False "previous session was not captured" warning fires on every /clear #206 per-session marker, the Nested Haiku summarizer re-triggers the plugin's own hooks, creating a spurious $TMPDIR-slug memory directory #204 guard with a control run beside it, .gitkeep not disabling the fast path, an executable listener taking the slow path and being dispatched, and clean stdout/stderr.

Two of them have their negative controls recorded rather than assumed: reverting log() to a stub and reverting declare -F to type each make the corresponding test fail, and I ran both.

A helper (_fast_path_run) establishes fast-path-ness from the spawn log rather than from EnvCacheProbe.assert_warm, because against a cache primed by another hook the probe answers warm for the slow path too — it cannot tell "replayed" from "never looked".

Two adjacent tests were measuring paths they did not name, and now say which. tests/test_post_tool_hook_spawns.py counted a second run of the same fixture, which after this change is the warm one — and whether it was warm at all depended on which side of a whole second two writes landed on (#303). It pins REMEMBER_ENV_CACHE=0 and is now explicitly the cold-path file. TestFreshProjectBootstrap::test_detect_before_bootstrap compared the first mention of two filenames anywhere in a hook, comments included; it now reads the source statements, with the premise (both are in fact sourced) asserted rather than assumed. test_case_divergence_298 pinned two hot-path libraries to origin/main byte for byte and so failed on a comment — the very comment that had become false; it now compares code lines only, verified still to catch a renamed function.

Full suite: 1590 passed, 43 skipped, coverage 92.95%.

What is not in this PR

Part 2 of the issue — having save-session.sh write a plain-integer tmp/position.<session_id> sidecar so pipeline.shell read-position stays off the hot path. It is worth about 2 spawns and ~118 ms per warm tool call on my machine, and it introduces a second source of truth for a position last-save.json already holds; a sidecar that disagrees with it produces a wrong delta silently. That is a separate argument and deserves its own issue.

Platform

Everything measured above is observed on macOS 24.3.0 / bash 3.2.57. Every bash test in this repo skips on win32, so the Windows CI leg does not execute any of this, and no Windows machine was available.

One claim is reasoned, not observed, and is written down above _after_post_tool_listener in the code: MSYS fakes the execute bit, and if Git Bash ever reported the shipped mode-0644 .gitkeep as executable, the fast path would never fire on Windows. That would be slow, not wrong — the slow path is today's behaviour exactly — and dispatch() has shipped the identical [ -x ] test for many releases, so it would already be trying to execute that file on every Windows tool call, which nobody has reported. One command in a real Git Bash session settles it: [ -x hooks.d/after_post_tool/.gitkeep ] && echo YES.

Also reasoned: CRLF in the cache file is stripped before the new digits-only guards, so a corrupted value falls back to the chain rather than reaching $(( )). SYS_TMPDIR and umask 077 are byte-identical replays of the expressions already in bootstrap-dirs.sh and resolve-paths.sh.

[fdaviddpt]

Part 2 of #350 — the tmp/position.<session_id> sidecar — is filed as #353 with the measurement it is worth (~2 spawns / ~118 ms per warm tool call, observed on macOS) and the argument against shipping it as-is. This PR closes #350; #353 is where that half continues.