fix(gmail): preserve wrapped header identifiers

[steipete]

--wrap-untrusted wrapped Gmail header identifiers such as From, so JSON lookups by header name stopped matching. The shared formatter also left flattened From/To/Cc/Bcc display text unwrapped.

Preserve a fixed allowlist of standard ASCII field names only at Gmail payload-header paths, including nested MIME parts. Custom names, malformed names, and all header values retain wrapping. Flattened sender and recipient display text now gets the same untrusted-content treatment as Subject and Reply-To. Documentation describes the boundary.

Regression coverage exercises message, thread, draft, raw, and nested-part output; custom and malformed names; unrelated name paths; flattened address headers; and Unicode case-folding aliases. The new tests failed against unchanged production code before the repair.

Fixes #1183. Thanks @postoso for the report.

Validation: failing-before/passing-after synthetic formatter regressions, full make ci on AWS Crabbox, and final independent Codex review through P2. The initial review caught Unicode case-folding of malformed header names; the final patch rejects those before matching.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed October 7, 2026, 12:24 AM ET / 04:24 UTC.

ClawSweeper review

What this changes

The PR preserves standard Gmail header names in wrapped JSON output, wraps flattened sender and recipient text, and adds regression tests, documentation, and an Unreleased changelog entry.

Merge readiness

✅ Ready for maintainer review

This remains a useful, focused repair: current main and v0.43.0 still wrap standard Gmail header names. No blocking correctness or security defect was found in the proposed patch.

Priority: P2
Reviewed head: ba3f9c48194ab95ed337992b443b8b4418c47174

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused repair with useful regression coverage and no concrete blocking finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from ordinary contributor runtime proof; its reported synthetic formatter regressions and Crabbox CI are supplemental validation. No stored-data contract or material authorization boundary changes.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored PR is exempt from ordinary contributor runtime proof; its reported synthetic formatter regressions and Crabbox CI are supplemental validation. No stored-data contract or material authorization boundary changes.
Evidence reviewed	7 items	Pinned introduced change: The pinned base-to-head diff contains only the formatter repair, 133 added test lines, six documentation lines, and one credited Unreleased entry. Repair remains necessary on main: The main classifier has no Gmail header-name exemption and classifies name and value as content. The branch endpoint independently returned the pinned main SHA. Latest release still has the defect: The v0.43.0 classifier likewise wraps header names. The releases endpoint confirmed v0.43.0 remains the latest release.
Findings	None	None.
Security	None	None.

How this fits together

Gmail commands pass Google API responses through the shared JSON formatter. With untrusted wrapping enabled, the formatter marks external text before scripts or agents consume it.

flowchart TD
  A[Gmail API response] --> B[Message thread or draft command]
  B --> C[JSON formatter]
  C --> D{Untrusted wrapping enabled}
  D -->|No| E[Ordinary JSON output]
  D -->|Yes| F[Preserve fixed header identifiers]
  F --> G[Wrap external text and header values]
  G --> H[JSON for scripts and agents]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +46, tests +133; 0 removed	Production growth implements the path check, ASCII allowlist, and missing address-value wrapping, with focused regression coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1183
Summary: This PR directly addresses the canonical report's header-name lookup defect and flattened address-value gap.

Members:

• canonical: --wrap-untrusted wraps Gmail header names, so a lookup by name finds nothing #1183 - The report describes the exact formatter behavior repaired by this branch.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Keep standard Gmail header identifiers machine-readable while consistently marking sender-controlled text as untrusted.

Do we have a high-confidence way to reproduce the issue?

Yes: current-main source deterministically wraps From in payload header entries, matching the reporter's wrapped/unwrapped Gmail comparison; this review did not execute commands against Gmail.

Is this the best way to solve the issue?

Yes: the fixed ASCII allowlist follows the existing validated-metadata pattern and preserves value protection without exempting arbitrary header names.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 6dcfcee20a82.

Labels

Label changes:

• add P2: This repairs scriptable Gmail header lookup in an opt-in output mode with limited blast radius.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored PR is exempt from ordinary contributor runtime proof; its reported synthetic formatter regressions and Crabbox CI are supplemental validation. No stored-data contract or material authorization boundary changes.

Label justifications:

• P2: This repairs scriptable Gmail header lookup in an opt-in output mode with limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored PR is exempt from ordinary contributor runtime proof; its reported synthetic formatter regressions and Crabbox CI are supplemental validation. No stored-data contract or material authorization boundary changes.

Evidence

What I checked:

• Pinned introduced change: The pinned base-to-head diff contains only the formatter repair, 133 added test lines, six documentation lines, and one credited Unreleased entry. (internal/outfmt/untrusted.go:226, ba3f9c48194a)
• Repair remains necessary on main: The main classifier has no Gmail header-name exemption and classifies name and value as content. The branch endpoint independently returned the pinned main SHA. (internal/outfmt/untrusted.go:219, 6dcfcee20a82)
• Latest release still has the defect: The v0.43.0 classifier likewise wraps header names. The releases endpoint confirmed v0.43.0 remains the latest release. (internal/outfmt/untrusted.go:219, 3b5122f4c81c)
• Narrow security boundary: Only fixed ASCII identifiers beneath payload headers, including nested parts, bypass wrapping. Custom names, malformed names, Unicode aliases, and header values retain protection; flattened From/To/Cc/Bcc values gain wrapping. This changes output classification without transferring account or execution authority. (internal/outfmt/untrusted.go:267, ba3f9c48194a)
• Production callers and regression coverage: Message, thread, and draft commands pass Gmail payloads to WriteJSON; WriteRaw uses the same wrapper. Added tests cover these envelope shapes, nested MIME parts, unrelated name paths, malformed identifiers, and flattened address values. Tests were inspected, not executed in this read-only review. (internal/outfmt/untrusted_gmail_test.go:10, ba3f9c48194a)
• Related report and prior boundary discussion: --wrap-untrusted wraps Gmail header names, so a lookup by name finds nothing #1183 supplies wrapped/unwrapped v0.43.0 command comparisons. Its prior review recommended preserving recognized identifiers while keeping custom and malformed names wrapped; this collaborator-authored PR adopts that narrow boundary and explicitly identifies itself as the candidate fix.

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• hashtag1974: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• VACInc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Fixed in #1191. Standard ASCII header identifiers now remain usable for name-based selection at Gmail payload-header paths (including nested MIME parts). Custom/malformed names and all raw values remain wrapped; flattened sender and recipient display text is now wrapped too.

The new synthetic regressions failed before the repair for message, thread, draft, and raw output. After the fix, focused formatter tests and the full make ci gate passed on AWS Crabbox (cbx_82fe63e89d13, run run_d775bb5d1b14177e01af47d72b9f5411). Final independent Codex review found no P0–P2 issues. Exact-head CI passed at ba3f9c48194ab95ed337992b443b8b4418c47174, including Linux, minimum Go, macOS, Windows, worker, Docker, and CodeQL: https://github.com/openclaw/gogcli/actions/runs/37571124228

Thanks @postoso for identifying both output inconsistencies.