harness: str_replace — show target file and expandable old→new diff

[btipling]

Summary

When the agent calls str_replace, the operator needs to see which file was edited and, on expand, what changed (old vs new). Today the tool-run surface mostly shows a one-liner like path + replacement count + bytes — not enough to audit the edit without re-running or digging elsewhere.

Current behavior (baseline)

Layer	What happens today
Tool result (lib/agent/tools.ts)	str_replace ${path}: ok replacements=N bytes=M — no old_string / new_string / patch body
L1 brief (salientToolBits)	e.g. path · N replacements · M B
L2 preview (buildToolPreview)	Only whatever is in that short result text — usually nothing expandable beyond the one-liner

So expand is useless for surgical edits: you can’t see the diff that actually landed.

Desired UX

Collapsed / L1 (always visible)

• Clear file path (workspace-relative as resolved)
• Short status: ok/fail, replacement count (and fail reason when ERROR)
• Example: str_replace · ok · src/ui.zig · 1 replacement

Expanded / L2

• A readable diff between what was matched (old_string) and what replaced it (new_string):
  • Prefer a unified diff-style block (redacted, bounded) — same spirit as existing markdown/diff fence paint in the harness
  • Or a two-block before / after layout if unified is awkward for multi-replace / replace_all
• Include enough context that a human can approve the edit at a glance
• Failures: show path + ERROR line; if the tool rejected (not unique, missing read, etc.), expand with the error detail (already in result text)

Implementation sketch (not locked)

1. Backend tool result — when str_replace succeeds, include a bounded, redacted representation of the edit, e.g.:
   • path, replacements, bytes (keep)
   • plus old_string / new_string (truncated) or a prebuilt unified-diff snippet
   • Must go through existing secret redaction; never dump unbounded file bodies
2. Stream summary + preview — summarizeToolLine / buildToolPreview treat that body as real L2 (path stays in L1 bits)
3. Wasm paint — L2 already uses mono for str_replace / multi-line detail; optionally route through existing diff/patch fence painting if the payload is a fenced diff
4. Caps — reuse tool-run preview budget (TOOL_RUN_PREVIEW_*, group encode budget); huge replaces clip with explicit …

Acceptance

• Successful str_replace L1 shows which file was edited (and count/status)
• Expanding the item shows a diff (or before/after) of old vs new content, redacted + bounded
• Failed str_replace still surfaces path + error; expand not a blank duplicate of L1
• No secrets leaked; stays under existing tool-run / msg size budgets
• Docs: docs/harness-limits.md / agent-stream tool-result notes if the result shape changes

Related

• Tool-run L2 previews: plan: harness tool-run observability — phase 3 — real level-2 detail (C) #353 / harness: real level-2 tool detail via bounded redacted preview (#353) #359 (general preview path)
• Diff painting already exists for markdown fences in harness rich paint — reuse if practical
• Not the same as harness: remove PONG smoke-test button and prompt #367 (PONG removal)

Out of scope

• Reverting edits from the UI
• Live file watcher / external editor
• Changing str_replace tool semantics (unique match, freshness gate) — display only unless result shape must grow

Related (2026-08-15)

Operator-visible diff stays this issue. Model-facing error window on a failed replace is #564. Do not merge those payloads.

[btipling]

Correction (operator screenshot)

The issue body said L1 already shows path/count/bytes. That is wrong in the live UI.

What the operator actually sees for a successful str_replace:

▼ 1 tool called
  ✓  str_replace

Only the tool name — no path, no replacement count, no bytes.

Why

Layer	Reality
Tool result	Still str_replace ${path}: ok replacements=N bytes=M
Host brief	Compact one-liner does include path/count bits from salientToolBits
Host detail / preview	Short single-line → buildToolPreview omits preview → meaningfulDetail → empty detail
Wasm L1 label	item_label = has_detail && brief ? brief : **name** — empty detail ⇒ paint name only (str_replace) so the glyph is the single status channel (#358)

So path/count/bytes exist on the wire/brief but are hidden when there is no L2 body. Expand is not offered (static label).

Product ask (restated)

1. Collapsed row must show the file path (and useful status: ok + replacement count) — not bare str_replace.
2. Expand must show old→new diff (requires richer tool result / preview than today’s one-liner).

(1) may be a small paint/brief rule fix for no-detail items (use brief, not only name, when brief carries path); (2) still needs result-shape work.

[btipling]

L1 path + expandable L2 audit landed in #684 (merge c9f4684, plan #665). Remaining display work from this issue’s “unified-diff style” preference is now #687 — per-line -/+ prefixes, taking the better paint from closed #685 without its cap-before-redact path.

[btipling]

#687 is no longer per-line -/+. Locked display is old on EMBER surface, new on TEAL surface (paint-only; emit stays the #684 -old_string / +new_string block).