@genesislcap/ai-assistant 15.11.0 → 15.12.0

package/src/components/chat-driver/chat-driver.trace-capture.test.ts

@@ -0,0 +1,251 @@
+import type {
+  AIProvider,
+  AIProviderRegistry,
+  ChatMessage,
+  ChatRequestOptions,
+} from '@genesislcap/foundation-ai';
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import type { AgentConfig } from '../../config/config';
+import { sumUsage } from '../../utils/sum-usage';
+import { usageRows } from '../../utils/usage-rows';
+// Side-effect import — MUST come before `./chat-driver` so the driver subclasses
+// jsdom's EventTarget rather than Node's native one. Mirrors chat-driver.test.ts.
+import './align-event-globals';
+import { ChatDriver } from './chat-driver';
+
+// ---------------------------------------------------------------------------
+// Sub-agent trace capture when ONE tool call invokes SEVERAL sub-agents.
+//
+// The capture slot used to be a single `{ trace?: ChatMessage[] }` per tool call,
+// assigned by each `requestSubAgent`. That covers N tool calls × 1 sub-agent — the
+// case its docblock named — but not 1 tool call × N sub-agents, which is what a
+// code-driven scheduler or a retry produces. All but the last trace was dropped, so
+// those children ran, were billed, and then had no record in history.
+//
+// The failure was invisible to every existing check: `sumUsage` and `usageRows` both
+// recurse into `subAgentTrace`, so they summed a truncated input and still reconciled
+// with each other perfectly. Measured at 1 of 7 traces kept on a seven-way fan-out,
+// ~2.3x under the true cost.
+//
+// These tests assert the traces SURVIVE, which is upstream of any cost assertion.
+// ---------------------------------------------------------------------------
+
+/** Answers by rule: concurrent children under one turn make a FIFO queue nondeterministic. */
+const ruleProvider = (): AIProvider => {
+  let parentTurns = 0;
+  return {
+    chat: async (
+      _history: ChatMessage[],
+      _userMessage: string,
+      options?: ChatRequestOptions,
+    ): Promise<ChatMessage> => {
+      const tools = (options?.tools ?? []).map((t) => t.name);
+      // Child turn: finishes via its completion tool, and reports usage so the
+      // reconciliation assertions have something to add up.
+      if (tools.includes('work')) {
+        return {
+          role: 'assistant',
+          content: '',
+          model: 'claude-sonnet-5',
+          cost: 0.01,
+          inputTokens: 100,
+          outputTokens: 20,
+          toolCalls: [{ id: 'w1', name: 'work', args: {} }],
+        };
+      }
+      if (tools.includes('delegate') && parentTurns === 0) {
+        parentTurns += 1;
+        return {
+          role: 'assistant',
+          content: '',
+          model: 'claude-sonnet-5',
+          cost: 0.02,
+          inputTokens: 200,
+          outputTokens: 30,
+          toolCalls: [{ id: 'd0', name: 'delegate', args: {} }],
+        };
+      }
+      return { role: 'assistant', content: 'done', model: 'claude-sonnet-5' };
+    },
+  };
+};
+
+const makeRegistry = (provider: AIProvider): AIProviderRegistry => ({
+  get: () => provider,
+  default: () => provider,
+  defaultName: () => 'test',
+  names: () => ['test'],
+  getStatus: async () => null,
+  listStatuses: async () => [],
+});
+
+const agent = (overrides: Partial<AgentConfig> & { name: string }): AgentConfig =>
+  ({ description: 'test agent', ...overrides }) as AgentConfig;
+
+/** A child that reports one unit of usage and completes. */
+const worker = (name: string): AgentConfig =>
+  agent({
+    name,
+    toolDefinitions: [
+      { name: 'work', description: 'work', parameters: { type: 'object', properties: {} } },
+    ],
+    toolHandlers: {
+      work: async (_args, ctx) => {
+        ctx.completeSubAgent?.({ ok: true });
+        return 'worked';
+      },
+    },
+  });
+
+/**
+ * A parent whose single `delegate` tool call invokes `names` in turn — the shape a
+ * code-driven scheduler produces, and the one the old single slot truncated.
+ */
+const boss = (children: AgentConfig[], invoke: string[]): AgentConfig =>
+  agent({
+    name: 'boss',
+    subAgents: children,
+    toolDefinitions: [
+      { name: 'delegate', description: 'delegate', parameters: { type: 'object', properties: {} } },
+    ],
+    toolHandlers: {
+      delegate: async (_args, ctx) => {
+        await Promise.all(invoke.map((n) => ctx.requestSubAgent!(n, { task: 'go' })));
+        return 'delegated';
+      },
+    },
+  });
+
+const run = async (config: AgentConfig): Promise<readonly ChatMessage[]> => {
+  const driver = new ChatDriver(makeRegistry(ruleProvider()), {
+    maxToolIterations: 20,
+    maxFoldOperations: 5,
+    sessionKey: '',
+  });
+  driver.applyAgent(config);
+  await driver.sendMessage('go');
+  return driver.getHistory();
+};
+
+const tracesIn = (history: readonly ChatMessage[]): readonly ChatMessage[][] =>
+  history.flatMap((m) =>
+    (m.toolCalls ?? []).flatMap((tc) => (tc.subAgentTrace ? [tc.subAgentTrace] : [])),
+  );
+
+const suite = createLogicSuite('ChatDriver sub-agent trace capture');
+
+// ---------------------------------------------------------------------------
+
+suite('keeps every trace when one tool call invokes three sub-agents', async () => {
+  const names = ['gen_a', 'gen_b', 'gen_c'];
+  const history = await run(boss(names.map(worker), names));
+
+  const traces = tracesIn(history);
+  assert.is(traces.length, 1, 'one tool call, so one concatenated trace');
+
+  // Each child contributes at least its own assistant turn. Before the fix this was
+  // one child's worth regardless of how many ran.
+  const seen = new Set(traces[0].map((m) => m.agentName).filter(Boolean));
+  assert.equal(
+    [...seen].sort(),
+    names,
+    `every invoked child must appear — got ${JSON.stringify([...seen])}`,
+  );
+});
+
+suite('prices every child — usageRows emits a row per child and reconciles', async () => {
+  // The reconciliation test extended to a fan-out. The single-child version passed
+  // before the fix AND after it, which is exactly why it did not catch this.
+  const names = ['gen_a', 'gen_b', 'gen_c'];
+  const history = await run(boss(names.map(worker), names));
+
+  const rows = usageRows(history);
+  const childRows = rows.filter((r) => r.subAgentDepth === 1);
+  assert.is(childRows.length, names.length, 'one row per child that ran');
+
+  const rowTotal = rows.reduce((n, r) => n + (r.costUsd ?? 0) + (r.externalCostUsd ?? 0), 0);
+  assert.ok(
+    Math.abs(rowTotal - sumUsage(history).costUsd) < 1e-12,
+    `rows ${rowTotal} vs sumUsage ${sumUsage(history).costUsd}`,
+  );
+  // Parent turn ($0.02) + three children ($0.01 each). Asserted as a number so a
+  // regression that silently drops a child fails here rather than only in the
+  // reconciliation above, which would still agree with a truncated input.
+  assert.ok(Math.abs(rowTotal - 0.05) < 1e-12, `expected 0.05, got ${rowTotal}`);
+});
+
+suite('keeps both traces when the same sub-agent is invoked twice (a retry)', async () => {
+  // The retry shape: one handler, one child name, two invocations. Under the old slot
+  // the first attempt's trace was overwritten by the second.
+  const history = await run(boss([worker('gen_a')], ['gen_a', 'gen_a']));
+
+  const traces = tracesIn(history);
+  assert.is(traces.length, 1);
+  const childTurns = traces[0].filter((m) => m.agentName === 'gen_a' && m.cost != null);
+  assert.is(childTurns.length, 2, 'both attempts survive, not just the last');
+
+  const rows = usageRows(history).filter((r) => r.subAgentDepth === 1);
+  assert.is(rows.length, 2, 'and both are priced');
+});
+
+suite('keeps child traces when the parent handler throws after they ran', async () => {
+  // Children that completed were billed by the provider. If the error path drops
+  // their traces, the run under-reports exactly as the single-slot bug did — and
+  // just as silently, since `sumUsage` and `usageRows` would still agree with each
+  // other over the truncated input. PR review.
+  const names = ['gen_a', 'gen_b'];
+  const parent = agent({
+    name: 'boss',
+    subAgents: names.map(worker),
+    toolDefinitions: [
+      { name: 'delegate', description: 'delegate', parameters: { type: 'object', properties: {} } },
+    ],
+    toolHandlers: {
+      delegate: async (_args, ctx) => {
+        await Promise.all(names.map((n) => ctx.requestSubAgent!(n, { task: 'go' })));
+        throw new Error('post-processing the children failed');
+      },
+    },
+  });
+
+  const history = await run(parent);
+  const traces = tracesIn(history);
+  assert.is(traces.length, 1, 'the failed tool call still carries its trace');
+  const seen = [...new Set(traces[0].map((m) => m.agentName).filter(Boolean))].sort();
+  assert.equal(seen, names, 'both children survive the throw');
+
+  const childRows = usageRows(history).filter((r) => r.subAgentDepth === 1);
+  assert.is(childRows.length, 2, 'and both are still priced');
+});
+
+suite('leaves subAgentTrace undefined when no sub-agent ran', async () => {
+  // Presence is the signal readers key off (`usage-rows.ts`, the UI's `when(...)`),
+  // so an empty array would be a different and wrong claim.
+  const history = await run(
+    agent({
+      name: 'boss',
+      subAgents: [worker('gen_a')],
+      toolDefinitions: [
+        {
+          name: 'delegate',
+          description: 'delegate',
+          parameters: { type: 'object', properties: {} },
+        },
+      ],
+      toolHandlers: { delegate: async () => 'did it myself' },
+    }),
+  );
+
+  for (const m of history) {
+    for (const tc of m.toolCalls ?? []) {
+      assert.is(tc.subAgentTrace, undefined, 'not an empty array');
+    }
+  }
+  assert.equal(
+    usageRows(history).filter((r) => r.subAgentDepth === 1),
+    [],
+    'no child rows',
+  );
+});
+
+suite.run();

