Subagent permission decisions are silently dropped — subagent hangs forever

[jonioliveira]

Summary

When a subagent (a node created by a Task/Agent tool call) requests a tool that needs approval, clicking Allow or Deny does nothing. The SDK's canUseTool promise never settles, so the subagent blocks indefinitely and the permission card never clears. The only way out is Halt / Remove from canvas.

No error surfaces anywhere: the POST returns { ok: false } and the UI ignores the response.

Root cause

sessions is keyed by the parent session id only — there is exactly one sessions.set call, in startLocalAgent:

sessions.set(agentId, session);          // server/local-agent.ts:346

But a subagent is a first-class node with its own id, and the pending permission card is stored on that node:

const childId = nextId("sub");                       // local-agent.ts:499
subagentByToolUse.set(block.id, childId);
registry.upsert({ id: childId, kind: "subagent", parentId: nodeId, ... });

// later, in canUseTool:
const nodeId = options.agentID
  ? (subagentByToolUse.get(options.agentID) ?? agentId)   // :199-201
  : agentId;
registry.patch(nodeId, { status: "waiting-user", pending: { requestId, ... } });  // :270

The client reads agent.pending off that subagent node and POSTs to its id:

await api(`/api/agents/${agentId}/permission`, { requestId: agent.pending.requestId, ... });
// lib/store.ts:912 (approve), :924 (deny), :938 (answer)

The route forwards that id straight through:

const ok = resolvePermission(req.params.id, String(requestId), { ... });  // server/index.ts:338-339

and resolvePermission looks it up in the parent-keyed map:

const session = sessions.get(agentId);   // server/local-agent.ts:730  -> undefined for a subagent
if (!session) return false;              // :731

So the promise created at local-agent.ts:303 is never resolved.

Reproduction

1. Start a Local agent.
2. Give it work that spawns a subagent (any Task call).
3. Have the subagent request a tool requiring approval (Bash / Write / Edit).
4. A permission card appears on the subagent node. Click Allow (or Deny).

Expected: the tool runs (or is denied) and the card clears.
Actual: nothing happens. The card stays, the subagent hangs forever.

A second defect stacked in the same function

Even with the session lookup fixed, the card is cleared on the parent rather than the node that owns it:

registry.patch(agentId, { pending: undefined, status: "running" });  // :735

For a subagent request the card lives on the child node, so the stale card would survive and the parent's status gets wrongly overwritten. registry.pushChat(agentId, ...) at :738 and :750 misdirects the same way. Both the lookup and the patch/chat targets need to follow the node that owns the pending request.

Suggested fix

Resolve the owning session by walking up parentId, then patch the node the card is actually on. A loop rather than a single hop, because nesting is possible — the nodeId a subagent is parented to is itself resolved through subagentByToolUse (:499), so a subagent can spawn its own subagent:

export function resolvePermission(nodeId: string, requestId: string, decision) {
  // A subagent's pending request belongs to its nearest ancestor's SDK session.
  let sessionId: string | undefined = nodeId;
  while (sessionId && !sessions.has(sessionId)) {
    sessionId = registry.agents.get(sessionId)?.parentId;
  }
  const session = sessionId ? sessions.get(sessionId) : undefined;
  if (!session) return false;

  const pending = session.pendingByRequest.get(requestId);
  if (!pending) return false;
  session.pendingByRequest.delete(requestId);

  // Clear the card on the node that owns it, not the session root.
  registry.patch(nodeId, { pending: undefined, status: "running" });
  // ...and route the status/user chat messages to nodeId as well.
}

Happy to open a PR for this if the approach looks right.

[jonioliveira]

Dug into this and the root-cause analysis above (mine) is wrong. Recording the correction, because the mechanism matters for the fix.

The whole diagnosis rests on options.agentID at local-agent.ts:199 matching the Task tool_use block id that subagentByToolUse is keyed under at :501. It doesn't. From the SDK's own declaration (@anthropic-ai/claude-agent-sdk/sdk.d.ts:246):

/** If running within the context of a sub-agent, the sub-agent's ID. */
agentID?: string;

The emitted runtime passes the tool_use id as a separate field, confirming they're distinct:

toolUseID: e.request.tool_use_id,
l:         e.request.agent_id,      // sub-agent id ≠ tool_use id

So:

1. subagentByToolUse.get(options.agentID) at :200 always misses (wrong key namespace), and nodeId falls back to agentId — the parent.
2. The pending card is therefore written to the parent node today. The parent's id is in sessions, so resolvePermission finds it and Allow/Deny works.

This means the hang described above doesn't reproduce, and the "second defect" doesn't exist — resolvePermission's first arg is req.params.id, the id of the node whose card the client read, so its patch/pushChat calls are already correctly targeted.

The corroborating evidence: :439 keys the same map correctly, with message.parent_tool_use_id. One map, two key namespaces, one wrong.

What the real bug is

Narrower than described: a subagent's permission request surfaces on the parent's card instead of the subagent node — misattributed on the canvas, not dropped. If you saw a genuine indefinite hang, it likely has a different cause and is worth filing separately with the node ids involved.

Where that leaves the fix

The fix is at :199-201, and it needs a call I didn't want to make unilaterally: either map agentID → childId (:501 only sees the tool_use id, so the association has to be learned elsewhere), or thread the spawning Task id through. :439 shows the pattern that already works.

#6 is retitled and downgraded to Refs #2 — it hardens resolvePermission to tolerate a non-session node id (correct groundwork, but inert until :199 is fixed) and turns the route's swallowed { ok: false } into a 409. It does not close this issue; leaving it open for the :199 decision.

One caveat: the agentID finding is from the shipped type declaration and emitted source, not from observing a live subagent. Worth a runtime confirmation before anyone builds on it.