@khalilgharbaoui/opencode-claude-code-plugin 0.31.1 → 0.32.0

package/dist/index.js

@@ -1683,7 +1683,8 @@ function buildProxyTimeoutError(toolName, ms) {
   }
   return new Error(base);
 }
-var TASK_PROXY_NOTE = "This and task_batch are the ONLY tools that dispatch opencode subagents (including user @-mentions). Claude Code's built-in TaskCreate/TaskUpdate manage a local todo list and cannot dispatch subagents. Do not search config files to verify a subagent type exists: invalid types fail fast with a clear error. Foreground calls block until the subagent finishes; set `background` to request opencode's background execution mode. For two or more independent subagents in one response use task_batch, not several task calls: those run one after another. Task calls have no proxy deadline by default: the call waits for the subagent to finish (a positive proxyToolTimeoutMs override adds a deadline).";
+var TASK_PROXY_NOTE = "This and task_batch are the ONLY tools that dispatch opencode subagents (including user @-mentions). Claude Code's built-in TaskCreate/TaskUpdate manage a local todo list and cannot dispatch subagents. Do not search config files to verify a subagent type exists: invalid types fail fast with a clear error. Calls block until the subagent finishes. For two or more independent subagents in one response use task_batch, not several task calls: those run one after another. Task calls have no proxy deadline by default: the call waits for the subagent to finish (a positive proxyToolTimeoutMs override adds a deadline).";
+var TASK_BACKGROUND_NOTE = 'Fire-and-collect: set `background: true` and the call returns at once with `<task id="ses_..." state="running">` instead of the subagent\'s answer. Keep working on something that does not overlap it, then end your turn: when the subagent finishes, opencode delivers its result to this conversation on its own as a new message. Do NOT poll, sleep or loop waiting for it. The `id` in that envelope is the task_id: pass it to task_status to read a result the notification did not deliver, or to task_cancel to stop a background subagent you no longer want.';
 var TASK_BATCH_TOOL_NAME = "task_batch";
 var TASK_BATCH_PROXY_NOTE = "Use this instead of several task calls in one response: Claude Code runs MCP tool calls one at a time, so separate task calls run serially even when emitted together, while one task_batch call fans them out as parallel opencode task calls. Each task takes the same fields as the task tool. Results come back in task order, each labelled. Like task it has no proxy deadline by default (a positive proxyToolTimeoutMs override adds one).";
 var TASK_INPUT_REQUIRED = ["description", "prompt", "subagent_type"];
