refactor(tool): centralize MAX_OUTPUT_BYTES in ToolRegistry::run

[hakula139]

Summary

Per-tool truncation was hand-rolled and incomplete: bash and read enforced the 128 KB byte cap; glob / grep / edit / write did not. A pathological grep response (250 rows × 500 chars before per-line overhead is 125 KB; long paths can push glob past 128 KB too) could flood the model context past the intended ceiling, and a future MCP-tool plug-in would have to re-implement the cap or trust the model not to drown.

This PR lifts the byte safety net into the dispatcher. New cap_output runs head-tail truncation (lifted from bash) so the model still sees both setup context and final outcome; new ToolRegistry::run wraps Tool::run with the cap. Per-tool view-shape budgets (row caps, line-length caps) stay where they are; the two layers separate "tool-semantic budget" from "absolute byte ceiling".

The two leading commits are research surveys (cherry-picked from docs/tool-research) framing the design — tool-truncation.md covers this PR; file-tracking.md scopes a separate companion workstream (Read-before-Edit gates, staleness detection) so the implementation here stays a focused refactor.

Design decisions

• Two layers, not one. View-shape (per-tool, semantic — "show 250 grep matches", "first 2000 read lines") and byte-budget (centralized, safety net) are separate concerns. Combining them forces every tool to know about bytes, which is what we're trying to escape.
• Head-tail, not tail-only. Preserves both setup context (file headers, command echo) and final outcome (error message, last lines) — the two pieces models most often need to reason about.
• Two distinct metadata fields, not one overloaded signal. truncated_total carries view-shape match counts (set by per-tool caps like glob's MAX_RESULTS); truncated_bytes carries pre-cap byte counts (set only by the registry). Splitting keeps glob's (X of N matches) from accidentally rendering bytes when both layers fire — plausible in deep monorepos with long paths.
• No spillover to disk for v1. opencode-style "use Grep on /tmp/spill.txt" needs a Task agent to consume the spilled file; oxide-code has none. Revisit when Task lands.
• MAX_OUTPUT_BYTES = 128 KB unchanged. Don't tune in the same PR that restructures responsibility.

Changes

File	Description
tool.rs	New // ── Output Cap ── section co-locates MAX_OUTPUT_BYTES, TRUNCATION_OVERHEAD, and cap_output next to the dispatcher with a two-layer preamble. ToolRegistry::run wraps Tool::run, applies the cap, and stamps metadata.truncated_bytes (separate from view-shape's truncated_total). Trait Tool::run doc tells implementations not to pre-truncate by bytes. Tests cover cap_output boundaries (short / head-tail / multibyte at split / barely-over) and the dispatcher path (overflow, within-cap, unknown-tool, byte-cap-on-read fallthrough to Text view). parse_input picks up #[expect(clippy::result_large_err)] since the new field tipped ToolOutput past clippy's threshold.
agent.rs	Dispatch swaps match tools.get(...) { Some(t) => t.run(...).await, None => Unknown-tool error } for tools.run(&name, input).await. Unknown-tool fallback now lives in the registry.
tool/bash.rs	Drop truncate_output and the boundary tests; the dispatcher's cap_output is the new home.
tool/read.rs	Drop the mid-loop byte-budget; row cap (DEFAULT_LINE_LIMIT) and per-line cap (truncate_line) keep view-shape bounded; (Showing lines N–M of TOTAL total) footer stays as a view-shape signal. split_read_footer doc explains the intentional asymmetry with glob's metadata-driven approach.
model.rs	Drive-by: collapse the #[expect] reason on Capabilities to a single line — matches the convention used by the other 10 #[expect] sites in the crate.
docs/research/tool-truncation.md (new)	Per-tool vs centralized output caps, head / tail vs spillover, why the dispatcher owns the byte safety net while per-tool view-shape budgets stay.
docs/research/file-tracking.md (new)	Companion survey for a deferred follow-up (Read-before-Edit gates, mtime / content staleness, persist-on-finish + verify-on-resume).
docs/research/README.md	Registers both new surveys.
docs/research/anthropic-api.md, docs/research/extended-thinking.md, docs/research/session-persistence.md, docs/research/system-prompt.md, docs/research/tui.md	Reference-project name normalization across older surveys (claude-code repo path → Claude Code product; codex-rs directory → OpenAI Codex product). Repo paths in code references stay as-is.
docs/roadmap.md	Drop the now-shipped "Centralized output truncation" Current Focus bullet.
.cspell/words.txt	Adds tengu and toks (introduced by tool-truncation.md).

Test plan

• cargo fmt --all --check
• cargo build compiles cleanly
• cargo clippy --all-targets -- -D warnings — zero warnings
• cargo test — 1196 passed
• cargo llvm-cov --ignore-filename-regex 'main\.rs' — 98.55% workspace line / 98.49% on tool.rs
• pnpm lint / pnpm spellcheck — 0 issues

Out of scope

• File-change tracking (Read-before-Edit gates + mtime / content staleness detection). Survey doc lands here; implementation is a separate workstream — see docs/research/file-tracking.md for the design notes.
• Spillover-to-disk for over-cap output. Needs a Task agent to consume the spilled file before the hint is useful.
• Tuning MAX_OUTPUT_BYTES. Carries over from the bash-era cap; revisit based on observed model behavior.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!