Summary

Describe the problem and fix in 2–5 bullets:

• Problem: when the edit tool fails because oldText does not exactly match the file contents, verbose-off user-facing output collapses into a vague failure warning.
• Why it matters: users do not get actionable guidance for a common whitespace/newline mismatch case, even though the underlying tool error already knows what went wrong.
• What changed: the embedded runner payload builder now recognizes the edit exact-match mismatch case and surfaces a concise sanitized summary that tells the user oldText must match exactly, including whitespace/newlines.
• What did NOT change (scope boundary): this does not change edit tool semantics, generic tool-error policy, replay/recovery policy, or expose raw file paths / file contents in verbose-off UI.

AI-assisted: Yes (Sona). Testing level: targeted local regression tests.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: edit tool: confusing error on whitespace mismatch, needs better surfacing #66915
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the useful mismatch detail already existed in the underlying edit error, but the final payload/UI warning path flattened it into a generic tool failure when verbose mode was off.
• Missing detection / guardrail: there was no targeted regression test asserting that edit exact-match mismatches should surface actionable, sanitized guidance in verbose-off mode.
• Contributing context (if known): the raw tool error may include file paths or file contents, so the UI layer had previously erred on the side of hiding too much instead of summarizing this well-known mismatch case safely.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/agents/pi-embedded-runner/run/payloads.test.ts
• Scenario the test should lock in: an edit exact-match mismatch should still show actionable guidance in verbose-off mode, mention exact-text / whitespace-newline mismatch, and avoid leaking raw paths.
• Why this is the smallest reliable guardrail: the behavior change lives in payload summarization, so the smallest reliable coverage is a focused unit test at the payload builder layer.
• Existing test that already covers this (if any): src/agents/pi-embedded-runner/run/payloads.errors.test.ts covers adjacent tool-error surfacing behavior, but not this exact sanitized mismatch summary.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Users now see actionable guidance for edit exact-match mismatches even when verbose mode is off.
• The warning remains sanitized and does not expose raw file paths from the underlying error.

Diagram (if applicable)

Before:
[edit exact-match mismatch] -> [generic tool failed warning]

After:
[edit exact-match mismatch] -> [sanitized actionable summary] -> [user knows to match whitespace/newlines exactly]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22 via npx -y node@22
• Model/provider: N/A (payload/tool error surfacing path)
• Integration/channel (if any): embedded runner payload generation
• Relevant config (redacted): verbose mode off

Steps

1. Trigger an edit tool failure where oldText does not exactly match the current file contents because of whitespace/newline mismatch.
2. Observe the user-facing warning generated from the embedded runner payload path with verbose mode off.
3. Compare the warning text before and after this change.

Expected

• The user-facing warning should say the exact text was not found and clarify that oldText must match exactly, including whitespace/newlines.
• The warning should remain sanitized and not expose raw file paths.

Actual

• Before this change, verbose-off output could collapse into a vague Edit ... failed warning without actionable guidance.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • targeted tests passed locally for payloads.errors.test.ts and payloads.test.ts
  • the new mismatch summary includes actionable guidance
  • the summary does not include raw path details such as /tmp/demo.txt
• Edge cases checked:
  • non-edit tool errors still follow existing behavior
  • only the exact-match mismatch case gets the special sanitized summary
• What you did not verify:
  • live end-to-end messaging-channel behavior outside the targeted payload tests
  • broader tool-error policy changes beyond this specific mismatch case

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: a sanitized summary could accidentally become too broad and affect unrelated tool failures.
  • Mitigation: the special-case path is restricted to toolName === "edit" plus the known exact-match mismatch prefix, and regression coverage locks that in.
• Risk: surfacing more detail could leak raw file paths or file contents.
  • Mitigation: the UI summary is hand-sanitized and tests assert that raw path details are not included.