@@ -1769,6 +1770,75 @@ function overlayQuestionProxyDescription(tools, liveDescription) {
 ${QUESTION_PROXY_NOTE}` } : t
   );
 }
+function liveTaskSupportsBackground(taskParameters, dialect = "v1") {
+  if (dialect === "v2") return true;
+  const properties = taskParameters?.properties;
+  if (!properties || typeof properties !== "object") return false;
+  return "background" in properties;
+}
+var BACKGROUND_TASK_TOOL_DEFS = [
+  {
+    name: "task_status",
+    description: "Read the current state of a background subagent started with `task` and `background: true`, and collect its result if it has finished. Use this only to recover a result opencode's automatic completion notification did not deliver (the turn was interrupted, errored, or was compacted across). It is NOT a progress poll: a healthy background task delivers its own result, so calling this in a loop spends turns and learns nothing. A result is handed over once; asking again reports the state without repeating the output.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: {
+          type: "string",
+          description: 'The id from the `<task id="..." state="running">` envelope the background dispatch returned.'
+        }
+      },
+      required: ["task_id"]
+    }
+  },
+  {
+    name: "task_cancel",
+    description: "Stop a background subagent started with `task` and `background: true`. Use it when the work is no longer wanted, has been superseded, or is running away. A cancelled subagent sends no completion notification. This cannot stop a foreground task call: those block this conversation and end on their own.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: {
+          type: "string",
+          description: 'The id from the `<task id="..." state="running">` envelope the background dispatch returned.'
+        }
+      },
+      required: ["task_id"]
+    }
+  }
+];
+function applyBackgroundSubagentSupport(tools, supported) {
+  if (!tools.some((t) => t.name === "task")) return tools;
+  const adjusted = tools.map((t) => {
+    if (t.name !== "task" && t.name !== TASK_BATCH_TOOL_NAME) return t;
+    if (supported) {
+      return { ...t, description: `${t.description}
+
+${TASK_BACKGROUND_NOTE}` };
+    }
+    return { ...t, inputSchema: stripBackgroundFromSchema(t.name, t.inputSchema) };
+  });
+  return supported ? [...adjusted, ...BACKGROUND_TASK_TOOL_DEFS] : adjusted;
+}
+function stripBackgroundFromSchema(toolName, schema) {
+  if (toolName === TASK_BATCH_TOOL_NAME) {
+    return {
+      ...schema,
+      properties: {
+        tasks: {
+          type: "array",
+          minItems: 2,
+          description: "Independent subagent tasks to run concurrently",
+          items: {
+            type: "object",
+            properties: TASK_INPUT_PROPERTIES_NO_BACKGROUND,
+            required: TASK_INPUT_REQUIRED
+          }
+        }
+      }
+    };
+  }
+  return { ...schema, properties: TASK_INPUT_PROPERTIES_NO_BACKGROUND };
+}
 function filterQuestionProxyByOpencodeSupport(tools, opencodeHasQuestion) {
   if (opencodeHasQuestion) return tools;
   return tools.filter((t) => t.name !== "question");
@@ -1796,9 +1866,12 @@ var TASK_INPUT_PROPERTIES = {
   },
   background: {
     type: "boolean",
-    description: "Run the task in the background when supported by opencode"
+    description: 'Run the subagent in the background and return immediately with a `<task id="..." state="running">` envelope instead of its answer. You are notified automatically when it completes. Do NOT sleep, poll or proactively check on its progress.'
   }
 };
+var TASK_INPUT_PROPERTIES_NO_BACKGROUND = Object.fromEntries(
+  Object.entries(TASK_INPUT_PROPERTIES).filter(([name]) => name !== "background")
+);
 var DEFAULT_PROXY_TOOLS = [
   {
     name: "bash",
@@ -2859,6 +2932,362 @@ function clearCompression(sessionKey2) {
   compressions.delete(sessionKey2);
 }
 
+// src/runtime-status.ts
+var opencodeClient = null;
+function setOpencodeClient(client) {
+  if (client && typeof client === "object") {
+    opencodeClient = client;
+  }
+}
+function getOpencodeClient() {
+  return opencodeClient;
+}
+var opencodeProjectDirectory;
+function setOpencodeProjectDirectory(dir) {
+  opencodeProjectDirectory = dir;
+}
+function getOpencodeProjectDirectory() {
+  return opencodeProjectDirectory;
+}
+function isUsableDirectory(d) {
+  return typeof d === "string" && d.length > 1 && d !== "/";
+}
+function resolveSpawnCwdFrom(configured, live, captured, sessionDir) {
+  if (configured) return configured;
+  if (isUsableDirectory(sessionDir)) return sessionDir;
+  if (isUsableDirectory(live)) return live;
+  return captured ?? live;
+}
+async function resolveSpawnCwdForSession(configured, sessionID) {
+  if (configured) return configured;
+  const sessionDir = sessionID ? await fetchSessionDirectory(sessionID) : void 0;
+  return resolveSpawnCwdFrom(
+    configured,
+    process.cwd(),
+    opencodeProjectDirectory,
+    sessionDir
+  );
+}
+async function fetchSessionDirectory(sessionID) {
+  if (!sessionID || sessionID === "default") return void 0;
+  const client = opencodeClient;
+  if (!client?.session?.get) return void 0;
+  try {
+    const res = await client.session.get({ path: { id: sessionID } });
+    const data = res.data;
+    if (!data || typeof data !== "object") return void 0;
+    const dir = data.directory;
+    return isUsableDirectory(dir) ? dir : void 0;
+  } catch (err) {
+    log.warn("failed to fetch opencode session directory", {
+      sessionID,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
+async function fetchSessionParentId(sessionID) {
+  if (!sessionID || sessionID === "default") return void 0;
+  const client = opencodeClient;
+  if (!client?.session?.get) return void 0;
+  try {
+    const res = await client.session.get({ path: { id: sessionID } });
+    const data = res.data;
+    if (!data || typeof data !== "object") return void 0;
+    const parentID = data.parentID;
+    return typeof parentID === "string" && parentID.length > 0 ? parentID : void 0;
+  } catch (err) {
+    log.warn("failed to fetch opencode session parent", {
+      sessionID,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
+async function fetchSessionRunState(sessionID) {
+  if (!sessionID || sessionID === "default") return "unknown";
+  const status = opencodeClient?.session?.status;
+  if (!status) return "unknown";
+  try {
+    const res = await status.call(opencodeClient.session);
+    const data = res.data;
+    if (!data || typeof data !== "object") return "unknown";
+    const entry = data[sessionID];
+    if (!entry || typeof entry !== "object") return "idle";
+    const type = entry.type;
+    return type === "idle" ? "idle" : "busy";
+  } catch (err) {
+    log.debug("failed to read opencode session status", {
+      sessionID,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return "unknown";
+  }
+}
+async function settleSessionRunState(sessionID, options = {}) {
+  const pollMs = options.pollMs ?? 150;
+  const windowMs = options.windowMs ?? 1500;
+  const started = Date.now();
+  let last = "unknown";
+  for (; ; ) {
+    const state = await fetchSessionRunState(sessionID);
+    if (state === "busy") return "busy";
+    if (state !== "unknown") last = state;
+    if (Date.now() - started >= windowMs) return last;
+    await new Promise((resolve6) => setTimeout(resolve6, pollMs));
+  }
+}
+async function getRuntimeMcpStatus() {
+  const client = opencodeClient;
+  if (!client?.mcp?.status) return void 0;
+  try {
+    const res = await client.mcp.status();
+    const data = res.data;
+    if (!data || typeof data !== "object") return void 0;
+    const out = {};
+    for (const [name, entry] of Object.entries(data)) {
+      if (entry && typeof entry === "object") {
+        const status = entry.status;
+        if (typeof status === "string") out[name] = status;
+      }
+    }
+    return out;
+  } catch (err) {
+    log.warn("failed to fetch opencode MCP runtime status", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
+async function fetchOpencodeToolList(provider, model, directory) {
+  const client = opencodeClient;
+  if (!client?.tool?.list) return void 0;
+  try {
+    const res = await client.tool.list({
+      query: { provider, model, ...directory ? { directory } : {} }
+    });
+    const data = res.data;
+    if (!Array.isArray(data)) return void 0;
+    const out = [];
+    for (const entry of data) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      const id = typeof e.id === "string" ? e.id : null;
+      const description = typeof e.description === "string" ? e.description : "";
+      const parameters = e.parameters && typeof e.parameters === "object" ? e.parameters : {};
+      if (!id) continue;
+      out.push({ id, description, parameters });
+    }
+    return out;
+  } catch (err) {
+    log.warn("failed to fetch opencode tool list", {
+      provider,
+      model,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
+async function fetchSessionReplies(sessionID) {
+  if (!sessionID || sessionID === "default") return void 0;
+  const client = opencodeClient;
+  if (!client?.session?.messages) return void 0;
+  try {
+    const res = await client.session.messages({ path: { id: sessionID } });
+    const data = res.data;
+    if (!Array.isArray(data)) return void 0;
+    const out = [];
+    for (const entry of data) {
+      if (!entry || typeof entry !== "object") continue;
+      const info = entry.info;
+      if (!info || typeof info !== "object") continue;
+      const record = info;
+      const parts = entry.parts;
+      const text = Array.isArray(parts) ? parts.flatMap((part) => {
+        if (!part || typeof part !== "object") return [];
+        const p = part;
+        if (p.type !== "text" || typeof p.text !== "string") return [];
+        return p.synthetic === true ? [] : [p.text];
+      }).join("\n").trim() : "";
+      const error = record.error;
+      const message = error && typeof error === "object" ? typeof error.data?.message === "string" ? error.data.message : typeof error.name === "string" ? error.name : void 0 : void 0;
+      out.push({
+        role: typeof record.role === "string" ? record.role : "",
+        completed: typeof record.time?.completed === "number",
+        error: message,
+        text
+      });
+    }
+    return out;
+  } catch (err) {
+    log.warn("failed to fetch opencode session messages", {
+      sessionID,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return void 0;
+  }
+}
+async function abortSession(sessionID) {
+  if (!sessionID || sessionID === "default") return false;
+  const client = opencodeClient;
+  if (!client?.session?.abort) return false;
+  try {
+    await client.session.abort({ path: { id: sessionID } });
+    return true;
+  } catch (err) {
+    log.warn("failed to abort opencode session", {
+      sessionID,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return false;
+  }
+}
+
+// src/background-tasks.ts
+var TASK_STATUS_TOOL_NAME = "task_status";
+var TASK_CANCEL_TOOL_NAME = "task_cancel";
+var MAX_LEDGERS = 32;
+var MAX_COLLECTED_PER_SESSION = 64;
+var collected = /* @__PURE__ */ new Map();
+function ledgerFor(sessionKey2) {
+  let ids = collected.get(sessionKey2);
+  if (!ids) {
+    ids = /* @__PURE__ */ new Set();
+    collected.set(sessionKey2, ids);
+    while (collected.size > MAX_LEDGERS) {
+      const oldest = collected.keys().next();
+      if (oldest.done) break;
+      collected.delete(oldest.value);
+    }
+  }
+  return ids;
+}
+function markCollected(sessionKey2, taskId) {
+  const ids = ledgerFor(sessionKey2);
+  ids.add(taskId);
+  while (ids.size > MAX_COLLECTED_PER_SESSION) {
+    const oldest = ids.values().next();
+    if (oldest.done) break;
+    ids.delete(oldest.value);
+  }
+}
+function hasCollectedBackgroundTask(sessionKey2, taskId) {
+  return collected.get(sessionKey2)?.has(taskId) === true;
+}
+function clearBackgroundTasks(sessionKey2) {
+  collected.delete(sessionKey2);
+}
+function readTaskId(input) {
+  const raw = input.task_id ?? input.taskId ?? input.sessionID;
+  if (typeof raw !== "string") return null;
+  const id = raw.trim();
+  return id.length > 0 ? id : null;
+}
+var MISSING_TASK_ID = 'task_id is required: pass the id from the `<task id="...">` envelope the background dispatch returned.';
+async function guardParent(taskId, callerSessionId) {
+  if (!callerSessionId || callerSessionId === "default") {
+    return `Cannot check that task_id ${taskId} belongs to this conversation (this turn has no opencode session id), so it is not inspected or cancelled.`;
+  }
+  const parent = await fetchSessionParentId(taskId);
+  if (parent === callerSessionId) return null;
+  return `task_id ${taskId} is not a subagent of this conversation, so it cannot be inspected or cancelled from here. Use the id from a \`<task id="...">\` envelope this conversation received.`;
+}
+function lastAssistantReply(replies) {
+  for (let index = replies.length - 1; index >= 0; index--) {
+    const reply = replies[index];
+    if (reply.role === "assistant") return reply;
+  }
+  return void 0;
+}
+async function collectBackgroundTask(input, options) {
+  const taskId = readTaskId(input);
+  if (!taskId) return { kind: "error", message: MISSING_TASK_ID };
+  const refused = await guardParent(taskId, options.callerSessionId);
+  if (refused) return { kind: "error", message: refused };
+  const replies = await fetchSessionReplies(taskId);
+  if (replies === void 0) {
+    return {
+      kind: "error",
+      message: `Could not read background task ${taskId} from opencode. It may have been deleted, or this opencode build does not expose the session transcript. The completion notification is still the primary delivery path: end your turn and wait for it.`
+    };
+  }
+  const runState = await fetchSessionRunState(taskId);
+  if (runState === "busy") {
+    return {
+      kind: "text",
+      text: `<task id="${taskId}" state="running">
+Still working. Do not call this again in a loop: when it finishes opencode delivers the result to this conversation on its own. End your turn, or work on something that does not overlap it.
+</task>`
+    };
+  }
+  const reply = lastAssistantReply(replies);
+  if (!reply) {
+    return {
+      kind: "text",
+      text: `<task id="${taskId}" state="unknown">
+opencode has no assistant reply for this task yet and it is not running. It may still be starting up.
+</task>`
+    };
+  }
+  if (reply.error) {
+    markCollected(options.sessionKey, taskId);
+    return {
+      kind: "text",
+      isError: true,
+      text: `<task id="${taskId}" state="error">
+${reply.error}
+</task>`
+    };
+  }
+  if (hasCollectedBackgroundTask(options.sessionKey, taskId)) {
+    return {
+      kind: "text",
+      text: `<task id="${taskId}" state="completed">
+Already delivered to this conversation earlier (by this tool or by opencode's completion notification). Scroll back for the result rather than collecting it again.
+</task>`
+    };
+  }
+  markCollected(options.sessionKey, taskId);
+  log.info("collected background subagent result", {
+    sessionKey: options.sessionKey,
+    taskId,
+    textLength: reply.text.length
+  });
+  return {
+    kind: "text",
+    text: `<task id="${taskId}" state="completed">
+<task_result>
+${reply.text || "(the subagent produced no text)"}
+</task_result>
+</task>`
+  };
+}
+async function cancelBackgroundTask(input, options) {
+  const taskId = readTaskId(input);
+  if (!taskId) return { kind: "error", message: MISSING_TASK_ID };
+  const refused = await guardParent(taskId, options.callerSessionId);
+  if (refused) return { kind: "error", message: refused };
+  const before = await fetchSessionRunState(taskId);
+  const aborted = await abortSession(taskId);
+  if (!aborted) {
+    return {
+      kind: "error",
+      message: `Could not cancel background task ${taskId}: opencode did not accept the abort. It may have already finished, or this opencode build does not expose session abort.`
+    };
+  }
+  collected.get(options.sessionKey)?.delete(taskId);
+  log.info("cancelled background subagent", {
+    sessionKey: options.sessionKey,
+    taskId,
+    wasRunning: before === "busy"
+  });
+  return {
+    kind: "text",
+    text: `<task id="${taskId}" state="cancelled">
+` + (before === "busy" ? "Stopped. No completion notification will arrive for it." : "It was not running when the cancel was sent, so nothing was interrupted. No completion notification will arrive for it.") + "\n</task>"
+  };
+}
+
 // src/permission-presets.ts
 var READ_ONLY_DISALLOWED_CLI_TOOLS = [
   "Bash",
@@ -3395,11 +3824,13 @@ function deleteActiveProcessesForSession(sessionID) {
     clearCompression(key);
     if (!released.includes(key)) released.push(key);
   }
+  for (const key of released) clearBackgroundTasks(key);
   return released;
 }
 function killAllActiveProcesses() {
   const keys = [...activeProcesses.keys()];
   for (const key of keys) deleteActiveProcess(key);
+  for (const key of keys) clearBackgroundTasks(key);
   return keys;
 }
 var processExitCleanupWired = false;
