Repository navigation
ACP does not project plugin plan metadata live or during replay #53928
Description
Functional context
An ACP client such as Zed can display a plan through standard sessionUpdate: plan notifications. At v2 commit 434f7b2 (2.0.24 manifest), successful plugin-tool metadata is retained in tool updates and saved messages but never projected into ACP plans. A plugin that returns the valid ACP shape under metadata.acp.plan therefore cannot display its current phases/tasks or restore that display on session load.
Related report: prevalentWare/opencode-goal-plugin#59
Scope
- Establish a generic, transport-independent metadata convention:
metadata.acp.plancontains ACPentriesand optional_meta. - Validate entry content, priority (
low,medium,high), and status (pending,in_progress,completed) before producing a standard plan notification. Ignore malformed metadata without failing the tool or session. - Project successful tool results live in
packages/cli/src/acp/translate.tsand during saved-message replay inreplay.ts; use the shared decoder intool.ts. - Keep child plans isolated unless the client opts into child-session updates. Keep normal tool notifications.
- This adapter convention is proposed for maintainer review; OpenCode core does not become a goal engine.
Acceptance criteria
- AC1: A successful root tool with valid metadata produces its normal tool update and a standard ACP plan with the same entries and metadata.
- AC2: Loading the saved assistant message replays the same plan.
- AC3: Invalid or absent plan metadata yields no plan and does not fail streaming or replay.
- AC4: A child plan cannot replace the root plan when child-session updates are disabled.
Functional tests
| Criterion | Setup and action | Expected evidence |
|---|---|---|
| AC1/AC2 | Generic successful tool fixture with one completed entry and _meta; translate live events and replay an equivalent saved message |
Both paths include the same ACP plan and preserve tool notifications |
| AC3 | Fixtures with no metadata or invalid status/entries | No ACP plan, normal tool behavior |
| AC4 | Child-session fixture with plan metadata and child updates disabled | No plan projected for the child |
Run bun run check from the repository root and bun test test/acp in packages/cli, using the required Bun 1.4.2. Fixtures require no provider credentials or installed goal plugin. Native Zed UI rendering is outside this transport-level acceptance.
Out of scope
Goal persistence, planning semantics, command lifetime, interruption classification, client UI redesign, provider behavior, infrastructure, CI/CD and publishing. The independent lifecycle correction is tracked in #53914 / PR #53913.
Dependencies
None for implementation or unit acceptance. A plugin emitting the convention is an optional integration consumer. Lifecycle and plan projection can land independently.
Activity
opencode-agent commentedon Oct 8, 2026
Thanks for the detailed proposal! As I understand it, you'd like the ACP adapter to treat
metadata.acp.planon successful tool results as a generic convention. Valid entries would be sent as a standard ACPplansession update, both live and when a session is reloaded. Invalid metadata would be ignored, and child-session plans would stay isolated unless the client opts in.The v2 ACP adapter doesn't send
planupdates at all right now, so this would be a new adapter convention. Maintainers will consider it, along with the approach in your PR.Related:
todowrite, which overlaps with plan projection in generalplansessionUpdate is never emitted #40745 / feat(acp): emit session plan from todo updates #40746 / fix(acp): emit plan updates for todos #41132: earlier, now closed, work on sending plans from todos