feat(tools): tool results return handles by default above a size threshold (#440)

[justrach]

Closes #440. The generalization of #409, and the core of graff's answer to "context as variables" without adopting a Python kernel: the filesystem is the namespace, bash is the REPL, both of which graff already has.

The finding this fixes

A live A/B eval showed #409's spill path is effectively dead code for the local toolset. Three caps sat in series, and layer 2 reduced every execTool result to 2,000 chars, so layer 3's ~136 KB send-time threshold was unreachable for bash/read_file/webfetch/codedb. Across 12 runs against a 168 KB log, including a forced cat, the spill never fired once.

The contract

Above a threshold, a tool result returns, uniformly and at tool time: a bounded preview, a durable handle (absolute path), the byte count, and a one-line shape hint (line count for text, top-level keys for JSON). The model slices what it needs with read_file/grep/bash instead of carrying the payload turn after turn.

What happened to the three caps

layer	verdict
tool_preview_chars 2000 + persistToolResult	Removed, replaced by tool_handle.zig. It was the handle idea without the payload information that makes a handle actionable: path only, no size, no shape. Same on-disk namespace, so nothing is orphaned. Paths are now absolute, which also fixes a latent bug where a worktree-isolated subagent (#276) could never open the old relative path.
bash_stdout_cap 128 KiB	Demoted to a capture ceiling and raised to 1 MiB; codedb's 64 KiB context truncation removed. Both destroyed bytes purely to protect context, which the handle now does non-destructively. At 128 KiB the handle would have lied for exactly the measured case: a quarter of that 168 KB log was already gone before anything could be written down. runCapped buffers incrementally, so this is a ceiling, not an allocation.
perOutputCap / capOversizedToolOutputs / tool_spill	Kept, narrowed to a documented backstop. effectiveThreshold(perOutputCap()) clamps the tool-time threshold at or below the send-time cap, so the two are ordered by construction rather than stacked. What can still reach the backstop is a session resumed from a pre-#440 build, whose stored outputs never met this contract; deleting the pass would mean destroying those bytes.

Threshold default is 4096 bytes, knob GRAFF_TOOL_HANDLE_BYTES (0/unparseable ignored, so the contract cannot be silently disabled). Verified to sit above the tier-2 eval case whose 4001-byte outputs must stay whole to drive compaction. Prompt guidance ships as a capability-gated segment per #421, so it contributes zero bytes under --no-local-tools.

Verification

zig build test → 1048/1048, exit 0 (baseline 1043; +6 new, −1 removed, which proves the new module's tests are actually reachable). scripts/eval-tier1.sh fully green.

Beyond unit tests, this was driven end to end through the real harness against a mock Codex: a 20 KB read_file came back as a handle with preview ≤ 4096 bytes, an absolute path, the exact byte count, and shape hint 1 lines, and the on-disk file was byte-for-byte equal to the payload.

Behaviour changes worth knowing

1. The marker text changed. Anything parsing [full tool result: … — inspect with read_file] breaks; the only in-repo consumer was updated.
2. Handle paths are absolute rather than .graff/tool-results/... relative.
3. Per-result preview budget goes 2000 → 4096 bytes, and is now constant per result.
4. A bash command emitting 128 KiB–1 MiB no longer reports [stdout truncated at 128 KB]; it yields a complete handle.
5. .graff/tool-results/ can grow faster. Bounded by a new 64 MiB per-process budget with an honest truncation marker, but there is still no GC sweeper for that directory. Pre-existing gap, filed separately.

Not measured: the 1 MiB capture ceiling's memory behaviour under real load is reasoned from incremental reads, not benchmarked. src/session_run.zig sits at 599/600 lines, so the next change there needs an extraction first.