acp: opt-in tool-call progress, so an ACP client can show what the agent did

[iamenahs]

A conforming ACP client shows a finished DSH turn as an answer with no visible work. It cannot say whether the agent read a file, ran a command, or produced the answer from nothing — and when a permission request arrives for call_… (#4276), there is no call in the transcript to attach it to.

I have read ACP as an automation-only protocol, and this doesn't argue with it. Terminal cards, diffs, locations, session navigation, configuration pickers and human elicitation belong exactly where that note put them — that bridge really had become a second product UI.

The narrower claim: tool_call and tool_call_update are different in kind from those. They are two members of the spec's own SessionUpdate union — what the agent did, not how an editor draws it. The note groups them with terminal metadata and editor cards; I think that grouping is what costs more than it saves, because it is the one thing every ACP client needs and the only one the protocol has a word for.

The idea

One config value, default off:

- id: acp
  name: '@deepseek-ai/dsh-acp'
  config:
    progress: tools     # default: none

• 'none' — the established contract, unchanged: committed assistant text and images only. Automation clients, dsh-subagent-acp included, see no difference.
• 'tools' — adds tool_call (id, tool name as title, kind, parsed rawInput) and tool_call_update (completed/failed, result text). Nothing else joins: no terminals, diffs, locations, plans, titles, reasoning or elicitation.

Opt-in matters more than the mapping: the deployment that wants a human watching asks for it, and every other deployment keeps today's silence by default.

What it looks like

Same build, same prompt — "Read app.js and say in one sentence what it exports." — through an ACP client:

default:            userMessage → assistantMessage
progress: tools:    userMessage → toolCall "read" [completed] → assistantMessage

A working patch, if it's useful to have something concrete to react to: iamenahs#2 — tool updates ride the existing per-session outputTail chain so a call never lands after the text that describes it, acp-demo forwards the value, npm run typecheck 0, npm run lint 0, 95 tests pass including edges.spec.ts's "does not emit tool, terminal, plan, title, or reasoning presentation updates", untouched, because the default is none.

The alternative I looked at first

@deepseek-ai/dsh-sdk-jsonrpc-server forwards the whole session/event stream and would solve this for one client without touching ACP at all. It has no approval flow — packages/sdk/protocol/README.md: "Server→client requests are dead capability… the Python SDK's responder surface exists for future approval flows" — so today it trades a human in the loop for fidelity. ACP is the only surface with both, which is why I'm asking here rather than just moving over.

If the answer is "the SDK is where interactive clients belong, and the approval flow is coming", that's a perfectly good answer — I'd just like to know which road to build on. Context: I maintain an ACP client that also drives Codex, Claude Code and Cursor, and DSH is the one agent whose work the transcript can't show.

[argszero]

Verified all of this against rc.2 (HEAD b150a55) — the claims hold, and I want to add the one argument I think is strongest in your favor, which comes from the note itself.

1. Your description of the current bridge is accurate

The handler at packages/acp/acp/src/index.ts:218-252 is a single choke point that emits only committed assistant text/images. The comment there is explicit: "Raw chunks, reasoning, tools, plans, titles, and retry markers are presentation or trace data and stay off the automation wire." So tool events do reach the handler via session/event — the bridge just ignores them. That means your patch is a filter widening at one site, not new plumbing, and the ordering guarantee you rely on is real: every delivery is chained on the previous outputTail (index.ts:228-239), so any tool update appended to that chain cannot land after the text that describes it. I also confirmed edges.spec.ts:25 pins the current behavior with exactly the title you quote, and sdk/protocol/README.md:39 contains the dead-capability sentence verbatim.

2. The note's escape hatch is closed for ACP clients — this is the gap

The note's Consequences justify excluding tool traces by saying automation clients "inspect durable logs or another API when they need reasoning, tool traces, titles, or richer state." But the same note removed the path that would make that practical: ACP "does not provide session load/list/delete" and is fresh-session-only. An ACP client cannot read the durable log of the session it just ran — the sanctioned route is "another API", and as you found, the JSON-RPC surface explicitly has no server-to-client requests today (the SDK README calls it dead capability pending future approval flows). So right now there is no surface where an automation client gets both a permission flow and a tool trace. That is a real hole, and your proposal is the only one in the repository that closes it.

3. The carve-out is coherent on the note's own terms

Look at the note's excluded list: "Reasoning, raw chunks, tool activity, todos, plans, titles, retry markers, terminal metadata, diffs, locations, resource links." The first two are intermediate model output. The rest are UI state or editor presentation. Tool calls are the odd member out — they are durable agent actions, and the SDK already has vocabulary for them (ToolCallUpdate is part of the SessionUpdate union, the same union as the committed answer). Carving tool events out of the presentation set does not reopen the editor bridge; it corrects a grouping that the note made for convenience rather than principle.

4. Two things I would pin down before it merges

• Reasoning must stay excluded even with progress: tools. Your field list already scopes it (id, tool name, kind, parsed rawInput; completed/failed + result text), but the existing edges.spec.ts test asserts "does not emit tool, terminal, plan, title, or reasoning presentation updates" as one assertion — once progress is on, that test changes. Add a sibling test that runs with progress: tools and asserts reasoning/todos/titles still never appear, so the exclusion is a deliberate invariant, not an accident of the default.
• Leak surface. rawInput is already in the durable log and the transport is local stdio, so opt-in default-none introduces no new exposure for existing deployments — but the proposal should state that explicitly in the protocol doc, because the note's "small public protocol" rationale is the one legitimate reason a maintainer could push back with.

5. It composes with Bug: acp permission requests carry only toolCallId, so no client can describe what it is approving #4276

With title/content on the permission request (the #4276 fix) and tool progress on the stream (this), a human-facing ACP client gets both "what is being asked" and "what the agent did" — the two halves of a transcript. If both land, the ACP surface stops being a blind answer box and becomes a protocol where an automation client can show its work.

The default-none opt-in is the right call — it keeps every existing deployment's silence and gives the maintainers a reviewable, reversible increment. I'd like to see this one move.

[iamenahs]

Both of your point 4 items are in bb68f4b on the PR branch.

The exclusion test now runs a turn that produces reasoning and a tool call with progress: 'tools', and pins the whole update list, so anything else the session logs leaking in fails there rather than passing because the fixture never produced it. It also asserts the reasoning text appears in no payload, catching both a stray thought chunk and reasoning smuggled inside the committed message. The leak-surface paragraph went into README.md/README.zh.md rather than only the PR, since that's where the "small public protocol" question gets asked. 96 tests, typecheck and lint clean, translation pair re-recorded.

On your point 2, one detail that sharpens it: the durable log does exist for ACP sessions, and it's keyed by the ACP session id. The composition's persistenceRoot defaults to ./.sessions relative to the process cwd, so a session created through session/new lands at <cwd>/.sessions/--<encoded cwd>--/<sessionId>/session.jsonl.zstd. I checked those against the ids my client was handed and they match.

So the information isn't missing or expensive — it's already written, under the id the client already holds. What's absent is any affordance to reach it: no load/list on this surface, no way for a client to know the deployment's persistenceRoot, and the format is DSH's own. "Inspect durable logs" ends up meaning "guess where they live and reimplement someone else's storage layer", which is the thing a protocol is meant to spare a client. That makes the carve-out cheaper to grant, not dearer.

Thanks again for the verification pass — the point-2 framing is better than what I wrote, and I've kept it.