@@ -3511,6 +3942,7 @@ function invalidateOtherEffortSessions(baseKey, effort) {
     deleteActiveProcess(key);
     deleteClaudeSessionId(key);
     clearCompression(key);
+    clearBackgroundTasks(key);
   }
 }
 function spawnClaudeProcess(cliPath, cliArgs, cwd, sessionKey2, proxyServer, mcpHash, systemPromptFile, ignoreAnthropicApiKey, effort, promptCacheTtl) {
@@ -4497,163 +4929,6 @@ function finishBridge(input) {
   };
 }
 
-// src/runtime-status.ts
-var opencodeClient = null;
-function setOpencodeClient(client) {
-  if (client && typeof client === "object") {
-    opencodeClient = client;
-  }
-}
-function getOpencodeClient() {
-  return opencodeClient;
-}
-var opencodeProjectDirectory;
-function setOpencodeProjectDirectory(dir) {
-  opencodeProjectDirectory = dir;
-}
-function getOpencodeProjectDirectory() {
-  return opencodeProjectDirectory;
-}
-function isUsableDirectory(d) {
-  return typeof d === "string" && d.length > 1 && d !== "/";
-}
-function resolveSpawnCwdFrom(configured, live, captured, sessionDir) {
-  if (configured) return configured;
-  if (isUsableDirectory(sessionDir)) return sessionDir;
-  if (isUsableDirectory(live)) return live;
-  return captured ?? live;
-}
-async function resolveSpawnCwdForSession(configured, sessionID) {
-  if (configured) return configured;
-  const sessionDir = sessionID ? await fetchSessionDirectory(sessionID) : void 0;
-  return resolveSpawnCwdFrom(
-    configured,
-    process.cwd(),
-    opencodeProjectDirectory,
-    sessionDir
-  );
-}
-async function fetchSessionDirectory(sessionID) {
-  if (!sessionID || sessionID === "default") return void 0;
-  const client = opencodeClient;
-  if (!client?.session?.get) return void 0;
-  try {
-    const res = await client.session.get({ path: { id: sessionID } });
-    const data = res.data;
-    if (!data || typeof data !== "object") return void 0;
-    const dir = data.directory;
-    return isUsableDirectory(dir) ? dir : void 0;
-  } catch (err) {
-    log.warn("failed to fetch opencode session directory", {
-      sessionID,
-      error: err instanceof Error ? err.message : String(err)
-    });
-    return void 0;
-  }
-}
-async function fetchSessionParentId(sessionID) {
-  if (!sessionID || sessionID === "default") return void 0;
-  const client = opencodeClient;
-  if (!client?.session?.get) return void 0;
-  try {
-    const res = await client.session.get({ path: { id: sessionID } });
-    const data = res.data;
-    if (!data || typeof data !== "object") return void 0;
-    const parentID = data.parentID;
-    return typeof parentID === "string" && parentID.length > 0 ? parentID : void 0;
-  } catch (err) {
-    log.warn("failed to fetch opencode session parent", {
-      sessionID,
-      error: err instanceof Error ? err.message : String(err)
-    });
-    return void 0;
-  }
-}
-async function fetchSessionRunState(sessionID) {
-  if (!sessionID || sessionID === "default") return "unknown";
-  const status = opencodeClient?.session?.status;
-  if (!status) return "unknown";
-  try {
-    const res = await status.call(opencodeClient.session);
-    const data = res.data;
-    if (!data || typeof data !== "object") return "unknown";
-    const entry = data[sessionID];
-    if (!entry || typeof entry !== "object") return "idle";
-    const type = entry.type;
-    return type === "idle" ? "idle" : "busy";
-  } catch (err) {
-    log.debug("failed to read opencode session status", {
-      sessionID,
-      error: err instanceof Error ? err.message : String(err)
-    });
-    return "unknown";
-  }
-}
-async function settleSessionRunState(sessionID, options = {}) {
-  const pollMs = options.pollMs ?? 150;
-  const windowMs = options.windowMs ?? 1500;
-  const started = Date.now();
-  let last = "unknown";
-  for (; ; ) {
-    const state = await fetchSessionRunState(sessionID);
-    if (state === "busy") return "busy";
-    if (state !== "unknown") last = state;
-    if (Date.now() - started >= windowMs) return last;
-    await new Promise((resolve6) => setTimeout(resolve6, pollMs));
-  }
-}
-async function getRuntimeMcpStatus() {
-  const client = opencodeClient;
-  if (!client?.mcp?.status) return void 0;
-  try {
-    const res = await client.mcp.status();
-    const data = res.data;
-    if (!data || typeof data !== "object") return void 0;
-    const out = {};
-    for (const [name, entry] of Object.entries(data)) {
-      if (entry && typeof entry === "object") {
-        const status = entry.status;
-        if (typeof status === "string") out[name] = status;
-      }
-    }
-    return out;
-  } catch (err) {
-    log.warn("failed to fetch opencode MCP runtime status", {
-      error: err instanceof Error ? err.message : String(err)
-    });
-    return void 0;
-  }
-}
-async function fetchOpencodeToolList(provider, model, directory) {
-  const client = opencodeClient;
-  if (!client?.tool?.list) return void 0;
-  try {
-    const res = await client.tool.list({
-      query: { provider, model, ...directory ? { directory } : {} }
-    });
-    const data = res.data;
-    if (!Array.isArray(data)) return void 0;
-    const out = [];
-    for (const entry of data) {
-      if (!entry || typeof entry !== "object") continue;
-      const e = entry;
-      const id = typeof e.id === "string" ? e.id : null;
-      const description = typeof e.description === "string" ? e.description : "";
-      const parameters = e.parameters && typeof e.parameters === "object" ? e.parameters : {};
-      if (!id) continue;
-      out.push({ id, description, parameters });
-    }
-    return out;
-  } catch (err) {
-    log.warn("failed to fetch opencode tool list", {
-      provider,
-      model,
-      error: err instanceof Error ? err.message : String(err)
-    });
-    return void 0;
-  }
-}
-
 // src/startup-diagnostics.ts
 var cachedPluginVersion;
 function pluginVersion() {
@@ -6560,6 +6835,69 @@ function interactiveSpawnEnv(opts) {
     ...opts.effort ? { CLAUDE_CODE_EFFORT_LEVEL: opts.effort } : {}
   };
 }
