vm-agent: read inbound ACP block _meta/annotations; guard SDK outward-strip

[simple-agent-manager]

Summary

First bounded slice of idea 01KWYF4H28MM5T679P55BMZXMT (hide SAM-injected prompt text from the chat UI). vm-agent-only change plus a design-de-risking test suite.

• parsePromptBlocks now preserves the ACP-standard optional _meta and annotations fields on inbound text prompt blocks (previously only {type,text} survived via acpsdk.TextBlock). This makes a SAM "system-injected" marker available in-process for a future origin-tagging consumer.
• Adds characterization tests that codify a blocking SDK constraint discovered while implementing this slice.

Key finding (surfaced by an in-session test)

acp-go-sdk v0.13.5's ContentBlock.MarshalJSON() for the text variant deliberately re-emits only {type, text}, dropping _meta AND annotations on every outward serialization — both acpConn.Prompt (to the agent CLI) and the SDK-marshaled mirror broadcast. The marshaler is asymmetric (reads inbound, strips outbound).

Design consequence: the origin marker cannot ride the ACP content block outward in this SDK version. The consumer slice must read the inbound marker (via parsePromptBlocks) and propagate origin through the vm-agent's own mirror/persistence fields (e.g. ExtractedMessage.Origin + a distinct broadcast field), not the ACP block. The two characterization tests guard this and fail loudly if a future SDK bump preserves the fields.

Deferred (documented in the task file)

1. Producer: task-runner emitting the injected instruction as a separate marked block.
2. Consumer: ExtractedMessage.Origin + additive DO origin column (excluded from FTS/dedup).
3. Web: render the origin=system segment collapsed with a chevron.

No new field was added to ExtractedMessage/reporter/DO here (no dead cross-boundary wiring).

Tests (green locally: go vet + go test ./internal/acp/..., gofmt clean, go build ./...)

• TestParsePromptBlocks_PreservesMetaAndAnnotations — inbound preservation.
• TestParsePromptBlocks_PlainTextRegression — plain text unchanged.
• TestParsePromptBlocks_SkipsNonTextAndEmpty — existing skip behavior.
• TestContentBlockMarshal_DropsMetaAndAnnotations — root-cause constraint guard (SDK marshaler).
• TestInjectUserMessageNotifications_SDKMarshalStripsMarker — real mirror path drops the marker.

⚠️ Staging verification SKIPPED (per user instruction)

The user explicitly asked to skip staging deployment because other important work is currently using staging. This touches packages/vm-agent/, which normally requires infra verification (rules 13/22/27). Because that gate was intentionally skipped, this PR is labeled needs-human-review and must NOT be self-merged — a human decides when/whether to deploy + verify.

Specialist Review Evidence

Reviewer	Status	Outcome
go-specialist	ADDRESSED	1 MEDIUM (comment wrongly claimed fields survive to agent CLI) + 1 LOW (annotations not asserted in mirror test). Both fixed in 79d01f4. Verdict: correct, nil-safe, concurrency-clean, plain-block behavior unchanged.
task-completion-validator	PASS	Revised scope honestly + completely delivered; deferrals documented; all 5 tests behavioral (not source-contract). 1 LOW (acceptance-criteria out of sync) fixed in 79d01f4.

🤖 Generated with Claude Code

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

• acp-go-sdk v0.13.5 pinned source read directly (gh api repos/coder/acp-go-sdk/contents/types_gen.go?ref=v0.13.5): ContentBlockText (Meta/Annotations), Annotations.Audience []Role, and ContentBlock.MarshalJSON (text variant re-emits only {type,text}). ACP extensibility: https://agentclientprotocol.com/protocol/extensibility

Codebase Impact Analysis

• packages/vm-agent/internal/acp/session_host_prompt.go — parsePromptBlocks widened to preserve inbound _meta/annotations.
• packages/vm-agent/internal/acp/session_host_prompt_parse_test.go — new tests (inbound preservation + SDK outward-strip characterization). No change to message_extract.go, reporter, DO, API, or web (consumer deferred).

Documentation & Specs

N/A: no www docs/specs affected. Behavior + design finding recorded in tasks/active/2026-07-07-preserve-acp-contentblock-meta-annotations.md and idea 01KWYF4H28MM5T679P55BMZXMT.

Constitution & Risk Check

• Principle XI (no hardcoded values): N/A — no URLs/timeouts/limits introduced; "text" type literal matches the SDK's own TextBlock helper.
• Risk: preserving inbound fields is populated-but-not-yet-consumed in-process; mitigated by explicit tests + documented consumer follow-up. Outward transports unchanged (SDK strips as before), so no behavior change for the agent CLI or existing viewers. Main risk (VM infra) is unverified because staging was intentionally skipped per the user → needs-human-review, no self-merge.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/important-before-starting-any-01kwy7 (79d01f4) with main (76aef70)}

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[simple-agent-manager]

Note on the red Specialist Review Evidence check: this is expected and intentional. That check is designed to fail whenever the needs-human-review label is present (scripts/quality/check-specialist-review-evidence.ts Check 1), which is exactly the state requested here: staging verification was skipped per the user's instruction (other work is using staging), so this PR must not be self-merged and needs a human decision.

All other checks are green (19 pass, 3 skipping). Local specialist reviews completed: go-specialist ADDRESSED, task-completion-validator PASS (see the Specialist Review Evidence table above). Go build/vet/test/gofmt all green locally.

To proceed, a human should: review, then delete all nodes on staging + deploy this branch to staging + verify a fresh workspace boots and prompts work (rule 27, since this touches packages/vm-agent/), remove the needs-human-review label, and merge.