Bug: acp permission requests carry only toolCallId, so no client can describe what it is approving

[iamenahs]

@deepseek-ai/dsh-acp asks the client to approve a bare toolCallId:

// packages/acp/acp/src/index.ts (master, b150a55)
return conn.requestPermission({
  sessionId: record.agent.session.id,
  toolCall: { toolCallId: request.callId },
  options: [ /* allow-once, reject-once */ ],
})

The bridge publishes no tool updates — deliberately, per ACP as an automation-only protocol — so that id is one the client has never seen. It has nothing to correlate it to and nothing to describe, and can only render a generic prompt.

That same note deliberately keeps one-shot session/request_permission: "The client chooses allow once, reject once, or cancel." A choice that cannot be described isn't one.

Why this reads as a bug rather than a boundary

The information is already at the call site and dropped. ApprovalRequest (packages/interaction/user-approval/src/index.ts) carries:

• readonly toolName: string — "The tool the question is about (presentation and audit)"
• readonly reason?: string — "The asker's human-readable explanation of WHY it is asking"

and ACP's ToolCallUpdate — the exact type the toolCall field takes — already allows optional title, kind, rawInput and content. Passing what the asker supplied is not presentation policy; it is the question.

Reproduction

• dsh 0.1.0-rc.8, repo at b150a55 (0.1.1-rc.2), @agentclientprotocol/sdk 0.14.1
• Composition: sandbox-policy workspace-write, dsh-user-approval policy: ask

1. Connect an ACP client, session/new in some directory.
2. Prompt: "Write the single word hello into <path outside the workspace> using your tools."
3. The sandbox correctly refuses and an approval is raised.

Received, client side:

toolCall: { toolCallId: "call_00_iEL6zYtNacMUYFEcT9ZQ6406" }
options:  Allow once | Reject

Rendered, with nothing to work from: "The agent asks permission to continue."

This is not a corner case for attended deployments: with workspace-write + ask, the only time DSH asks is when it is about to act outside the workspace — the moment when knowing what it is matters most.

Fix

toolName → toolCall.title; reason, when present → a text content block. No new session updates, so the output boundary is untouched. approval.spec.ts asserts with toMatchObject, so it stays green.

Patch, with tests and end-to-end output (summary becomes "write"): iamenahs#1 — npm run typecheck 0, npm run lint 0, ACP suite 84 passed. Happy to reshape it however you'd prefer, or to hand it over as a description if you'd rather write it yourselves.

Found while building an ACP client against DSH; the same client drives Codex, Claude Code and Cursor, and this is the one place where the approval cannot be shown.

[argszero]

Verified against rc.2 (HEAD b150a55) — the drop is real, and the fields are in scope at the exact line you quote, so this is a two-field one-site fix.

1. Source anchors

• packages/acp/acp/src/index.ts:271 — the handler receives request as the full ApprovalRequest (type-only import at :39 from @deepseek-ai/dsh-user-approval).
• packages/interaction/user-approval/src/index.ts:161 has "readonly toolName: string" and :168 has "readonly reason?: string" — both documented as presentation + audit context: "The tool the question is about" and "The asker's human-readable explanation of WHY it is asking".
• The bridge drops both at :274-276: it sends only "toolCall: { toolCallId: request.callId }" and nothing else.

2. The reason field matters more than it first appears in your repro

Your reproduction (sandbox-policy workspace-write refusal, approval raised) is exactly the case where reason carries the whole question: the sandbox refusal reason is what a human needs to decide allow-once vs reject. toolName alone (write or bash) would still leave the client guessing why the tool call needs approval; reason turns the bare id into a decidable prompt. The handler has it in scope — it is purely a forwarding decision.

3. Fix shape

At :274-276, forward what the asker supplied into the toolCall object. The ToolCallUpdate fields you cite (title, kind, rawInput, content) are the SDK's own channel for this:

• title gets request.toolName
• content (text block) gets request.reason, when present

This stays inside the automation-only boundary you quote: nothing new is published on the session stream, no terminal/diff/card machinery, just the question itself carried on the permission request. The client still chooses allow once / reject once / cancel — it just now has the information to choose.

4. One design note worth adding to the fix

The bridge's comment at :268-269 says permission requests are a machine policy channel for ACP clients and never infers a durable grant from an unknown client response. Forwarding toolName/reason does not change either property — the grant semantics stay one-shot, and the client remains a blind policy voter that can now see what it is voting on. The fix is compatible with the documented contract.

5. Test gap

The ACP bridge tests (packages/acp/acp/tests) should assert the forwarded toolCall carries title/content — a regression test that would have caught this drop. The minimal test: emit approval/request with toolName + reason, capture the requestPermission call, assert toolCall.title equals toolName and the text content equals reason.

Your #4277 proposal (opt-in tool-call progress) is the complementary half — with title/content on the permission request and optional progress on the stream, a human-facing ACP client has both "what is being asked" and "what the agent did". They compose cleanly.

[iamenahs]

Thanks for reading it that closely — the anchors match what I found, and your point 4 is a check I hadn't made explicitly.

On your point 2, you're right: reason is the more important half. The escalation path already constructs the human-readable justification (escalate sandbox to ${mode}: ${justification}), so when present that's effectively the decidable prompt. toolName tells the client what (write, bash); reason tells it why approval is needed.

One empirical wrinkle: in the refusal I captured (workspace-write + policy: ask, writing outside the session cwd), the approval actually arrived with reason === undefined. That appears to come through the tool-level path in packages/core/tools/src/index.ts, where reason is optional, rather than the escalation path where it's required.

I think that's probably a separate upstream question rather than something to widen this fix around: should fs/bash sandbox refusals themselves always supply a reason? If so, that seems worth following up separately. Either way, forwarding toolName/reason here is still the right bridge behavior.

On your point 5, the regression coverage is already in the PR — iamenahs#1. There are cases for forwarding toolName + reason, and for omitting the content block entirely when no reason was supplied. ACP suite 84 passed; typecheck and lint are clean.

And agreed on the pairing with #4277 — the patch for that one is iamenahs#2, same default-off shape: with title/content on the permission request and optional progress on the stream, a human-facing client has both what is being asked and what the agent did.

Still a two-field, one-site bridge change. Thanks again for independently verifying it.

[iamenahs]

Correction to my last reply - I was wrong about the reason.

It isn't undefined. The ask comes through the escalation path exactly as you said, and the branch forwards it. Captured raw off the wire, with the patch applied:

"toolCall": {
  "toolCallId": "call_00_YuoefBEJ5lkGfJJ27s7k9634",
  "title": "write",
  "content": [{ "type": "content", "content": { "type": "text",
    "text": "escalate sandbox to danger-full-access: The user explicitly asked me to write this file outside the session workspace; full access is the only mode that allows it." } }]
}

The durable log records the same ask with toolName: "write" and that reason string, under the call id my client was handed.

What I actually hit was a gap on my side: my client renders toolCall.title and ignores toolCall.content, so a well-formed request still displayed as a bare tool name. Mine to fix, not the bridge's — and it means there's no separate upstream question about refusals after all. Your point 2 stands without the caveat I attached to it.