+function usageInputSide(usage) {
+  return (usage?.input_tokens ?? 0) + (usage?.cache_read_input_tokens ?? 0) + (usage?.cache_creation_input_tokens ?? 0);
+}
+function isApiCallRecord(rec) {
+  if (!rec || rec.type !== "assistant" || !rec.message) return false;
+  return usageInputSide(rec.message.usage) > 0;
+}
+var TurnUsageAccumulator = class {
+  calls = /* @__PURE__ */ new Map();
+  lastKey = null;
+  /** Feed every transcript record of the turn, in file order. */
+  add(rec) {
+    if (!isApiCallRecord(rec)) return;
+    const id = rec.message.id;
+    const key = typeof id === "string" && id.length > 0 ? id : `uuid:${rec.uuid ?? this.calls.size}`;
+    this.calls.set(key, rec.message.usage);
+    this.lastKey = key;
+  }
+  /** Distinct API calls seen, for diagnostics. */
+  get callCount() {
+    return this.calls.size;
+  }
+  /**
+   * The newest real call's usage, verbatim (its own `iterations` included):
+   * the conversation's context occupancy, which is what a finish must report.
+   * See `lastCallContextUsage` in `usage.ts`, the one convention for this.
+   */
+  get lastCall() {
+    return this.lastKey === null ? null : this.calls.get(this.lastKey) ?? null;
+  }
+  /**
+   * The turn summed over DISTINCT calls: the shape and the meaning of a
+   * headless `result` frame's usage, which is what `total_cost_usd` and
+   * `turnStats` are about. Deliberately carries no `iterations`: that is one
+   * response's server-side field and a sum of calls has no such list, so
+   * `toUsage` falls back to these flat counters, while `lastCall` keeps its
+   * own for `lastCallContextUsage` to read.
+   */
+  get turnTotal() {
+    if (this.calls.size === 0) return null;
+    const total = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+      cache_creation: {
+        ephemeral_1h_input_tokens: 0,
+        ephemeral_5m_input_tokens: 0
+      },
+      output_tokens_details: { thinking_tokens: 0 }
+    };
+    for (const u of this.calls.values()) {
+      total.input_tokens += u.input_tokens ?? 0;
+      total.output_tokens += u.output_tokens ?? 0;
+      total.cache_read_input_tokens += u.cache_read_input_tokens ?? 0;
+      total.cache_creation_input_tokens += u.cache_creation_input_tokens ?? 0;
+      total.cache_creation.ephemeral_1h_input_tokens += u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+      total.cache_creation.ephemeral_5m_input_tokens += u.cache_creation?.ephemeral_5m_input_tokens ?? 0;
+      total.output_tokens_details.thinking_tokens += u.output_tokens_details?.thinking_tokens ?? 0;
+    }
+    return total;
+  }
+};
 var TERMINAL_STOP = /* @__PURE__ */ new Set(["end_turn", "stop_sequence", "max_tokens"]);
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 function resolveConfigDir(configDir) {
@@ -6754,8 +7092,8 @@ var ClaudeSession = class {
       this.proc.terminal.write(prompt);
     }
     await this.submitTurn();
-    const collected = [];
-    let lastUsage = null;
+    const collected2 = [];
+    const usage = new TurnUsageAccumulator();
     let stopReason = null;
     const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
@@ -6779,9 +7117,9 @@ var ClaudeSession = class {
         if (rec.type === "assistant" && rec.message) {
           for (const b of rec.message.content ?? []) {
             if (b?.type === "text" && typeof b.text === "string")
-              collected.push(b.text);
+              collected2.push(b.text);
           }
-          if (rec.message.usage) lastUsage = rec.message.usage;
+          usage.add(rec);
           if (rec.message.stop_reason && TERMINAL_STOP.has(rec.message.stop_reason)) {
             stopReason = rec.message.stop_reason;
           }
@@ -6793,15 +7131,17 @@ var ClaudeSession = class {
     if (!stopReason) {
       throw new Error(
         this.failureMessage(
-          `turn timed out after ${timeout}ms (no terminal assistant record; collected ${collected.length} text block(s))`
+          `turn timed out after ${timeout}ms (no terminal assistant record; collected ${collected2.length} text block(s))`
         )
       );
     }
-    const u = lastUsage ?? {};
+    const turnTotal = usage.turnTotal;
+    const u = turnTotal ?? {};
     return {
-      text: collected.join("\n").trim(),
+      text: collected2.join("\n").trim(),
       stopReason,
-      usage: lastUsage,
+      usage: turnTotal,
+      lastCallUsage: usage.lastCall,
       cacheReadTokens: u.cache_read_input_tokens ?? 0,
       cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
       ephemeral1hTokens: u.cache_creation?.ephemeral_1h_input_tokens ?? 0,
@@ -6814,9 +7154,15 @@ var ClaudeSession = class {
   /**
    * Like ask(), but instead of collecting the reply text it re-emits each NEW
    * raw JSONL transcript line via onLine (verbatim) until a terminal
-   * stop_reason. Returns the terminal stop_reason + the last assistant usage.
-   * Used by the opencode plugin transport shim, which feeds these raw lines
-   * into the existing stream-json line handler unchanged.
+   * stop_reason. Used by the opencode plugin transport shim, which feeds
+   * these raw lines into the existing stream-json line handler unchanged.
+   *
+   * `usage` is the turn summed over DISTINCT API calls, which is exactly what
+   * a headless `result` frame reports, so the shim can synthesize one and
+   * every downstream consumer (the finish's `lastCallContextUsage`,
+   * `turnStats`) behaves as it does on the headless path. `lastCallUsage` is
+   * the newest real call, returned because a caller with no stream parser
+   * (`askOnce`) has no other way to get the context side.
    */
   async tailTurn(prompt, onLine, perTurnTimeoutMs) {
     if (this.aborted) throw new Error("aborted");
@@ -6829,8 +7175,7 @@ var ClaudeSession = class {
       this.proc.terminal.write(prompt);
     }
     await this.submitTurn();
-    let lastUsage = null;
-    let totalOutput = 0;
+    const usage = new TurnUsageAccumulator();
     let stopReason = null;
     const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
@@ -6854,11 +7199,8 @@ var ClaudeSession = class {
         } catch {
           continue;
         }
+        usage.add(rec);
         if (rec.type === "assistant" && rec.message) {
-          if (rec.message.usage) {
-            lastUsage = rec.message.usage;
-            totalOutput += rec.message.usage.output_tokens ?? 0;
-          }
           if (rec.message.stop_reason && TERMINAL_STOP.has(rec.message.stop_reason)) {
             stopReason = rec.message.stop_reason;
           }
@@ -6867,18 +7209,6 @@ var ClaudeSession = class {
       this.cursor = lastComplete;
       if (stopReason) break;
     }
-    let usage = lastUsage;
-    if (lastUsage) {
-      usage = { ...lastUsage, output_tokens: totalOutput };
-      if (Array.isArray(lastUsage.iterations) && lastUsage.iterations.length > 0) {
-        const iters = lastUsage.iterations.map((it) => ({ ...it }));
-        iters[iters.length - 1] = {
-          ...iters[iters.length - 1],
-          output_tokens: totalOutput
-        };
-        usage.iterations = iters;
-      }
-    }
     if (!stopReason) {
       throw new Error(
         this.failureMessage(
@@ -6886,7 +7216,12 @@ var ClaudeSession = class {
         )
       );
     }
-    return { stopReason, usage };
+    return {
+      stopReason,
+      usage: usage.turnTotal,
+      lastCallUsage: usage.lastCall,
+      callCount: usage.callCount
+    };
   }
   dispose() {
     if (this.proc) {
@@ -7025,9 +7360,18 @@ function spawnInteractiveProcess(opts) {
     void (async () => {
       try {
         await ensureStarted();
-        const { stopReason, usage } = await session.tailTurn(userMsg, (raw) => {
+        const { stopReason, usage, lastCallUsage, callCount } = await session.tailTurn(userMsg, (raw) => {
           lineEmitter.emit("line", raw);
         });
+        log.info("interactive turn usage", {
+          apiCalls: callCount,
+          turnOutputTokens: usage?.output_tokens,
+          turnInputTokens: usage?.input_tokens,
+          turnCacheReadTokens: usage?.cache_read_input_tokens,
+          lastCallInputTokens: lastCallUsage?.input_tokens,
+          lastCallCacheReadTokens: lastCallUsage?.cache_read_input_tokens,
+          lastCallCacheWriteTokens: lastCallUsage?.cache_creation_input_tokens
+        });
         const timedOut = !stopReason;
         emitResult(
           timedOut ? "error_during_execution" : stopReason,
@@ -7143,6 +7487,14 @@ Subagent dispatch in this environment goes through exactly two tools: \`mcp__ope
 - If that tool is not in your visible tool list it is deferred \u2014 load it with ToolSearch (\`select:mcp__opencode_proxy__task\`), then call it.
 - Claude Code's built-in TaskCreate/TaskUpdate/TaskList manage a local todo list. They cannot dispatch subagents; creating a task there runs nothing. Never report a subagent as dispatched unless \`mcp__opencode_proxy__task\` returned its result.
 - Do not verify a subagent's existence by searching config files \u2014 the tool's description lists the available agent types, and invalid types fail fast with a clear error.`;
+var BACKGROUND_SUBAGENT_HINT = `## Background subagents
+
+This opencode host runs background subagents, so \`mcp__opencode_proxy__task\` takes \`background: true\`.
+
+- A background dispatch returns at once with \`<task id="ses_..." state="running">\` instead of the subagent's answer. That is success, not a truncated result.
+- After starting one, keep working on something that does not overlap it, then end your turn normally. When the subagent finishes, opencode delivers its result into this conversation as a new message on its own. Do not sleep, poll, or ask the operator to wait.
+- The \`id\` in that envelope is the task_id. \`mcp__opencode_proxy__task_status\` reads a result back if the automatic delivery did not arrive (an interrupted or errored turn); \`mcp__opencode_proxy__task_cancel\` stops a background subagent you no longer want. Neither is a progress poll.
+- Foreground is still the default and still the right choice when you need the answer before you can continue. Use background only for work that genuinely runs alongside yours.`;
 var QUESTION_PROXY_HINT = `## Asking the operator questions
 
 Structured questions in this environment go through exactly one tool: \`mcp__opencode_proxy__question\`.
@@ -7714,9 +8066,11 @@ async function fetchLiveToolInfo(config, modelId) {
     config.cwd
   );
   const question = items?.find((item) => item.id === "question");
+  const task = items?.find((item) => item.id === "task");
   return {
     resolved: items !== void 0,
-    taskDescription: items?.find((item) => item.id === "task")?.description,
+    taskDescription: task?.description,
+    taskParameters: task?.parameters,
     questionDescription: question?.description,
     hasQuestion: !!question,
     items
@@ -7759,9 +8113,14 @@ async function resolvePlanModeQuestion(config, compactionMode, loadLiveToolInfo)
   }
   return active;
 }
-async function ensureProxyServer(config, tools, sessionKeyForCalls, interceptCompress) {
+async function ensureProxyServer(config, tools, sessionKeyForCalls, interceptCompress, callerSessionId) {
   const timeoutOverrides = config.proxyToolTimeoutMs;
   const interceptors = /* @__PURE__ */ new Map();
+  if (tools.some((t) => t.name === TASK_STATUS_TOOL_NAME)) {
+    const opts = { sessionKey: sessionKeyForCalls, callerSessionId };
+    interceptors.set(TASK_STATUS_TOOL_NAME, (input) => collectBackgroundTask(input, opts));
+    interceptors.set(TASK_CANCEL_TOOL_NAME, (input) => cancelBackgroundTask(input, opts));
+  }
   if (interceptCompress && tools.some((t) => t.name === "compress")) {
     interceptors.set("compress", (input) => {
       const summary = typeof input.summary === "string" ? input.summary.trim() : "";
@@ -9379,12 +9738,13 @@ var ClaudeCodeLanguageModel = class {
    * Create a proxy MCP server for a single active Claude process/session.
    * The process lifecycle owns the server lifecycle via session-manager.
    */
-  async ensureProxyServer(tools, sessionKeyForCalls, interceptCompress) {
+  async ensureProxyServer(tools, sessionKeyForCalls, interceptCompress, callerSessionId) {
     return ensureProxyServer(
       this.config,
       tools,
       sessionKeyForCalls,
-      interceptCompress
+      interceptCompress,
+      callerSessionId
     );
   }
   /**
@@ -10167,10 +10527,12 @@ var ClaudeCodeLanguageModel = class {
               const liveToolInfo = taskProxyEnabled || questionProxyEnabled || opencodeToolsRequested ? await loadLiveToolInfo() : {
                 resolved: false,
                 taskDescription: void 0,
+                taskParameters: void 0,
                 questionDescription: void 0,
                 hasQuestion: false
               };
               let enrichedProxy = resolvedProxy;
+              let backgroundSubagentsSupported = false;
               if (enrichedProxy && taskProxyEnabled) {
                 enrichedProxy = overlayTaskProxyDescription(
                   enrichedProxy,
@@ -10185,6 +10547,20 @@ var ClaudeCodeLanguageModel = class {
                     )
                   )
                 });
+                backgroundSubagentsSupported = liveTaskSupportsBackground(
+                  liveToolInfo.taskParameters,
+                  self.config.hostApi === "v2" ? "v2" : "v1"
+                );
+                enrichedProxy = applyBackgroundSubagentSupport(
+                  enrichedProxy,
+                  backgroundSubagentsSupported
+                );
+                log.info("background subagent gate", {
+                  supported: backgroundSubagentsSupported,
+                  registryResolved: liveToolInfo.resolved,
+                  hostApi: self.config.hostApi ?? "v1",
+                  note: backgroundSubagentsSupported ? "task accepts `background`; task_status and task_cancel are registered" : "`background` stripped from the task schema; set OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in opencode's environment to enable it"
+                });
               }
               if (enrichedProxy && questionProxyEnabled) {
                 enrichedProxy = overlayQuestionProxyDescription(
@@ -10225,7 +10601,8 @@ var ClaudeCodeLanguageModel = class {
                 state.proxyServer = await self.ensureProxyServer(
                   combinedProxyTools,
                   sk,
-                  pluginCompressEnabled
+                  pluginCompressEnabled,
+                  affinity
                 );
               }
               const questionProxyActive = enrichedProxy?.some((t) => t.name === "question") ?? false;
@@ -10246,6 +10623,7 @@ var ClaudeCodeLanguageModel = class {
                 [
                   ...extractSystemMessages(options.prompt),
                   ...taskProxyEnabled ? [SUBAGENT_DISPATCH_HINT] : [],
+                  ...backgroundSubagentsSupported ? [BACKGROUND_SUBAGENT_HINT] : [],
                   ...questionProxyActive ? [QUESTION_PROXY_HINT] : []
                 ],
                 {