package/src/components/chat-driver/chat-driver.ts

@@ -8,6 +8,7 @@ import type {
   ChatFallback,
   ChatMessage,
   ChatRequestOptions,
+  ChatThinkingPolicy,
   ChatToolCall,
   ChatToolChoice,
   ChatToolDefinition,
@@ -38,6 +39,7 @@ import type {
   SystemPromptInput,
   TailContextInput,
   TemperatureInput,
+  ThinkingPolicyInput,
   ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
@@ -589,6 +591,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
    */
   private activeCachePolicyInput?: CachePolicyInput;
+  /**
+   * Active agent's extended-thinking selector (static value or per-turn resolver). `undefined` —
+   * unset, or returned by the resolver — leaves the model on its own default posture, which is
+   * neither uniformly on nor off, so an agent that never sets this is unaffected by the option.
+   */
+  private activeThinkingPolicyInput?: ThinkingPolicyInput;
   /**
    * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
    * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
@@ -1029,6 +1037,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.activeTemperatureInput = config.temperature;
     this.activeToolChoiceInput = config.toolChoice;
     this.activeCachePolicyInput = config.cachePolicy;
+    this.activeThinkingPolicyInput = config.thinkingPolicy;
     this.activeTailContextInput = config.tailContext;
     this.activeResponseSchemaInput = config.responseSchema;
     this.activeFallbacks = config.fallbacks;
@@ -1910,11 +1919,25 @@ export class ChatDriver extends EventTarget implements AiDriver {
    *   `condenseWhen` can register against the right call (it stamps the clocks
    *   straight off the driver). Absent for dispatch paths with no addressable tool
    *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
-   * @param traceCapture - Optional per-invocation slot. When provided, the trace
-   *   from any sub-agent call is written here rather than to shared instance state,
-   *   so parallel tool calls each capture their own trace independently.
-   */
-  private buildHandlerContext(activeToolCallId?: string, traceCapture?: { trace?: ChatMessage[] }) {
+   * @param traceCapture - Optional per-tool-call accumulator. When provided, every
+   *   sub-agent call's trace is **appended** here rather than written to shared
+   *   instance state, so parallel tool calls each capture their own traces
+   *   independently.
+   *
+   *   Deliberately a list of traces, not one slot. A single handler may call
+   *   `requestSubAgent` more than once — a code-driven scheduler dispatching a
+   *   dependency graph, a retry of a timed-out child, any fan-out helper — and a
+   *   single slot kept only the last, so every other child ran, was billed by the
+   *   provider, and then vanished from history. The loss was silent in the worst
+   *   way: `sumUsage` and `usageRows` both recurse into the trace, so they summed a
+   *   truncated input and still agreed with each other. Measured at 1 of 7 traces
+   *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
+   *   error growing as the fan-out widens.
+   */
+  private buildHandlerContext(
+    activeToolCallId?: string,
+    traceCapture?: { traces: ChatMessage[][] },
+  ) {
     return {
       requestInteraction: <T>(
         componentName: string,
@@ -1930,7 +1953,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
           | { ok: false; result?: never; reason: SubAgentFailureReason }
         > =>
           this.invokeSubAgent<T>(name, options).then(({ outcome, trace }) => {
-            if (traceCapture) traceCapture.trace = trace;
+            // Append, never assign: see `traceCapture` on `buildHandlerContext`. Order
+            // is completion order, which is fine — every message carries its own
+            // timestamp and the timeline sorts on that.
+            if (traceCapture && trace) traceCapture.traces.push(trace);
             return outcome;
           }),
       }),
@@ -2494,6 +2520,18 @@ export class ChatDriver extends EventTarget implements AiDriver {
     // `iterations` because fold operations decrement iterations, which would incorrectly
     // re-trigger the slice on subsequent calls after a fold open/close.
     let firstLlmCall = !!currentInput;
+    // Thinking posture for this WHOLE turn, resolved on the first model call and then held.
+    //
+    // Unlike temperature or toolChoice, this one cannot vary per iteration: a tool-use loop is
+    // a single assistant turn, and Anthropic requires one thinking mode for its duration.
+    // Toggling mid-loop does not error — the API silently disables thinking for that request
+    // and strips blocks that would leave the turn structure invalid, so an `'auto' -> 'off'`
+    // switch loses the reasoning continuity the opening call established while an
+    // `'off' -> 'auto'` switch simply does not deliver the reasoning asked for. It also
+    // invalidates the prompt cache, which costs more than the reasoning it was meant to save.
+    // Resolved per USER turn instead, which is where the docs say to choose it.
+    let pinnedThinkingPolicy: ChatThinkingPolicy | undefined;
+    let thinkingPolicyPinned = false;
 
     while (iterations < this.maxToolIterations) {
       iterations += 1;
@@ -2680,6 +2718,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
         resolvedCachePolicy,
         resolvedTailContext,
         resolvedResponseSchema,
+        firstResolvedThinkingPolicy,
       ] =
         // oxlint-disable-next-line no-await-in-loop
         await Promise.all([
@@ -2688,7 +2727,19 @@ export class ChatDriver extends EventTarget implements AiDriver {
           this.resolveTurnInput<CachePolicy>(this.activeCachePolicyInput, promptCtx),
           this.resolveTurnInput<string>(this.activeTailContextInput, promptCtx),
           this.resolveTurnInput<object | undefined>(this.activeResponseSchemaInput, promptCtx),
+          // Only consulted on the first iteration (see `pinnedThinkingPolicy`); resolved
+          // alongside the others so a resolver still sees the same turn context.
+          thinkingPolicyPinned
+            ? Promise.resolve(undefined)
+            : this.resolveTurnInput<ChatThinkingPolicy | undefined>(
+                this.activeThinkingPolicyInput,
+                promptCtx,
+              ),
         ]);
+      if (!thinkingPolicyPinned) {
+        pinnedThinkingPolicy = firstResolvedThinkingPolicy;
+        thinkingPolicyPinned = true;
+      }
       // The system prompt is always just the agent's resolved prompt — byte-stable, so it can be
       // cached. The framework's volatile additions (fold suffix, retry nudge) and the agent's tail
       // context all go to the framed tail: one uniform channel, no cache-scope branch. On a normal
@@ -2736,6 +2787,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // Prompt-cache policy for this turn (Anthropic places breakpoints per scope; Gemini
         // caches implicitly regardless). Undefined → no caching requested.
         cachePolicy: resolvedCachePolicy,
+        // Extended-thinking posture, pinned for the whole tool loop (one assistant turn) rather
+        // than re-resolved per iteration — see `pinnedThinkingPolicy`. Undefined — unset, or the
+        // resolver's answer for this turn — is NOT "off": it leaves the model on its own default,
+        // so agents that never set this are priced exactly as before. Transports clamp models
+        // that can't honour it.
+        thinkingPolicy: pinnedThinkingPolicy,
         // Framed volatile context injected at the message tail (never stored). Undefined → none.
         tailContext,
         // Structured-output schema for this turn (agent/state-resolved). When set, the transport
@@ -2924,7 +2981,15 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // leaves the key off entirely rather than carrying it as `undefined`.
       // JSON.stringify already drops undefined from the exported log, so this is
       // chiefly about keeping the in-memory message shape honest.
-      if (this.lastResolvedModel !== undefined) response.model = this.lastResolvedModel;
+      // Fill, never overwrite — but still only when there is something to fill with.
+      // A transport that already stamped a model knows something the driver does not:
+      // `lastResolvedModel` is the model we ASKED for, so overwriting would relabel a
+      // fallback-served turn as the requested model and misattribute its spend.
+      // Written as a guard rather than `??=` because `??=` ASSIGNS undefined, which
+      // would create the key and break the omit-when-unresolved contract above.
+      if (response.model === undefined && this.lastResolvedModel !== undefined) {
+        response.model = this.lastResolvedModel;
+      }
       if (this.lastResolvedProvider !== undefined) response.provider = this.lastResolvedProvider;
       if (this.lastResolvedProviderName !== undefined) {
         response.providerName = this.lastResolvedProviderName;
@@ -3194,15 +3259,27 @@ export class ChatDriver extends EventTarget implements AiDriver {
               return;
             }
 
-            // Real tool execution
+            // Real tool execution.
+            //
+            // The accumulator is declared OUTSIDE the try so the catch can attach it
+            // too: a handler that ran sub-agents and then threw (post-processing their
+            // results failed, say) has already spent real money on children that
+            // completed. Losing their traces on the error path would under-report the
+            // run exactly as the single-slot bug did — and just as silently, since
+            // `sumUsage` and `usageRows` would still agree with each other.
+            const traceCapture: { traces: ChatMessage[][] } = { traces: [] };
+            const capturedTrace = (): ChatMessage[] | undefined =>
+              traceCapture.traces.length ? traceCapture.traces.flat() : undefined;
             try {
-              const traceCapture: { trace?: ChatMessage[] } = {};
               const result = await handler(tc.args, this.buildHandlerContext(tc.id, traceCapture));
               const content = typeof result === 'string' ? result : JSON.stringify(result);
               executedById.set(tc.id, {
                 toolCallId: tc.id,
                 content,
-                subAgentTrace: traceCapture.trace,
+                // Concatenated when a handler invoked several children, so none is lost.
+                // Stays `undefined` when nothing was captured — readers key off presence,
+                // and an empty array is a different claim from "no sub-agent ran".
+                subAgentTrace: capturedTrace(),
               });
               anyRealToolExecuted = true;
             } catch (e) {
@@ -3217,6 +3294,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 // Structured recovery hint so the model retries or routes around a tool
                 // failure instead of apologising and giving up.
                 content: `Tool error: ${(e as Error).message}\nRECOVERY: this tool failed once — you may retry it, or take a different valid action to make progress. Do NOT abandon the task, ask the user to rephrase, or claim you cannot make changes. If a planning tool failed, retry it or proceed with the information you already have.`,
+                // Children that completed before the throw were still billed — keep
+                // their traces so the run's cost stays whole.
+                subAgentTrace: capturedTrace(),
               });
               anyRealToolExecuted = true; // treat errors as real work for fold op counting
             }

package/src/config/config.ts

@@ -3,12 +3,19 @@ import type {
   ChatFallback,
   ChatInputDuringExecutionMode,
   ChatMessage,
+  ChatThinkingPolicy,
   ChatToolChoice,
   ChatToolDefinition,
   ChatToolHandlers,
 } from '@genesislcap/foundation-ai';
 
-export type { CachePolicy, ChatFallback, ChatInputDuringExecutionMode, ChatToolChoice };
+export type {
+  CachePolicy,
+  ChatFallback,
+  ChatInputDuringExecutionMode,
+  ChatThinkingPolicy,
+  ChatToolChoice,
+};
 
 /**
  * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
@@ -164,6 +171,36 @@ export type CachePolicyInput =
   | CachePolicy
   | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
 
+/**
+ * Extended-thinking posture for an agent — whether the model reasons before answering. Either a
+ * static `ChatThinkingPolicy` or a function resolved **once per user turn**, at the start of the
+ * tool loop. Pick the function form to vary it by current state: reason in the state that makes a
+ * real decision, and drop it in states that only step a known sequence, where reasoning bills at
+ * the full output rate to re-derive what the state machine already knows.
+ *
+ * Note the resolution point, which differs from every other per-turn input here: a tool-use loop
+ * is a single assistant turn and its thinking mode must hold for the whole of it, so this resolver
+ * is consulted on the first model call of a turn and its answer reused for the rest. A resolver
+ * that returns a different value part-way through a loop will not see it applied until the next
+ * user turn.
+ *
+ * **Omit — or return `undefined` from the function — to keep the model's own default**, which is
+ * a distinct third state rather than a synonym for either value: Sonnet 5 and Fable 5 think by
+ * default, the rest do not. So an agent that leaves this unset, or a resolver that answers
+ * `undefined` on some turns, behaves and prices exactly as it did before this option existed.
+ *
+ * A request, not a guarantee — transports clamp what a model cannot honour (Fable 5 and Gemini
+ * 2.5 Pro always think) and warn once instead of failing the turn. Resolved and applied the same
+ * way as {@link TemperatureInput}. See `ChatThinkingPolicy`.
+ *
+ * @beta
+ */
+export type ThinkingPolicyInput =
+  | ChatThinkingPolicy
+  | ((
+      ctx: SystemPromptContext,
+    ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
+
 /**
  * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
  * state) injected at the tail of every model-call so the model sees it without invalidating the
@@ -346,6 +383,18 @@ interface BaseAgentConfig {
    * @beta
    */
   cachePolicy?: CachePolicyInput;
+  /**
+   * Extended-thinking posture for this agent — whether the model reasons before answering. Either
+   * a static value or a function resolved **once per user turn** and held for that turn's whole
+   * tool loop (vary by state: `'auto'` where the turn is a genuine decision, `'off'` where it only
+   * steps a known sequence and reasoning is billed at the full output rate for no benefit). Omit —
+   * or return `undefined` — to keep the model's own default, which is neither `'auto'` nor `'off'`
+   * uniformly. Provider-neutral; transports clamp models that cannot honour it.
+   * See {@link ThinkingPolicyInput}.
+   *
+   * @beta
+   */
+  thinkingPolicy?: ThinkingPolicyInput;
   /**
    * Volatile per-turn context injected at the tail of every model-call (after the history and any
    * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put

package/src/config/define-stateful-agent.ts

@@ -1,6 +1,7 @@
 import type {
   CachePolicy,
   ChatMessage,
+  ChatThinkingPolicy,
   ChatToolChoice,
   ChatToolDefinition,
   ChatToolHandlers,
@@ -18,6 +19,7 @@ import type {
   SystemPromptInput,
   TailContextInput,
   TemperatureInput,
+  ThinkingPolicyInput,
   ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
@@ -185,6 +187,25 @@ export interface StatefulAgentInit<S> {
     | CachePolicy
     | ((ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>);
 
+  /**
+   * Extended-thinking posture. Either a static `ChatThinkingPolicy` or a function resolved with
+   * the current `state` **once per user turn** — the function form is the point of this option on
+   * a machine agent: `'auto'` in the state that makes a real decision, `'off'` in the states that
+   * only step a known sequence, where reasoning is billed at the full output rate to re-derive
+   * what the machine already knows. Omit, or return `undefined` from the function, to keep the
+   * model's own default for that turn.
+   *
+   * Resolved once per turn rather than per tool-loop iteration (unlike `temperature` and
+   * `toolChoice`): a tool-use loop is one assistant turn and its thinking mode must hold for the
+   * whole of it. A state transition part-way through a loop therefore takes effect on the next
+   * user turn, not immediately.
+   */
+  thinkingPolicy?:
+    | ChatThinkingPolicy
+    | ((
+        ctx: StatefulAgentContext<S>,
+      ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>);
+
   /**
    * Volatile per-turn tail context (current file/spec, diagnostics, live state). Either a static
    * string or a function resolved each tool-loop iteration with the current `state`. Provide raw
@@ -484,6 +505,21 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
         }
       : opts.cachePolicy;
 
+  // Unlike the resolvers above, a pre-init call returns `undefined` rather than throwing: that is
+  // this option's "model default" state, so degrading to it costs a turn its thinking preference
+  // instead of breaking the turn outright.
+  const wrappedThinkingPolicy: ThinkingPolicyInput | undefined =
+    typeof opts.thinkingPolicy === 'function'
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) return undefined;
+          return (
+            opts.thinkingPolicy as (
+              ctx: StatefulAgentContext<S>,
+            ) => ChatThinkingPolicy | undefined | Promise<ChatThinkingPolicy | undefined>
+          )({ ...ctx, state });
+        }
+      : opts.thinkingPolicy;
+
   const wrappedTailContext: TailContextInput | undefined =
     typeof opts.tailContext === 'function'
       ? async (ctx: SystemPromptContext) => {
@@ -541,6 +577,7 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
     temperature: wrappedTemperature,
     toolChoice: wrappedToolChoice,
     cachePolicy: wrappedCachePolicy,
+    thinkingPolicy: wrappedThinkingPolicy,
     tailContext: wrappedTailContext,
     onUnresolvedTool: wrappedOnUnresolvedTool,
     resumable: wrappedResumable,

package/src/main/main.template.ts

@@ -178,11 +178,29 @@ const subAgentMessageRowTemplate = html<ChatMessage>`
   )}
 `;
 
+/**
+ * Label for a trace block: the distinct agents that appear in it.
+ *
+ * One tool call can invoke several sub-agents — a scheduler dispatching a dependency
+ * graph, or a retry — and their conversations arrive concatenated in one trace. Naming
+ * only `[0]` would then label a block "gen_A trace" while `gen_B`'s turns sit inside
+ * it. Two agents read as "gen_A, gen_B"; beyond that it degrades to a count rather
+ * than growing an unbounded summary line.
+ */
+const subAgentTraceLabel = (trace: readonly ChatMessage[]): string => {
+  const names = [...new Set(trace.map((m) => m.agentName).filter(Boolean))] as string[];
+  if (names.length === 0) return 'Sub-agent trace';
+  if (names.length <= 2) return `${names.join(', ')} trace`;
+  // Owns the whole string rather than returning a fragment the template suffixes, so the noun
+  // agrees with the count — a shared ` trace` suffix rendered "3 sub-agents trace".
+  return `${names.length} sub-agent traces`;
+};
+
 /** Collapsed <details> trace shown inside a tool-call card once the sub-agent finishes. */
 const subAgentTraceTemplate = html<ChatToolCall>`
   <details class="sub-agent-trace">
     <summary class="sub-agent-trace-summary">
-      ${(tc) => tc.subAgentTrace![0]?.agentName ?? 'Sub-agent'} trace
+      ${(tc) => subAgentTraceLabel(tc.subAgentTrace!)}
     </summary>
     ${repeat(
       (tc) => tc.subAgentTrace!.filter((m) => m.role !== 'user'),

package/src/utils/strip-agent-handlers.ts

@@ -8,7 +8,7 @@ import type { AgentConfig } from '../config/config';
  *    `onDeactivate`, `getDebugSnapshot`, `onUnresolvedTool`) and the function
  *    form of the per-turn resolvers (`systemPrompt`, `toolDefinitions`,
  *    `displayName`, `provider`, `temperature`, `toolChoice`, `cachePolicy`,
- *    `toolHandlers`).
+ *    `thinkingPolicy`, `toolHandlers`).
  * 2. **Object "handler bags" whose *values* are functions** — `toolHandlers` in
  *    its object form is `{ name: handler }`, so `typeof` is `'object'`, not
  *    `'function'`. A by-value check on the field alone misses it, leaking a live