feat: the capture spine — response fidelity, binary-safe replay, and a per-call capture

README.md

@@ -168,8 +168,25 @@ the launcher's own share is attributable.
 | `check`       | + config load, trust resolution, one-rule tree         | 2.3 ms | 2.7 ms | —        |
 | `hook`        | + envelope decode, adjudication, decision write        | 2.8 ms | 3.0 ms | ≤ 100 ms |
 | `passthrough` | a call no rule selects — decode, allow, no config load | —      | —      | ≤ 100 ms |
+| `posttool`    | a PostToolUse call — decode, capture the response      | —      | —      | ≤ 100 ms |
 | `wired`       | the hook as `.claude/settings.json` invokes it         | 8.0 ms | 8.4 ms | ≤ 100 ms |
 
+`posttool` is the same envelope decode plus the response capture, and its cells
+are `—` for `passthrough`'s reason: the series above comes from a quieter
+machine, and a figure from a noisier one published in that column reads as a
+step change rather than as a different room. Measured against its own
+contemporaneous `hook` on one container, 100 runs each, the capture costs
+**1.25x at p50 and 1.12x at p95** — 16.3 ms and 21.1 ms against that machine's
+own 13.0 ms and 18.9 ms for `hook`, so about **5x inside** the 100 ms budget on
+a noisy container and further inside it on the machine the table above reports.
+
+`perf-compare` reads a different pairing and gets a different number, and both
+are honest: it runs this arm against the MERGE BASE's binary, which performs no
+capture at all, so its 1.806x prices the feature rather than a drift in the cost
+of the same work. That arm carries an exemption in `perf-compare` until `main`
+holds a capturing binary and the comparison is like with like; the absolute
+budget is what gates it in the meantime.
+
 100 ms is the [Command Line Interface Guidelines'][clig] floor for a response
 that reads as instant. It is an absolute ceiling rather than a tight band around
 the measured value: a shared runner's p95 moves by more than a percentage band

completions/batten.bash

@@ -820,7 +820,7 @@ _batten() {
             return 0
             ;;
         batten__subcmd__capture__subcmd__list)
-            opts="-J -q -v -y -h --stream --json --strictness --fail-on-warning --config-from --silent --quiet --verbose --debug --trace --log-level --no-color --no-input --yes --help"
+            opts="-J -q -v -y -h --stream --calls --json --strictness --fail-on-warning --config-from --silent --quiet --verbose --debug --trace --log-level --no-color --no-input --yes --help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -876,7 +876,7 @@ _batten() {
             return 0
             ;;
         batten__subcmd__capture__subcmd__show)
-            opts="-J -q -v -y -h --lines --grep --json --strictness --fail-on-warning --config-from --silent --quiet --verbose --debug --trace --log-level --no-color --no-input --yes --help"
+            opts="-J -q -v -y -h --lines --grep --raw --bytes --json --strictness --fail-on-warning --config-from --silent --quiet --verbose --debug --trace --log-level --no-color --no-input --yes --help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -890,6 +890,10 @@ _batten() {
                     COMPREPLY=($(compgen -f "${cur}"))
                     return 0
                     ;;
+                --bytes)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
                 --strictness)
                     COMPREPLY=($(compgen -W "permissive standard strict" -- "${cur}"))
                     return 0

completions/batten.fish

@@ -170,6 +170,7 @@ complete -c batten -n "__fish_batten_using_subcommand capture; and not __fish_se
 complete -c batten -n "__fish_batten_using_subcommand capture; and not __fish_seen_subcommand_from show list prune help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l lines -d 'A 1-indexed inclusive line range, `FROM:TO`, clamped to the capture' -r
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l grep -d 'Only lines containing this literal substring' -r
+complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l bytes -d 'A 0-indexed half-open byte range, `FROM:TO`, either side omittable, clamped to the capture' -r
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l strictness -d 'Raise how strictly gates apply (an override may only tighten policy)' -r -f -a "permissive\t'Advisory: findings are reported without failing the run'
 standard\t'The default: a finding is a violation'
 strict\t'Everything `Standard` fails on, plus anything advisory'"
@@ -180,6 +181,7 @@ normal\t'The default'
 verbose\t'Explain what is being checked'
 debug\t'Add resolution detail'
 trace\t'Add everything'"
+complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l raw -d 'Write the selected bytes to stdout verbatim, with no decode and no added newline'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -s J -l json -d 'Emit byte-stable JSON instead of pointer lines'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l fail-on-warning -d 'Promote a warn-severity finding to a violation (an override may only turn this on)'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from show" -l silent -d 'Say nothing but a verdict or a usage error'
@@ -202,6 +204,7 @@ normal\t'The default'
 verbose\t'Explain what is being checked'
 debug\t'Add resolution detail'
 trace\t'Add everything'"
+complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from list" -l calls -d 'List recorded calls instead of stored captures, in a byte-stable order'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from list" -s J -l json -d 'Emit byte-stable JSON instead of pointer lines'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from list" -l fail-on-warning -d 'Promote a warn-severity finding to a violation (an override may only turn this on)'
 complete -c batten -n "__fish_batten_using_subcommand capture; and __fish_seen_subcommand_from list" -l silent -d 'Say nothing but a verdict or a usage error'

completions/batten.zsh

@@ -193,6 +193,7 @@ trace\:"Add everything"))' \
 _arguments "${_arguments_options[@]}" : \
 '--lines=[A 1-indexed inclusive line range, \`FROM\:TO\`, clamped to the capture]: :_default' \
 '--grep=[Only lines containing this literal substring]: :_default' \
+'--bytes=[A 0-indexed half-open byte range, \`FROM\:TO\`, either side omittable, clamped to the capture]: :_default' \
 '--strictness=[Raise how strictly gates apply (an override may only tighten policy)]: :((permissive\:"Advisory\: findings are reported without failing the run"
 standard\:"The default\: a finding is a violation"
 strict\:"Everything \`Standard\` fails on, plus anything advisory"))' \
@@ -203,6 +204,7 @@ normal\:"The default"
 verbose\:"Explain what is being checked"
 debug\:"Add resolution detail"
 trace\:"Add everything"))' \
+'--raw[Write the selected bytes to stdout verbatim, with no decode and no added newline]' \
 '-J[Emit byte-stable JSON instead of pointer lines]' \
 '--json[Emit byte-stable JSON instead of pointer lines]' \
 '--fail-on-warning[Promote a warn-severity finding to a violation (an override may only turn this on)]' \
@@ -235,6 +237,7 @@ normal\:"The default"
 verbose\:"Explain what is being checked"
 debug\:"Add resolution detail"
 trace\:"Add everything"))' \
+'--calls[List recorded calls instead of stored captures, in a byte-stable order]' \
 '-J[Emit byte-stable JSON instead of pointer lines]' \
 '--json[Emit byte-stable JSON instead of pointer lines]' \
 '--fail-on-warning[Promote a warn-severity finding to a violation (an override may only turn this on)]' \