@wrongstack/acp 1.1.2 → 1.1.4

package/dist/client.js

@@ -11,6 +11,19 @@ import {
 var DEFAULT_MAX_FRAME_CHARS = 20 * 1024 * 1024;
 var DEFAULT_MAX_QUEUED_MESSAGES = 1e3;
 var DEFAULT_MAX_QUEUED_CHARS = 32 * 1024 * 1024;
+var STDERR_TAIL_CHARS = 4096;
+function echoChildStderr() {
+  const v = process.env.WRONGSTACK_DEBUG;
+  return !!v && v !== "0" && v !== "false";
+}
+function lastLine(text) {
+  const lines = text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (line) return line.length > 300 ? `${line.slice(0, 300)}\u2026` : line;
+  }
+  return "";
+}
 function takeLines(pending, chunk) {
   const lines = [];
   let start = 0;
@@ -27,6 +40,8 @@ function positiveLimit(value, fallback) {
 var ClientTransport = class {
   child = null;
   buffer = "";
+  stderrTail = "";
+  stopRequested = false;
   handlers = /* @__PURE__ */ new Set();
   claimHandlers = /* @__PURE__ */ new Set();
   closeHandlers = /* @__PURE__ */ new Set();
@@ -127,9 +142,11 @@ var ClientTransport = class {
         }
         const idx = this.buffer.indexOf("[wstack-acp]\n");
         if (idx !== -1) {
-          this.buffer = this.buffer.slice(idx + "[wstack-acp]\n".length);
+          const rest = this.buffer.slice(idx + "[wstack-acp]\n".length);
+          this.buffer = "";
           child.stdout.removeListener("data", waitForMarker);
           onReady();
+          if (rest) this.onChildData(rest);
         }
       };
       child.stdout.on("data", waitForMarker);
@@ -192,6 +209,7 @@ var ClientTransport = class {
   }
   stop(reason = "transport stopped") {
     this.closed = true;
+    this.stopRequested = true;
     this.resolveRead?.(null);
     this.resolveRead = null;
     this.buffer = "";
@@ -229,7 +247,8 @@ var ClientTransport = class {
     }
   }
   onChildError(chunk) {
-    writeErr(`[acp-child stderr] ${chunk}`);
+    this.stderrTail = (this.stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+    if (echoChildStderr()) writeErr(`[acp-child stderr] ${chunk}`);
   }
   onChildClose(code) {
     this.closed = true;
@@ -241,11 +260,16 @@ var ClientTransport = class {
     this.queuedChars = 0;
     this.handlers.clear();
     this.claimHandlers.clear();
-    if (code !== 0 && code !== null) {
+    const failed = code !== 0 && code !== null && !this.stopRequested;
+    if (failed) {
+      const tail = echoChildStderr() ? "" : this.stderrTail.trimEnd();
       writeErr(`[acp-child exited with code ${code}]
-`);
+${tail ? `${tail}
+` : ""}`);
     }
-    this.notifyClosed(`agent process exited with code ${code}`);
+    const cause = failed ? lastLine(this.stderrTail) : "";
+    this.stderrTail = "";
+    this.notifyClosed(`agent process exited with code ${code}${cause ? `: ${cause}` : ""}`);
   }
   dispatch(msg, chars = JSON.stringify(msg).length) {
     if (this.resolveRead) {
@@ -388,6 +412,9 @@ function isAuthRequiredError(err) {
 }
 
 // src/client/acp-request-state.ts
+function touchIdleRequests(pending) {
+  for (const p of pending.values()) p.rearm?.();
+}
 function rejectPendingRequests(pending, reason) {
   for (const p of pending.values()) {
     clearTimeout(p.timeoutHandle);
@@ -584,11 +611,21 @@ async function executeMcpMessage(ctx, connectionId, message) {
 }
 async function executeCreateSession(ctx) {
   const servers = filterMcpServers(ctx.agentCapabilities, ctx.opts.mcpServers);
-  const id = ctx.allocId();
-  const result = await ctx.sendRequest(id, "session/new", {
+  const params = {
     cwd: ctx.opts.cwd ?? ctx.opts.projectRoot,
-    mcpServers: servers
-  });
+    mcpServers: servers,
+    ...ctx.opts.sessionMeta ? { _meta: ctx.opts.sessionMeta } : {}
+  };
+  const resumeId = ctx.opts.resumeSessionId;
+  if (resumeId && ctx.agentCapabilities.sessionCapabilities?.resume) {
+    const resumed = await ctx.sendRequest(ctx.allocId(), "session/resume", { ...params, sessionId: resumeId }).catch((err) => ({ refused: err }));
+    if (ctx.closed) throw new ACPSessionError("closed", "session is closed");
+    if (!isJsonRpcError(resumed) && !resumed.refused) {
+      return adoptSessionMode(ctx, resumeId, resumed);
+    }
+  }
+  const id = ctx.allocId();
+  const result = await ctx.sendRequest(id, "session/new", params);
   if (isJsonRpcError(result)) {
     throw new ACPSessionError(
       "session_create_failed",
@@ -600,8 +637,53 @@ async function executeCreateSession(ctx) {
   if (typeof sessionId !== "string" || sessionId.length === 0) {
     throw new ACPSessionError("protocol_error", "session/new returned no sessionId", result);
   }
+  return adoptSessionMode(ctx, sessionId, result);
+}
+async function executeOpenSession(ctx, create) {
+  if (ctx.closed) throw new ACPSessionError("closed", "session is closed");
+  if (ctx.sessionId) return { sessionId: ctx.sessionId, resumed: false };
+  const sessionId = await create();
+  ctx.setSessionId(sessionId);
+  return { sessionId, resumed: sessionId === ctx.opts.resumeSessionId };
+}
+async function adoptSessionMode(ctx, sessionId, result) {
+  const want = ctx.opts.initialModeId;
+  const modes = result.modes;
+  const offered = Array.isArray(modes?.availableModes) && modes.availableModes.some((m) => m?.id === want);
+  if (want && !offered && ctx.opts.requireInitialMode) {
+    throw new ACPSessionError(
+      "session_create_failed",
+      `the agent does not offer the "${want}" session mode this host requires`,
+      result
+    );
+  }
+  if (want && offered && modes?.currentModeId !== want) {
+    await executeSetMode(ctx, sessionId, want);
+  }
   return sessionId;
 }
+async function executeSteer(ctx, supported, text) {
+  if (ctx.closed || !ctx.sessionId || !supported) return "unsupported";
+  const result = await ctx.sendRequest(
+    ctx.allocId(),
+    "_session/steering",
+    {
+      sessionId: ctx.sessionId,
+      prompt: [{ type: "text", text }],
+      _meta: { steering: { idleBehavior: "promptRequired" } }
+    },
+    1e4
+  );
+  if (isJsonRpcError(result)) {
+    throw new ACPSessionError(
+      "prompt_failed",
+      `_session/steering failed: ${result.message}`,
+      result
+    );
+  }
+  const outcome = result?.outcome;
+  return outcome === "injected" || outcome === "promptRequired" || outcome === "startedNewTurn" ? outcome : "unsupported";
+}
 
 // src/client/acp-session-auth.ts
 function ensureOpen(host) {
@@ -1208,6 +1290,7 @@ function emptyRunResult(stopReason) {
 function createSessionScratch() {
   return { text: "", thoughts: "", toolCalls: /* @__PURE__ */ new Map(), diffs: [] };
 }
+var MESSAGE_SEPARATOR = "\n\n";
 function handleAcpSessionUpdate(msg, scratch, emitProgress2) {
   const update = msg.params?.update;
   if (typeof update !== "object" || update === null) return;
@@ -1217,6 +1300,10 @@ function handleAcpSessionUpdate(msg, scratch, emitProgress2) {
     case "agent_message_chunk": {
       const text = extractText(u.content);
       if (text) {
+        if (scratch.messageBreak && scratch.text && !/\s$/.test(scratch.text)) {
+          scratch.text += MESSAGE_SEPARATOR;
+        }
+        scratch.messageBreak = false;
         scratch.text += text;
         emitProgress2({ type: "message", text });
       }
@@ -1241,7 +1328,9 @@ function handleAcpSessionUpdate(msg, scratch, emitProgress2) {
         emitProgress2({ type: "plan", entries: u.entries });
       }
       return;
-    case "usage_update":
+    case "usage_update": {
+      const rateLimit = u._meta?.["_claude/rateLimit"];
+      if (isRecord(rateLimit)) emitProgress2({ type: "rate_limit", info: rateLimit });
       if (typeof u.used === "number" && Number.isFinite(u.used) && u.used >= 0 && typeof u.size === "number" && Number.isFinite(u.size) && u.size >= 0) {
         const usage = {
           used: u.used,
@@ -1252,6 +1341,7 @@ function handleAcpSessionUpdate(msg, scratch, emitProgress2) {
         emitProgress2({ type: "usage", usage });
       }
       return;
+    }
     case "available_commands_update":
     case "current_mode_update":
     case "config_option_update":
@@ -1264,6 +1354,20 @@ function handleAcpSessionUpdate(msg, scratch, emitProgress2) {
       return;
   }
 }
+function toolOutputText(u) {
+  const joined = (blocks) => blocks.map(extractText).filter((text) => text.length > 0).join("\n");
+  if (Array.isArray(u.content)) {
+    const text = joined(
+      u.content.map(
+        (c) => c && typeof c === "object" && c.type === "content" ? c.content : void 0
+      )
+    );
+    if (text) return text;
+  }
+  if (typeof u.rawOutput === "string") return u.rawOutput || void 0;
+  if (Array.isArray(u.rawOutput)) return joined(u.rawOutput) || void 0;
+  return void 0;
+}
 function captureToolCall(u, isNew, scratch, emitProgress2) {
   const toolCallId = typeof u.toolCallId === "string" ? u.toolCallId : "";
   if (!toolCallId) return;
@@ -1274,12 +1378,18 @@ function captureToolCall(u, isNew, scratch, emitProgress2) {
     kind: typeof u.kind === "string" ? u.kind : prev?.kind,
     status: typeof u.status === "string" ? u.status : prev?.status ?? (isNew ? "pending" : "in_progress"),
     rawInput: isRecord(u.rawInput) ? u.rawInput : prev?.rawInput,
-    rawOutput: isRecord(u.rawOutput) ? u.rawOutput : prev?.rawOutput
+    rawOutput: isRecord(u.rawOutput) ? u.rawOutput : prev?.rawOutput,
+    output: toolOutputText(u) ?? prev?.output
   };
   scratch.toolCalls.set(toolCallId, record);
+  if (scratch.text) scratch.messageBreak = true;
   if (Array.isArray(u.content)) {
     for (const c of u.content) {
       if (c && typeof c === "object" && c.type === "diff") {
+        const key = `${toolCallId}\0${c.path}\0${c.oldText ?? ""}\0${c.newText}`;
+        scratch.seenDiffs ??= /* @__PURE__ */ new Set();
+        if (scratch.seenDiffs.has(key)) continue;
+        scratch.seenDiffs.add(key);
         const diff = {
           path: c.path,
           oldText: c.oldText,
@@ -1290,10 +1400,15 @@ function captureToolCall(u, isNew, scratch, emitProgress2) {
       }
     }
   }
-  emitProgress2({
-    type: isNew ? "tool_call" : "tool_call_update",
-    toolCall: record
-  });
+  scratch.announced ??= /* @__PURE__ */ new Set();
+  if (!scratch.announced.has(toolCallId)) {
+    const hasInput = record.rawInput !== void 0 && Object.keys(record.rawInput).length > 0;
+    if (isNew && !hasInput) return;
+    scratch.announced.add(toolCallId);
+    emitProgress2({ type: "tool_call", toolCall: record });
+    if (isNew || record.status !== "completed" && record.status !== "failed") return;
+  }
+  emitProgress2({ type: "tool_call_update", toolCall: record });
 }
 
 // src/client/acp-session-messages.ts
@@ -1325,6 +1440,7 @@ function handleMessage(msg) {
     }
     return;
   }
+  touchIdleRequests(this.pending);
   if (msg.method === "session/update") {
     const updateSessionId = msg.params?.sessionId;
     if (typeof updateSessionId === "string" && updateSessionId !== this.sessionId) return;
@@ -1381,6 +1497,7 @@ function handleMessage(msg) {
       );
       return;
     }
+    if (msg.method.startsWith("_")) return;
     console.warn(
       JSON.stringify({
         level: "warn",
@@ -1490,7 +1607,9 @@ async function prompt(host, blocks, signal, onProgress) {
         sessionId: host.sessionId,
         prompt: blocks
       },
-      host.timeoutMs
+      // Timed by silence, not length: a working agent keeps it alive.
+      host.promptIdleTimeoutMs,
+      true
     ),
     new Promise((_, reject) => {
       rejectTurn = reject;
@@ -1506,6 +1625,17 @@ async function prompt(host, blocks, signal, onProgress) {
     if (cancelled || abortedKind) {
       return emptyRunResult("cancelled");
     }
+    if (err instanceof ACPSessionError && err.kind === "stalled") {
+      if (host.sessionId) {
+        host.transport.send({
+          jsonrpc: "2.0",
+          method: "session/cancel",
+          params: { sessionId: host.sessionId }
+        }).catch(() => {
+        });
+      }
+      throw err;
+    }
     const msg = err instanceof Error ? err.message : String(err);
     if (signal.aborted) {
       throw new ACPSessionError("aborted", "prompt was aborted by the parent", err);
@@ -1527,17 +1657,31 @@ async function prompt(host, blocks, signal, onProgress) {
   }
   const stopReason = response.stopReason ?? "end_turn";
   const finalText = host.scratch.text;
+  const tokens = readTokenUsage(response.usage);
   return {
     text: finalText,
     stopReason,
     hasText: finalText.length > 0,
     usage: host.scratch.usage,
+    ...tokens ? { tokens } : {},
     plan: host.scratch.plan,
     toolCalls: [...host.scratch.toolCalls.values()],
     diffs: host.scratch.diffs,
     thoughts: host.scratch.thoughts
   };
 }
+function readTokenUsage(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const r = raw;
+  const n = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0;
+  if (typeof r.inputTokens !== "number" && typeof r.outputTokens !== "number") return void 0;
+  return {
+    input: n(r.inputTokens),
+    output: n(r.outputTokens),
+    cacheRead: n(r.cachedReadTokens),
+    cacheWrite: n(r.cachedWriteTokens)
+  };
+}
 
 // src/client/permission.ts
 function pickAllow(options) {
@@ -2187,6 +2331,7 @@ var ACPSession = class _ACPSession {
   terminalServer;
   permissionPolicy;
   timeoutMs;
+  promptIdleTimeoutMs;
   opts;
   transportOff = null;
   callbackAbort = new AbortController();
@@ -2202,12 +2347,15 @@ var ACPSession = class _ACPSession {
   agentCapabilities = {};
   agentInfo = null;
   authMethods = [];
+  /** The agent accepts `_session/steering` (see executeSteer). */
+  steeringSupported = false;
   /** Protocol version negotiated with the agent during initialize. */
   negotiatedVersion = ACP_PROTOCOL_VERSION;
   constructor(opts, transport) {
     this.opts = opts;
     this.transport = transport;
     this.timeoutMs = opts.timeoutMs ?? 5 * 6e4;
+    this.promptIdleTimeoutMs = opts.promptIdleTimeoutMs ?? 10 * 6e4;
     const fsOpts = {
       projectRoot: opts.projectRoot
     };
@@ -2362,6 +2510,8 @@ var ACPSession = class _ACPSession {
     }
     this.negotiatedVersion = r.protocolVersion;
     this.agentCapabilities = r.agentCapabilities ?? {};
+    const meta = result._meta;
+    this.steeringSupported = meta?.steering?.supported === true;
     this.agentInfo = r.agentInfo ?? null;
     this.authMethods = r.authMethods ?? [];
     this.state = "ready";
@@ -2406,6 +2556,10 @@ var ACPSession = class _ACPSession {
       closeSession: () => this.closeSession()
     };
   }
+  /** Start (or, with `resumeSessionId`, resume) the agent session now, not at the first prompt. */
+  async openSession() {
+    return executeOpenSession(this.opContext(), () => this.createSessionWithAuth());
+  }
   async loadSession(sessionId, mcpServers, cwd) {
     return executeLoadSession(this.opContext(), sessionId, mcpServers, cwd);
   }
@@ -2439,6 +2593,14 @@ var ACPSession = class _ACPSession {
   async disableProvider() {
     return executeDisableProvider(this.opContext());
   }
+  /** Whether {@link steer} can reach the agent. */
+  canSteer() {
+    return this.steeringSupported;
+  }
+  /** Inject a message into the agent's running turn. */
+  async steer(text) {
+    return executeSteer(this.opContext(), this.steeringSupported, text);
+  }
   // ──────────────────────────────────────────────────────────────────────
   // Prompt
   // ──────────────────────────────────────────────────────────────────────
@@ -2457,14 +2619,14 @@ var ACPSession = class _ACPSession {
   cancelLateSession(createPromise) {
     cancelLateAcpSession(this.transport, createPromise);
   }
-  async closeSession() {
+  async closeSession(graceMs = 1e4) {
     if (!this.sessionId) return;
     const sid = this.sessionId;
     this.sessionId = null;
     if (this.agentCapabilities.sessionCapabilities?.close) {
       const id = this.allocId();
       try {
-        await this.sendRequest(id, "session/close", { sessionId: sid }, 1e4);
+        await this.sendRequest(id, "session/close", { sessionId: sid }, graceMs);
       } catch {
       }
     }
@@ -2472,7 +2634,12 @@ var ACPSession = class _ACPSession {
   // ──────────────────────────────────────────────────────────────────────
   // Lifecycle — close
   // ──────────────────────────────────────────────────────────────────────
-  async close() {
+  /**
+   * Close the session and stop the agent. `graceMs` bounds how long the
+   * agent may take to answer `session/close` before it is stopped anyway —
+   * shutdown passes a short one so a slow answer cannot outlive the process.
+   */
+  async close(opts = {}) {
     if (this.closed) return;
     this.closed = true;
     this.state = "closed";
@@ -2482,7 +2649,7 @@ var ACPSession = class _ACPSession {
     this.terminalServer.dispose();
     if (this.sessionId && this.agentCapabilities.sessionCapabilities?.close) {
       try {
-        await this.closeSession();
+        await this.closeSession(opts.graceMs);
       } catch {
       }
     }
@@ -2506,24 +2673,37 @@ var ACPSession = class _ACPSession {
     }
     throw new ACPSessionError("protocol_error", "no JSON-RPC request id is available");
   }
-  async sendRequest(id, method, params, timeoutMs) {
+  async sendRequest(id, method, params, timeoutMs, idle = false) {
     return new Promise((resolve3, reject) => {
       const effectiveTimeout = timeoutMs ?? this.timeoutMs;
-      const handle = setTimeout(() => {
+      const expire = () => {
         this.pending.delete(id);
         reject(
-          new ACPSessionError("protocol_error", `${method} timed out after ${effectiveTimeout}ms`)
+          idle ? new ACPSessionError(
+            "stalled",
+            `${method}: no activity from the agent for ${Math.round(effectiveTimeout / 1e3)}s`
+          ) : new ACPSessionError(
+            "protocol_error",
+            `${method} timed out after ${effectiveTimeout}ms`
+          )
         );
-      }, effectiveTimeout);
-      this.pending.set(id, {
+      };
+      const entry = {
         method,
         resolve: resolve3,
         reject,
         timeoutMs: effectiveTimeout,
-        timeoutHandle: handle
-      });
+        timeoutHandle: setTimeout(expire, effectiveTimeout)
+      };
+      if (idle) {
+        entry.rearm = () => {
+          clearTimeout(entry.timeoutHandle);
+          entry.timeoutHandle = setTimeout(expire, effectiveTimeout);
+        };
+      }
+      this.pending.set(id, entry);
       this.transport.send({ jsonrpc: "2.0", id, method, params }).catch((err) => {
-        clearTimeout(handle);
+        clearTimeout(entry.timeoutHandle);
         this.pending.delete(id);
         const msg = err instanceof Error ? err.message : String(err);
         reject(new ACPSessionError("protocol_error", `send ${method} failed: ${msg}`, err));
@@ -2627,13 +2807,74 @@ var ACPSession = class _ACPSession {
       progressHandler: this.progressHandler,
       allocId: this.allocId,
       sendRequest: this.sendRequest,
-      timeoutMs: this.timeoutMs,
+      promptIdleTimeoutMs: this.promptIdleTimeoutMs,
       scratch: this.scratch
     };
     return this;
   }
 };
 
+// src/integration/acp-agent-failure.ts
+var USAGE_LIMIT_PREFIXES = [
+  "You've hit your",
+  "You've reached your",
+  "You're out of usage credits",
+  "Your org is out of usage",
+  "Your seat type doesn't include usage",
+  "Your seat type doesn't include extra usage",
+  "Your usage allocation has been disabled",
+  "Your group's usage limit is set to $0",
+  "requires usage credits",
+  "You're out of extra usage",
+  "Claude AI usage limit reached"
+];
+var DEFAULT_QUOTA_HOLD_MS = 15 * 6e4;
+function parseQuotaResetAt(text, now = Date.now()) {
+  const epoch = /usage limit reached\|(\d{9,11})/i.exec(text);
+  if (epoch?.[1]) return Number(epoch[1]) * 1e3;
+  const m = /\bresets?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/i.exec(text);
+  if (!m?.[1]) return void 0;
+  let hour = Number(m[1]);
+  const minute = m[2] ? Number(m[2]) : 0;
+  const meridiem = m[3]?.toLowerCase();
+  if (meridiem === "pm" && hour < 12) hour += 12;
+  if (meridiem === "am" && hour === 12) hour = 0;
+  if (hour > 23 || minute > 59 || !meridiem && !m[2]) return void 0;
+  const at = new Date(now);
+  at.setHours(hour, minute, 0, 0);
+  if (at.getTime() <= now) at.setDate(at.getDate() + 1);
+  return at.getTime();
+}
+function classifyAgentFailure(rpc, agent, now = Date.now()) {
+  const text = rpc.message.replace(/^Internal error:\s*/i, "").trim();
+  const errorKind = rpc.data?.errorKind;
+  const isQuota = USAGE_LIMIT_PREFIXES.some((p) => text.startsWith(p) || text.includes(p)) || errorKind === "billing_error" || errorKind === "account_on_hold";
+  if (isQuota) {
+    const resetAt = parseQuotaResetAt(text, now);
+    return {
+      kind: "provider_quota",
+      message: `${agent}: usage quota spent \u2014 ${text || "the account has no usage left"}`,
+      retryable: false,
+      backoffMs: resetAt !== void 0 ? Math.max(0, resetAt - now) : DEFAULT_QUOTA_HOLD_MS
+    };
+  }
+  const message = `${agent}: ${text}`;
+  switch (errorKind) {
+    case "rate_limit":
+      return { kind: "provider_rate_limit", message, retryable: true, backoffMs: 3e4 };
+    case "overloaded":
+    case "server_error":
+      return { kind: "provider_5xx", message, retryable: true, backoffMs: 1e4 };
+    case "authentication_failed":
+    case "oauth_org_not_allowed":
+    case "verification_required":
+    case "cloud_credential_error":
+      return { kind: "provider_auth", message, retryable: false };
+    default:
+      return rpc.code === -32e3 ? { kind: "provider_auth", message, retryable: false } : void 0;
+  }
+}
+
 // src/integration/acp-subagent-runner.ts
 async function makeACPSubagentRunner(options) {
   const { runner, stop } = await makeACPSubagentRunnerWithStop(options);
@@ -2646,13 +2887,37 @@ async function makeACPSubagentRunner(options) {
   };
   return wrappedRunner;
 }
+var sessionCostSeen = /* @__PURE__ */ new WeakMap();
+function recordTurnUsage(ctx, session, result) {
+  const cost = result.usage?.cost;
+  const total = cost?.currency === "USD" && Number.isFinite(cost.amount) && cost.amount >= 0 ? cost.amount : void 0;
+  const turnCost = total === void 0 ? 0 : Math.max(0, total - (sessionCostSeen.get(session) ?? 0));
+  if (total !== void 0) sessionCostSeen.set(session, total);
+  const t = result.tokens;
+  if (!t && turnCost === 0) return void 0;
+  try {
+    ctx.budget.recordUsage(
+      {
+        input: t?.input ?? 0,
+        output: t?.output ?? 0,
+        cacheRead: t?.cacheRead ?? 0,
+        cacheWrite: t?.cacheWrite ?? 0
+      },
+      turnCost
+    );
+  } catch {
+  }
+  return { type: "turn_usage", ...t ? { tokens: t } : {}, costUsd: turnCost };
+}
 async function makeACPSubagentRunnerWithStop(options) {
   const projectRoot = options.projectRoot ?? options.cwd ?? process.cwd();
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
   const persistent = options.persistent === true;
   let shared = null;
   let turns = Promise.resolve();
-  const startSession = async () => {
+  const startSession = async (setup) => {
+    const mcpServers = setup?.mcpServers && setup.mcpServers.length > 0 ? [...options.mcpServers ?? [], ...setup.mcpServers] : options.mcpServers;
+    const permissionPolicy = setup?.permissionPolicy ?? options.permissionPolicy;
     return ACPSession.start({
       command: options.command,
       ...options.args !== void 0 ? { args: options.args } : {},
@@ -2660,23 +2925,29 @@ async function makeACPSubagentRunnerWithStop(options) {
       ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
       projectRoot,
       timeoutMs,
+      ...options.promptIdleTimeoutMs !== void 0 ? { promptIdleTimeoutMs: options.promptIdleTimeoutMs } : {},
       role: options.role,
-      ...options.permissionPolicy !== void 0 ? { permissionPolicy: options.permissionPolicy } : {},
-      ...options.mcpServers !== void 0 ? { mcpServers: options.mcpServers } : {}
+      ...permissionPolicy !== void 0 ? { permissionPolicy } : {},
+      ...mcpServers !== void 0 ? { mcpServers } : {},
+      ...setup?.meta ? { sessionMeta: setup.meta } : {},
+      ...options.initialModeId ? { initialModeId: options.initialModeId } : {},
+      ...options.requireInitialMode ? { requireInitialMode: true } : {}
     });
   };
   const runner = async (task, ctx) => {
     let session;
+    let setup;
     try {
+      setup = options.sessionSetup?.(task, ctx);
       if (persistent) {
-        shared ??= startSession();
+        shared ??= startSession(setup);
         const starting = shared;
         session = await starting.catch((err) => {
           if (shared === starting) shared = null;
           throw err;
         });
       } else {
-        session = await startSession();
+        session = await startSession(setup);
       }
     } catch (err) {
       throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
@@ -2693,14 +2964,20 @@ async function makeACPSubagentRunnerWithStop(options) {
       }
     };
     let result;
+    let endLive;
     try {
-      const turn = () => session.prompt([textContent(task.description)], ctx.signal, onProgress);
+      if (session.canSteer()) endLive = options.onTurnLive?.(ctx, task, (t) => session.steer(t));
+      const prompt2 = setup?.promptPrefix ? `${setup.promptPrefix}
+
+${task.description}` : task.description;
+      const turn = () => session.prompt([textContent(prompt2)], ctx.signal, onProgress);
       const run = persistent ? turns.then(turn, turn) : turn();
       if (persistent) turns = run;
       result = await run;
     } catch (err) {
       throw acpErrorToSubagentError(err, options.role ?? "acp-subagent");
     } finally {
+      endLive?.();
       if (!persistent) {
         try {
           await session.close();
@@ -2708,6 +2985,8 @@ async function makeACPSubagentRunnerWithStop(options) {
         }
       }
     }
+    const turnUsage = recordTurnUsage(ctx, session, result);
+    if (turnUsage) onProgress(turnUsage);
     const failure = acpTurnFailure(result, options.role ?? "acp-subagent");
     if (failure) throw failure;
     return {
@@ -2728,7 +3007,20 @@ async function makeACPSubagentRunnerWithStop(options) {
   };
   return { runner, stop };
 }
+function agentRpcError(err) {
+  let cur = err;
+  for (let depth = 0; depth < 4 && cur; depth++) {
+    if (isJsonRpcError(cur)) return cur;
+    cur = cur.cause;
+  }
+  return void 0;
+}
 function acpErrorToSubagentError(err, subagentId) {
+  const rpc = agentRpcError(err);
+  if (rpc) {
+    const classified = classifyAgentFailure(rpc, subagentId);
+    if (classified) return classified;
+  }
   if (err instanceof ACPSessionError) {
     const kind = mapACPKind(err.kind);
     return {
@@ -2796,6 +3088,9 @@ function mapACPKind(acpKind) {
       return "bridge_failed";
     case "aborted":
       return "aborted_by_parent";
+    // The agent went silent mid-turn and the turn was cancelled.
+    case "stalled":
+      return "budget_timeout";
     case "closed":
     case "unsupported_capability":
       return "unknown";