talon-agent 5.0.1 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -99,7 +99,7 @@
     "build:fusefs": "node native/talon-fusefs/build.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.197",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.277",
     "@anthropic-ai/sdk": "^0.104.1",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",

package/src/backend/claude-sdk/handler.ts

@@ -156,23 +156,48 @@ function createPostResultWatchdog(
 }
 
 // ── Active query store ──────────────────────────────────────────────────────
-// Holds the Query reference for each in-flight chat so gateway actions
-// (e.g. reload_plugins) can call control methods like setMcpServers().
+// Holds the in-flight turn for each chat so gateway actions (e.g.
+// reload_plugins) can call control methods like setMcpServers(), and so a
+// user-driven stop can mark the very turn it interrupts.
 
-const activeQueries = new Map<string, Query>();
+type ActiveTurn = {
+  qi: Query;
+  /**
+   * Set by `interruptChatTurn` the moment a stop is requested. The turn's
+   * close-out reads it to tell a deliberate stop from a fault: whatever
+   * the SDK does after an interrupt is the stop.
+   *
+   * Since SDK 0.3.x that is emphatically not a clean `result`. The CLI
+   * emits an `is_error` result whose `errors[]` holds only an
+   * `[ede_diagnostic] …` line, `Query.readMessages` keeps it as
+   * `lastErrorResultText`, and when the underlying stream then errors the
+   * SDK replaces the error with `Error("Claude Code returned an error
+   * result: " + lastErrorResultText)`. Unmarked, that reads as a genuine
+   * SDK failure: an ERROR log per /stop, failed-turn accounting, and a
+   * fallback-model retry of the turn the user just stopped.
+   */
+  interrupted: boolean;
+};
+
+const activeQueries = new Map<string, ActiveTurn>();
 
 /**
  * Best-effort graceful interrupt of a chat's in-flight turn. Uses the SDK's
- * native `Query.interrupt()`, which stops the agent loop and closes the stream
- * with a `result` (subtype `interrupt`) — so the turn ends as a normal
- * completion (turn_end + usage), NOT an error, and never trips the
- * model-fallback retry path. No-op (returns false) when no turn is running.
+ * native `Query.interrupt()`, which stops the agent loop — so the turn ends
+ * as a normal completion (turn_end + usage), NOT an error, and never trips
+ * the model-fallback retry path.
+ *
+ * The turn is marked BEFORE the native interrupt is fired, exactly as the
+ * shared `runtime/turn/turn-interrupt.ts` marks `state.turnTerminated`
+ * first: the mark, not the SDK's own close-out shape, is what makes the
+ * contract above true. No-op (returns false) when no turn is running.
  */
 export async function interruptChatTurn(chatId: string): Promise<boolean> {
-  const qi = activeQueries.get(chatId);
-  if (!qi) return false;
+  const active = activeQueries.get(chatId);
+  if (!active) return false;
+  active.interrupted = true;
   try {
-    await qi.interrupt();
+    await active.qi.interrupt();
     log("agent", `[${chatId}] turn interrupted by user`);
     incrementCounter("sdk.turn_interrupted");
     return true;
@@ -187,7 +212,7 @@ export async function interruptChatTurn(chatId: string): Promise<boolean> {
 
 /** Get the active Query for a chat, if one is in flight. */
 export function getActiveQuery(chatId: string): Query | undefined {
-  return activeQueries.get(chatId);
+  return activeQueries.get(chatId)?.qi;
 }
 
 // ── Internal state passed across recursive retry calls ──────────────────────
@@ -428,12 +453,6 @@ function accountFailedClaudeTurn(
   model: string,
   durationMs: number,
 ): void {
-  const sawResultUsage =
-    state.sdkInputTokens +
-      state.sdkOutputTokens +
-      state.sdkCacheRead +
-      state.sdkCacheWrite >
-    0;
   accountFailedTurn({
     backend: "claude",
     chatId,
@@ -441,7 +460,7 @@ function accountFailedClaudeTurn(
     durationMs,
     model,
     apiCalls: state.numApiCalls || live.calls,
-    usage: sawResultUsage
+    usage: sawResultUsage(state)
       ? turnUsageSnapshot(state)
       : {
           inputTokens: live.input,
@@ -452,6 +471,37 @@ function accountFailedClaudeTurn(
   });
 }
 
+/** Whether the turn's `result` message reported any tokens at all. */
+function sawResultUsage(state: StreamState): boolean {
+  return (
+    state.sdkInputTokens +
+      state.sdkOutputTokens +
+      state.sdkCacheRead +
+      state.sdkCacheWrite >
+    0
+  );
+}
+
+/**
+ * Close out a turn the user stopped. An interrupt is a completion, so it
+ * accounts like one (`accountTurn`, not `accountFailedTurn` — nothing
+ * failed) — but the `result` message may never have landed, leaving
+ * `state.sdk*` at zero while the per-API-call accumulator holds what the
+ * turn really burned. Fold the accumulator in so a stop doesn't lose the
+ * tokens, and mark the turn terminated so the flow-violation re-prompt
+ * can't resurrect what the user just stopped (the same guarantee
+ * `runtime/turn/turn-interrupt.ts` gives the callback backends).
+ */
+function closeInterruptedTurn(state: StreamState, live: LiveUsage): void {
+  state.turnTerminated = true;
+  if (sawResultUsage(state)) return;
+  state.sdkInputTokens = live.input;
+  state.sdkOutputTokens = live.output;
+  state.sdkCacheRead = live.cacheRead;
+  state.sdkCacheWrite = live.cacheWrite;
+  if (!state.numApiCalls) state.numApiCalls = live.calls;
+}
+
 /**
  * The aggregate `cache=NN%` can't distinguish a turn that reused the
  * previous turn's prefix from one that re-wrote it — see
@@ -488,6 +538,105 @@ function reportCacheVerdict(
   noteLookbackRisk(chatId, state.toolCalls);
 }
 
+// ── Stream phase ────────────────────────────────────────────────────────────
+
+/** What the stream phase left for the rest of the turn to do. */
+type StreamOutcome =
+  /** Run the normal post-stream phases (this includes every user stop). */
+  | { kind: "ok" }
+  /** A retry already ran to completion and yielded its own events. */
+  | { kind: "retried" }
+  /** Terminal failure — account for it and yield this `error` event. */
+  | { kind: "failed"; event: AgentEvent };
+
+/**
+ * Drive the SDK stream to exhaustion and decide what its ending means.
+ * Owns the error recovery (retry decision, model fallback) and the
+ * user-interrupt contract; releases the watchdog timer and the
+ * `activeQueries` entry on every exit.
+ */
+async function* runTurnStream(inputs: {
+  chatId: string;
+  params: ChatRunParams;
+  internal: InternalState;
+  active: ActiveTurn;
+  state: StreamState;
+  live: LiveUsage;
+  watchdog: PostResultWatchdog;
+  /** Model the turn is accounted against. */
+  activeModel: string;
+  /** Model string the SDK attributes the result message's usage to. */
+  sdkModel: string;
+}): AsyncGenerator<AgentEvent, StreamOutcome, void> {
+  const { chatId, active, state, live, watchdog } = inputs;
+  try {
+    yield* consumeSdkStream({
+      chatId,
+      qi: active.qi,
+      state,
+      live,
+      watchdog,
+      model: inputs.sdkModel,
+      pendingTools: new Map(),
+    });
+    // The SDK doesn't throw on API errors — it converts them into a
+    // synthetic assistant message and finishes the turn with an error-
+    // flagged result (usage limits, 429s, auth failures all land here).
+    // Rethrow so this turn takes the SAME path as a thrown SDK error
+    // instead of tripping the flow-violation re-prompt loop against an
+    // already-exhausted limit.
+    //
+    // …unless the user stopped this turn: an interrupted turn's result is
+    // flagged `is_error` with nothing but an `[ede_diagnostic]` line
+    // behind it, which `readResultError` then renders as bare trailing
+    // text or "Claude SDK turn failed (<subtype>)". That is the stop, not
+    // a failure — the turn closes as a completion.
+    if (state.resultErrorText && !active.interrupted) {
+      throw new Error(state.resultErrorText);
+    }
+  } catch (err) {
+    if (active.interrupted) {
+      // Same deal one layer down: after an interrupt the SDK re-labels the
+      // stream error with that error-result text. Quiet by design — no
+      // `logError`, no retry decision (which would classify the ede text,
+      // bump `errors.*`, and could fall back to another model for a turn
+      // the user just stopped), no `error` event. The shutdown drain takes
+      // this same path: its abort interrupts through here too.
+      log(
+        "agent",
+        `[${chatId}] turn ended by user interrupt: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      incrementCounter("sdk.interrupt_closed_stream");
+    } else if (!watchdog.forceClosed) {
+      const { retried, classified } = yield* applyRetryDecisionStream({
+        err,
+        chatId,
+        activeModel: inputs.activeModel,
+        retried: inputs.internal.errorRetried ?? false,
+        buildRetryStream: retryStreamBuilder(inputs.params, inputs.internal),
+        // No backendLabel — historical claude-sdk log shape was un-prefixed.
+      });
+      if (retried) return { kind: "retried" };
+      logError("agent", `[${chatId}] SDK error: ${classified.message}`);
+      // Returning (rather than yielding) here defers the `error` event
+      // until after `finally` releases the watchdog timer and the
+      // activeQueries entry.
+      return {
+        kind: "failed",
+        event: { type: "error", error: classifiedToAgentError(classified) },
+      };
+    }
+  } finally {
+    watchdog.clear();
+    if (activeQueries.get(chatId) === active) {
+      activeQueries.delete(chatId);
+    }
+  }
+  return { kind: "ok" };
+}
+
 // ── Main chat-turn generator ────────────────────────────────────────────────
 
 /**
@@ -498,7 +647,11 @@ function reportCacheVerdict(
  * recurse via `yield*` and produce the retry's event stream
  * transparently). On flow violation: `yield* runChatTurn(retry
  * params)` — the recursive call owns its `incrementTurns`, the
- * caller deliberately doesn't increment.
+ * caller deliberately doesn't increment. On a user interrupt
+ * (`interruptChatTurn`, which also backs the shutdown drain): the turn
+ * closes as a completion carrying the partial text and the real usage —
+ * never an `error` event, never a retry, whatever shape the SDK chose to
+ * end the stream in.
  */
 export async function* runChatTurn(
   params: ChatRunParams,
@@ -552,7 +705,8 @@ export async function* runChatTurn(
   yield { type: "run_started" };
 
   const qi = query({ prompt, options });
-  activeQueries.set(chatId, qi);
+  const active: ActiveTurn = { qi, interrupted: false };
+  activeQueries.set(chatId, active);
 
   // Cold-start delivery-tool race: on the FIRST turn of a freshly-opened
   // chat the hub's `${frontend}-tools` binding can still be `pending` when
@@ -567,59 +721,27 @@ export async function* runChatTurn(
   const live = createLiveUsage();
   const watchdog = createPostResultWatchdog(chatId, abortController, qi);
 
-  let propagateError: AgentEvent | null = null;
-  try {
-    yield* consumeSdkStream({
-      chatId,
-      qi,
-      state,
-      live,
-      watchdog,
-      model: options.model ?? activeModel,
-      pendingTools: new Map(),
-    });
-    // The SDK doesn't throw on API errors — it converts them into a
-    // synthetic assistant message and finishes the turn with an error-
-    // flagged result (usage limits, 429s, auth failures all land here).
-    // Rethrow so this turn takes the SAME path as a thrown SDK error
-    // instead of tripping the flow-violation re-prompt loop against an
-    // already-exhausted limit.
-    if (state.resultErrorText) {
-      throw new Error(state.resultErrorText);
-    }
-  } catch (err) {
-    if (!watchdog.forceClosed) {
-      const { retried, classified } = yield* applyRetryDecisionStream({
-        err,
-        chatId,
-        activeModel,
-        retried: _internal.errorRetried ?? false,
-        buildRetryStream: retryStreamBuilder(params, _internal),
-        // No backendLabel — historical claude-sdk log shape was un-prefixed.
-      });
-      // The recursive stream already yielded its own usage + completed.
-      if (retried) return;
-      logError("agent", `[${chatId}] SDK error: ${classified.message}`);
-      // Defer the yield until after `finally` releases the watchdog timer
-      // and the activeQueries entry.
-      propagateError = {
-        type: "error",
-        error: classifiedToAgentError(classified),
-      };
-    }
-  } finally {
-    watchdog.clear();
-    if (activeQueries.get(chatId) === qi) {
-      activeQueries.delete(chatId);
-    }
-  }
-
-  if (propagateError) {
+  const outcome = yield* runTurnStream({
+    chatId,
+    params,
+    internal: _internal,
+    active,
+    state,
+    live,
+    watchdog,
+    activeModel,
+    sdkModel: options.model ?? activeModel,
+  });
+  // The recursive retry stream already yielded its own usage + completed.
+  if (outcome.kind === "retried") return;
+  if (outcome.kind === "failed") {
     accountFailedClaudeTurn(chatId, state, live, activeModel, Date.now() - t0);
-    yield propagateError;
+    yield outcome.event;
     return;
   }
 
+  if (active.interrupted) closeInterruptedTurn(state, live);
+
   const durationMs = Date.now() - t0;
   accountTurn({
     chatId,

package/src/backend/claude-sdk/one-shot.ts

@@ -20,6 +20,7 @@ import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
 import { EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
 import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
 
@@ -65,6 +66,7 @@ export async function runOneShotAgent(
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
 
   // Reasoning effort is opt-in for background runs (config `heartbeatEffort`
@@ -126,7 +128,7 @@ export async function runOneShotAgent(
   // settlement figure the task table records.
   let usage: OneShotUsage | undefined;
   for await (const msg of qi) {
-    await formatAndAppendMessage(appendLog, msg);
+    await formatAndAppendMessage(appendLog, msg, onAssistantText);
     if (msg.type === "result") {
       const u = msg.usage;
       usage = {
@@ -183,6 +185,7 @@ function assembleMcpServers(contextLabel: string): Record<string, unknown> {
 async function formatAndAppendMessage(
   appendLog: (text: string) => Promise<void>,
   msg: SDKMessage,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   try {
     const ts = new Date().toISOString().slice(11, 19);
@@ -200,7 +203,11 @@ async function formatAndAppendMessage(
           });
 
         if (textBlocks.length > 0) {
-          await appendLog(`\n## [${ts}] Assistant\n${textBlocks.join("\n")}\n`);
+          const assistantText = textBlocks.join("\n");
+          // Report before the log write: an append failure (full disk, closed
+          // handle) must not also swallow the run's result for a hook caller.
+          emitAssistantText(onAssistantText, assistantText);
+          await appendLog(`\n## [${ts}] Assistant\n${assistantText}\n`);
         }
         if (toolUseBlocks.length > 0) {
           await appendLog(`\n${toolUseBlocks.join("\n\n")}\n`);
@@ -208,6 +215,14 @@ async function formatAndAppendMessage(
         break;
       }
       case "result": {
+        // Deliberately NOT reported through `onAssistantText`. The SDK's
+        // terminal `result` message restates the last assistant turn's text
+        // (`subtype: "success"`) or carries an error string (the
+        // `error_*` subtypes) — never anything the `assistant` case above
+        // has not already emitted. Reporting it too would hand every hook
+        // caller a duplicate final segment, and the truncated copy at that
+        // (2000 chars, below). The log keeps it because a run log wants the
+        // settlement line; a sub-agent result does not.
         const result =
           "result" in msg
             ? (msg as { result: string }).result

package/src/backend/claude-sdk/stream.ts

@@ -422,6 +422,15 @@ function readResultError(msg: SDKResultMessage, state: StreamState): void {
       .filter((e) => typeof e === "string" && !e.startsWith("[ede_diagnostic]"))
       .join("; ")
       .slice(0, 500);
+    // A known startup failure (SDK ≥ 0.3.274) names its cause — the CLI
+    // never ran a turn, so nothing else in the result says why. Lead with
+    // it; the diagnostics text is the same line stderr carried.
+    if (msg.startup_failure_reason) {
+      state.resultErrorText =
+        `Claude Code failed to start (${msg.startup_failure_reason})` +
+        (diagnostics ? `: ${diagnostics}` : "");
+      return;
+    }
     state.resultErrorText =
       state.lastTrailingText.trim() ||
       diagnostics ||

package/src/backend/codex/one-shot.ts

@@ -20,6 +20,7 @@
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
 import { appendBackendSuffix } from "../runtime/index.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
 import {
   CODEX_SYSTEM_PROMPT_SUFFIX,
@@ -79,6 +80,7 @@ export async function runOneShotAgent(
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
 
   const codex = ensureCodex(contextLabel);
@@ -143,7 +145,7 @@ export async function runOneShotAgent(
     let usage: OneShotUsage | undefined;
     for await (const event of events) {
       if (abortController.signal.aborted) break;
-      await appendCodexEvent(appendLog, event);
+      await appendCodexEvent(appendLog, event, onAssistantText);
       if (event.type === "turn.completed") {
         const u = (event as { usage?: Record<string, number> }).usage;
         if (u) {
@@ -217,6 +219,7 @@ export async function runOneShotAgent(
 async function appendCodexEvent(
   appendLog: (text: string) => Promise<void>,
   event: { type: string } & Record<string, unknown>,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const ts = new Date().toISOString().slice(11, 19);
 
@@ -260,7 +263,7 @@ async function appendCodexEvent(
     case "item.completed": {
       const item = (event as unknown as { item?: Record<string, unknown> })
         .item;
-      if (item) await appendCodexItem(appendLog, item, ts);
+      if (item) await appendCodexItem(appendLog, item, ts, onAssistantText);
       return;
     }
     default:
@@ -268,17 +271,28 @@ async function appendCodexEvent(
   }
 }
 
-/** Append one `ThreadItem` to the run log. */
+/**
+ * Append one `ThreadItem` to the run log, and report the model's final
+ * answers to the run's optional `onAssistantText` consumer.
+ *
+ * Only `agent_message` items are reported: `reasoning` items are the model's
+ * thinking and the rest are tool/command/diff payloads, none of which is the
+ * run's answer.
+ */
 async function appendCodexItem(
   appendLog: (text: string) => Promise<void>,
   item: Record<string, unknown>,
   ts: string,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const type = typeof item.type === "string" ? item.type : "unknown";
 
   if (type === "agent_message") {
     const text = typeof item.text === "string" ? item.text : "";
-    if (text) await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    if (text) {
+      emitAssistantText(onAssistantText, text);
+      await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    }
     return;
   }
 

package/src/backend/remote-server/one-shot.ts

@@ -42,6 +42,7 @@ import {
   type RemoteAssistantInfo,
 } from "./session-helpers.js";
 import { appendBackendSuffix, sleep } from "../runtime/index.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 import { buildPermissionRuleset } from "./sessions.js";
 
 // ── Client surface ──────────────────────────────────────────────────────────
@@ -108,6 +109,7 @@ export async function runRemoteOneShotAgent<
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
   const { label, errMsg } = bindings;
 
@@ -210,7 +212,7 @@ export async function runRemoteOneShotAgent<
       : [];
 
     for (const part of parts) {
-      await appendResponsePart(appendLog, part);
+      await appendResponsePart(appendLog, part, onAssistantText);
     }
 
     // The prompt response's assistant info carries the run's token usage —
@@ -250,17 +252,28 @@ export async function runRemoteOneShotAgent<
 
 // ── Run-log rendering ───────────────────────────────────────────────────────
 
-/** Render one response part into the Markdown run log. */
+/**
+ * Render one response part into the Markdown run log, and report the
+ * assistant's final text to the run's optional `onAssistantText` consumer.
+ *
+ * Only the `text` parts are reported: `reasoning` parts are the model's
+ * thinking and tool parts are call payloads, neither of which is the run's
+ * answer.
+ */
 async function appendResponsePart(
   appendLog: (text: string) => Promise<void>,
   part: Record<string, unknown>,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const ts = new Date().toISOString().slice(11, 19);
   const type = typeof part.type === "string" ? part.type : "unknown";
 
   if (type === "text") {
     const text = typeof part.text === "string" ? part.text : "";
-    if (text) await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    if (text) {
+      emitAssistantText(onAssistantText, text);
+      await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    }
     return;
   }
 

package/src/backend/runtime/one-shot-hooks.ts

@@ -0,0 +1,45 @@
+/**
+ * One-shot run hooks — the shared, throw-proof call site for
+ * `OneShotAgentParams.onAssistantText`.
+ *
+ * Every backend's isolated runner (`BackgroundRunner.runOneShotAgent`) already
+ * renders the model's assistant text into the run log as markdown. The hook is
+ * the same text as data, so a caller (the sub-agent runner) can take a run's
+ * result without parsing the log back apart. It lives here rather than in each
+ * backend so all four report it identically: same "final answer only" meaning,
+ * same empty-string skip, same swallow-and-log on a throwing callback.
+ *
+ * Contract:
+ *   - Final assistant text only. Reasoning/thinking blocks and tool-call
+ *     payloads are log-only; they never reach the hook.
+ *   - Synchronous. The runner does not await the consumer, so a hook that
+ *     wants to do async work owns its own queueing.
+ *   - Never throws into the run. A consumer bug must not abort a heartbeat.
+ */
+
+import type { OneShotAgentParams } from "../../core/types.js";
+import { logWarn } from "../../util/log.js";
+
+/**
+ * Report one assistant text segment to the run's optional consumer.
+ *
+ * No-ops when there is no hook (the heartbeat/dream/cron path) or when the
+ * text is empty — the backends guard their log appends the same way, so the
+ * hook sees exactly the segments the log does.
+ */
+export function emitAssistantText(
+  onAssistantText: OneShotAgentParams["onAssistantText"],
+  text: string,
+): void {
+  if (!onAssistantText || !text) return;
+  try {
+    onAssistantText(text);
+  } catch (err) {
+    logWarn(
+      "agent",
+      `one-shot onAssistantText hook threw (ignored): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

package/src/core/agent-runtime/agent-host.ts

@@ -31,9 +31,10 @@
  * They are deliberately not the same types. Two client arguments do not
  * survive a process boundary and the wire shapes say so:
  *
- *   - `OneShotAgentParams` carries an `AbortController` and an
- *     `appendLog` callback. `HostOneShotParams` is the serialisable
- *     subset; Phase 2 maps `appendLog` onto `log` notices and the
+ *   - `OneShotAgentParams` carries an `AbortController` and two
+ *     callbacks (`appendLog`, `onAssistantText`). `HostOneShotParams`
+ *     is the serialisable subset; Phase 2 maps `appendLog` onto `log`
+ *     notices, `onAssistantText` onto a notice of its own, and the
  *     abort onto an `interrupt`-shaped request.
  *   - `hello.config` is the `claude-sdk` slice of `TalonConfig` as
  *     JSON. The in-process client takes the real `TalonConfig` object.
@@ -59,9 +60,9 @@ export const AGENT_HOST_PROTOCOL_VERSION = 1;
 // ── Shared payload shapes ───────────────────────────────────────────────────
 
 /**
- * The serialisable half of `OneShotAgentParams`. `abortController` and
- * `appendLog` are host-local concerns (see the file header); everything
- * else is exactly what a background run needs.
+ * The serialisable half of `OneShotAgentParams`. `abortController`,
+ * `appendLog` and `onAssistantText` are host-local concerns (see the file
+ * header); everything else is exactly what a background run needs.
  *
  * Unexported on purpose — it is reachable as
  * `Extract<HostRequest, { type: "one_shot" }>["params"]`, and a second

package/src/core/agent-runtime/capabilities.ts

@@ -103,6 +103,9 @@ export interface ChatBackend {
  *     trigger log-file producers keep their direct write path.
  *     Resolves with the run's token usage when the SDK reports it
  *     (the task table records it at settlement); void otherwise.
+ *     Implementations must also honour the optional `onAssistantText`
+ *     hook — the run's final answers as data, for callers (the
+ *     sub-agent runner) that need a result rather than a markdown log.
  *   - `evictOrphanSubprocesses(label)` — backends that spawn
  *     per-run subprocesses (Claude SDK) implement this so a hung
  *     run can be force-cleaned after the abort grace window.

package/src/core/mcp-hub/children.ts

@@ -100,6 +100,16 @@ export function formatChildExit(
   return lines.length > 0 ? `${head}; stderr: ${lines.join(" | ")}` : head;
 }
 
+/**
+ * Human-readable form of a child key for log lines. Keys join server name
+ * and chat id with a NUL byte (see `childKey` in index.ts) — unambiguous
+ * as a Map key, but it renders as `\u0000` in the JSON log.
+ */
+function describeKey(key: string): string {
+  const nul = key.indexOf("\u0000");
+  return nul === -1 ? key : `${key.slice(0, nul)} chat=${key.slice(nul + 1)}`;
+}
+
 /**
  * Bookkeeping for a child process that has gone away, asked or not.
  * Wired as the transport's `onclose` BEFORE `client.connect` so the SDK
@@ -125,7 +135,7 @@ function onChildClosed(key: string, transport: HubChildTransport): void {
     : "died before registration";
   logWarn(
     "gateway",
-    `hub child ${key} ${phase} (pid ${transport.pid ?? "?"}): ${formatChildExit(record)}`,
+    `hub child ${describeKey(key)} ${phase} (pid ${transport.pid ?? "?"}): ${formatChildExit(record)}`,
   );
 }
 
@@ -199,7 +209,10 @@ async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
           try {
             await client.close();
           } catch (err) {
-            logWarn("gateway", `hub child ${key} close failed: ${String(err)}`);
+            logWarn(
+              "gateway",
+              `hub child ${describeKey(key)} close failed: ${String(err)}`,
+            );
           }
         })());
     })(),
@@ -226,7 +239,10 @@ async function spawnChild(key: string, spec: ChildSpec): Promise<ChildHandle> {
   };
 
   children.set(key, entry);
-  log("gateway", `hub child started: ${key} (pid ${transport.pid ?? "?"})`);
+  log(
+    "gateway",
+    `hub child started: ${describeKey(key)} (pid ${transport.pid ?? "?"})`,
+  );
   return entry.handle;
 }
 
@@ -327,9 +343,9 @@ function reapIdle(): void {
     if (entry.lastActivity >= cutoff) continue;
     children.delete(key);
     entry.close().catch((err) => {
-      logError("gateway", `hub reap of ${key} failed`, err);
+      logError("gateway", `hub reap of ${describeKey(key)} failed`, err);
     });
-    log("gateway", `hub child reaped (idle): ${key}`);
+    log("gateway", `hub child reaped (idle): ${describeKey(key)}`);
   }
 }
 

package/src/core/types.ts

@@ -161,6 +161,17 @@ export type OneShotAgentParams = {
   abortController: AbortController;
   /** Append a string to the run log (markdown). */
   appendLog: (text: string) => Promise<void>;
+  /**
+   * Called with each assistant text segment as the run produces it (final
+   * answers, not reasoning/thinking, not tool-call payloads). Optional so
+   * heartbeat/dream/cron callers are untouched; a sub-agent runner uses it to
+   * capture the run's result without parsing the markdown log.
+   *
+   * Synchronous and best-effort: every backend invokes it through
+   * `emitAssistantText` (backend/runtime/one-shot-hooks.ts), which swallows
+   * and logs a throwing callback so a consumer bug can never fail the run.
+   */
+  onAssistantText?: (text: string) => void;
 };
 
 /** How much cache telemetry a backend can surface in /status. */