fix(security): never auto-share a read_terminal snapshot the safety model did not fully see

[jonathanKingston]

Closes #2280.

What was wrong

The read_terminal screen judged the trailing 6000 characters of a snapshot, then shared the whole snapshot on a confident "safe". Anything above the window travelled unexamined whenever the tail looked like ordinary build output — which is exactly what #2280 measured on both local models, with the payload held constant and only its position varied.

The comment above the constant said the part beyond the window was "still covered by the approval fallback whenever the classifier cannot vouch for the visible tail". That only held when the tail looked risky.

What this does

A verdict now only vouches for what the model was shown.

• terminalReadScreenWindow (new, pure, in terminal-read-verdict.ts) splits a snapshot into the screened tail and the part above it. The gate criterion is characters, so one enormous line cannot slip through on a zero line count; the line counts are for the user-facing explanation only.
• A snapshot with anything above the window goes straight to the existing approval prompt. The reason says how many of its lines were actually screened, e.g. "It is larger than the safety model screens: only the most recent 75 of its 200 lines were screened."
• No screening call is spent on an oversized snapshot: no verdict on the tail could change that outcome, so it would only add latency (and, once fix(security): give the safety classifier a default that works, and say when it cannot run #2276 lands, cloud spend) before a prompt that is coming anyway.
• Snapshots that fit the window are unchanged, as are the flagged / could-not-screen paths and "Always allow for this chat".
• The tool description tells the agent roughly where the window sits so a quick check stays under it instead of prompting, and it now interpolates READ_TERMINAL_DEFAULT_LINES / READ_TERMINAL_MAX_LINES instead of repeating them as literals.

Why this option

Of the four in the issue, this one keeps the full 2000-line capability, adds no latency, and stays fail-closed. Its cost is a prompt for large reads, which "Always allow for this chat" turns into one prompt per chat.

• Share only what was screened silently truncates the tool to ~6000 chars against a 2000-line cap.
• Screen in chunks is not viable with the current 8s timeout: the issue's own latency data shows a single window already brushes it on some local models.
• Cap max_lines does not bound characters, so it does not actually keep a snapshot inside the window.
• A deterministic secret scanner is worth pursuing separately, but it does nothing for the injection lane and would not change this gate's contract.

Notes for a reviewer

• The security posture only tightens. Nothing that auto-shared before and was fully screened changes; the only new behaviour is that an unscreened portion now escalates instead of riding along.
• Overlap with fix(security): give the safety classifier a default that works, and say when it cannot run #2276. That PR reshapes the same guard (the classifier returns { verdict, problem }) and adds a terminal-read-guard.test.ts of its own. Whichever lands second needs a small manual merge in those two files; the logic does not conflict. This PR deliberately keeps its edit to classifyTerminalSnapshot to one line so that merge stays trivial.
• A classifier test seam (setTerminalSnapshotClassifierForTest) was added, mirroring the existing gate seam, so the gate can be driven with a scripted verdict and no model or HTTP stub.

Testing

• New terminal-read-guard.test.ts pins the gate contract: a confident safe never auto-shares an oversized snapshot; no screening call is spent on it; the reason names the screened line count; approve, decline, and remember all behave; a break-less oversized line gets a reason without a bogus line count.
• terminal-read-verdict.test.ts covers the window helper: fits, exactly-at-limit, tail-only screening with the lines above counted (and the straddling line not counted as above), oversized single line, empty.
• services/security + tools/ test directories: 719 pass. Lint, tsc -p tsconfig.node.json, and oxfmt --check clean.

🤖 Generated with Claude Code

[github-actions]

🖥️ PR preview

• Marketing site
• Browser demo
  Interactive, with a mocked backend — jump to a scenario:
• Builds a cupcake site
• Agent-proposed edits open the Changes panel
• Markdown list indentation
• Responsive composer footer
• Subagent display visual reference
• Subagent stays ungrouped beside reading tools
• Semantic search subagent markdown
• Light-theme approval with a bright accent
• Grouped outside-sandbox command approval
• Remote desktop discovered-port list with one selected
• Settings scroll + sticky footer geometry
• Per-model reasoning / temperature / top-p
• Thread switch hydration notice
• Thread switch hydration failure
• Chat layout styling
  _{Static demo of the renderer against a mock API — the browser pane, terminal, and all main-process IPC are stubbed, so it never proves main-process behaviour. Rebuilt whenever a push changes the demo bundle; these links go live once the queued deploy lands, shortly after this comment. Removed when the PR closes.}

[jonathanKingston]

Review: never auto-share an unscreened read_terminal snapshot

Verdict: no blocking findings; the fail-closed claim holds. Rebase (16 behind, dry merge clean) and let CI typecheck the combined tree before merge.

Path enumeration (gateImpl, terminal-read-guard.ts:155-201)

Path	Classifier called	Shared	Unscreened auto-share
fits window (≤ 6000 chars), confident safe	yes, whole snapshot byte-for-byte	whole snapshot	no
fits, flagged or low confidence	yes	only after approval	no
fits, screen error, timeout or model absent	yes, verdict: null	only after approval, problem named	no
oversized (> 6000)	no	only after approval, reason via describeUnscreened	no
exactly 6000	yes	whole	no (probe: unscreenedChars = 0)
6001, or a single 7000-char line	no	after approval; reason says "part of it was not screened" with no bogus line count	no
empty snapshot	yes	(no output yet)	n/a
remembered thread	no (line 161, before the size check)	whole, silently	user-granted, see item 1
approval denied	none	nothing; agent told to ask for a paste	no

terminalReadScreenWindow slices and gates on the same text.length measure, and unscreened + screened === text held for every probe (window−1, window, window+1, a 7000-char line, 200 × 80, boundary on a newline, screened tail starting with a newline). CR/LF and ANSI are normalised upstream in takeLastLines and stripTerminalControlSequences, so counts match what the agent receives. READ_TERMINAL_MAX_LINES is still enforced server-side twice (zod .max() at read-terminal-tool.ts:48 and the clamp in takeLastLines); the tool only has action, id, max_lines, so no offset and no sliding window.

Check	Result
pnpm test -- terminal-read-guard terminal-read-verdict read-terminal	36/36 pass (after rebuilding node-pty, no linux prebuild here)
oxfmt --check on the 5 changed files	pass
pnpm run check:dead-code	pass
Dry merge with origin/main	clean; #2282 rewrote the classifier internals but the gate's classifier indirection wraps it unchanged

No as casts, no object-literal casts, no exported type predicates; setTerminalSnapshotClassifierForTest mirrors the existing setTerminalReadGateForTest boundary injection, and the window size is a const, not a test-only option.

Non-blocking

1. "Always allow for this chat" bypasses the classifier and the size gate for the rest of the session (terminal-read-guard.ts:161 and :199). Pre-existing, but the oversized prompt now offers it on every large read and the new test pins it. docs/shell-permissions.md describes the analogous read-outside grant as authorising no command by itself, with every later command re-proved; this grant shares every later snapshot of any size unscreened. Worth a follow-up: omit allowRemember for the oversized reason, or keep screening fitting snapshots in remembered threads.
2. The user decides an oversized read with less information than before. Previously the tail was screened and the prompt could say "flagged: looks like an API token"; now it says only that the snapshot is larger than the model screens. A deliberate latency trade, but a token in the last ten lines of a 200-line snapshot no longer surfaces in the prompt copy.
3. Reason arithmetic overstates by up to one line. For 200 lines of 80 chars the window holds 74 whole lines plus 6 characters of the 75th, and the copy says "most recent 75 of its 200 lines were screened". Cosmetic since the gate is by characters; "about 75" or whole lines only would be exact.
4. classifyTerminalSnapshot still slices at line 103, but the gate only calls it when nothing is unscreened, so the slice is dead in product. If it is ever reached, slice(-6000) can start with a lone low surrogate (probe: 0xde00, isWellFormed false).
5. Missing tests: gate-level 6000 versus 6001 (auto-share versus prompt with zero classifier calls); the verdict case where exactly one non-newline character of the boundary line is visible (unscreenedLines 0, totalLines 2). The approval body copy changed and no e2e or demo spec reaches the terminal-output-share prompt (only settings-read-terminal.e2e.ts, the settings toggle); per the AGENTS.md visual-copy rule, add one or note why it is exempt.

Residual pre-existing gap, out of scope: two tail reads of different lengths, each under the window, can split a multi-line secret so the model sees each half in isolation. That is model quality rather than gating; an issue would be enough.

---

Generated by Claude Code

[jonathanKingston]

Pushed five commits: 099ee77 merges main (clean, 17 commits); b3ca03c makes the reason count only lines the model saw whole ("74 of its 200 lines were fully screened", singular handled) via a new screenedLines on terminalReadScreenWindow, gate criterion unchanged; de405dc removes the dead re-slice in classifyTerminalSnapshot since the gate is the only caller and only passes snapshots that fit; 5878dca scopes "Always allow for this chat" to the question the prompt actually asked (unscreened versus flagged), so a remembered thread still screens fitting snapshots and a flagged one prompts on its own question, while oversized and could-not-screen reads keep one prompt per chat as the PR intended; 08658e1 pins the 6000 versus 6001 gate boundary (zero classifier calls when oversized) and the one-visible-character verdict case. Every path is at least as closed as before and no UI copy changed. Typecheck, eslint, oxfmt, dead-code and 45 targeted tests pass. docs/shell-permissions.md still has no read_terminal section; worth a small follow-up if you want the gate and the per-cause grant recorded as contract.

---

Generated by Claude Code

[copse-release-bot]

Reference screenshots ready for review

Review GitHub’s image diffs in screenshot PR #2371.
Merge it (or enable auto-merge) to apply the accepted PNGs to claude/issue-2280-cdcd14.

Rendered for 9e039abba775 by CI run 33931082329; the immutable artifact is reference-screenshot-candidates-33931082329.

If this source branch moves, a later successful render closes the stale review PR and replaces this link.