@graphorin/agent 0.6.0 → 0.7.0

package/src/runtime/step-catalogue.ts

@@ -0,0 +1,338 @@
+/**
+ * Per-step tool-catalogue support for the agent runtime: projection of
+ * a tool's declared schemas onto the provider wire contract
+ * (`ToolDefinition`), including worked examples, plus the per-step
+ * registry / executor / catalogue / preferred-model resolution.
+ * Extracted verbatim from `factory.ts` (issue #23).
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AISpan,
+  Message,
+  Provider,
+  ProviderRequest,
+  ReasoningRetention,
+  RunState,
+  Tool,
+  ToolChoice,
+  ToolDefinition,
+  ToolDefinitionExample,
+} from '@graphorin/core';
+import type { ToolExecutor } from '@graphorin/tools/executor';
+import type { ToolRegistry } from '@graphorin/tools/registry';
+import type { ResultReader } from '@graphorin/tools/result';
+import { projectSchemaToJsonSchema } from '@graphorin/tools/schema';
+import { ToolNotFoundError } from '../errors/index.js';
+import { type PreferredModelResolution, resolvePreferredModel } from '../preferred-model/index.js';
+import { orderPromotedTools } from '../tooling/catalogue.js';
+import { buildToolRegistry } from '../tooling/registry-build.js';
+import type { AgentConfig, PrepareStepOverrides } from '../types.js';
+import { buildHandoffTool, type HandoffEntry } from './handoff.js';
+import { buildStepMessages } from './messages.js';
+import { specToProvider } from './provider-events.js';
+import type { MutableRunState } from './run-input.js';
+import { registerReadResult, registerToolSearch } from './tool-wiring.js';
+
+/** WARN-once keys for schemas the projection cannot read (per process). */
+const unprojectableSchemaWarned = new Set<string>();
+
+/**
+ * Resolve a tool's declared schema - plain Zod (v3/v4), `toJSON()`-bearing,
+ * or already-JSON-Schema data - to a JSON Schema record via the shared
+ * projection (tools-01). Pre-fix this only honoured `toJSON()` and passed
+ * everything else through verbatim, so every plain-Zod tool serialised as
+ * `{"_def":...}` internals on OpenAI-shaped/Ollama/vercel wire bodies.
+ * `undefined` when nothing usable can be projected (caller substitutes a
+ * permissive `{}`), with a WARN so the degradation is never silent.
+ */
+function projectSchema(
+  raw: unknown,
+  toolName: string,
+  slot: 'input' | 'output',
+): Readonly<Record<string, unknown>> | undefined {
+  return projectSchemaToJsonSchema(raw, {
+    onUnsupported: (detail) => {
+      const key = `${toolName}:${slot}:${detail}`;
+      if (unprojectableSchemaWarned.has(key)) return;
+      unprojectableSchemaWarned.add(key);
+      console.warn(
+        `[graphorin/agent] tool '${toolName}' ${slot} schema: '${detail}' cannot be projected ` +
+          'to JSON Schema - that fragment degrades to a permissive {} on the provider wire body.',
+      );
+    },
+  });
+}
+
+export function toolToDefinition(tool: Tool): ToolDefinition {
+  const ts = tool as Tool & {
+    readonly inputSchema?: unknown;
+    readonly outputSchema?: unknown;
+  };
+  const inputSchema = projectSchema(ts.inputSchema, tool.name, 'input') ?? {};
+  // A5: project the output schema so structured-output providers + typed
+  // code-mode see the tool's result shape.
+  const outputSchema = projectSchema(ts.outputSchema, tool.name, 'output');
+  const examples = renderToolExamples(tool);
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema,
+    ...(outputSchema !== undefined ? { outputSchema } : {}),
+    ...(examples !== undefined ? { examples } : {}),
+  };
+}
+
+/**
+ * Project a tool's worked `examples` onto the provider wire contract
+ * (WI-06 / P2-3). Examples are rendered only when the tool eagerly
+ * renders them: the registry resolves the `defer_loading` auto-rule into
+ * `examplesEagerlyRendered`, so a deferred tool resolves to `false` and is
+ * skipped (its examples stay out of context even once `tool_search`
+ * promotes it). `undefined` - the "runtime decides" case for a plain
+ * eager tool - renders, since the tool is already advertised this step.
+ *
+ * Bounded to ≤5 to honour the `ToolExample` `[1,5]` contract even when a
+ * tool slipped past the registry's overflow WARN (which does not truncate).
+ */
+function renderToolExamples(tool: Tool): ReadonlyArray<ToolDefinitionExample> | undefined {
+  const examples = tool.examples;
+  if (examples === undefined || examples.length === 0) return undefined;
+  if (tool.examplesEagerlyRendered === false) return undefined;
+  return examples.slice(0, 5).map((ex) => ({
+    input: ex.input,
+    output: ex.output,
+    ...(ex.comment !== undefined ? { comment: ex.comment } : {}),
+  }));
+}
+
+/**
+ * The run-scoped inputs of the per-step catalogue resolution. Field
+ * names mirror the run-loop locals the former inline block captured.
+ */
+export interface StepCatalogueEnv<TDeps, TOutput> {
+  readonly config: AgentConfig<TDeps, TOutput>;
+  readonly isCodeMode: boolean;
+  readonly toolRegistry: ToolRegistry;
+  readonly toolExecutor: ToolExecutor;
+  readonly makeToolExecutor: (
+    registry: ToolRegistry,
+    opts?: { readonly quiet?: boolean },
+  ) => ToolExecutor;
+  readonly resultReader: ResultReader;
+  readonly handoffMap: ReadonlyMap<string, HandoffEntry<TDeps>>;
+  readonly handoffNames: ReadonlyArray<string>;
+  readonly codeModeAdvertised: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  readonly activeRunCapability: 'read-only' | undefined;
+  readonly promotedDeferred: Set<string>;
+  readonly runStartPromotions: Set<string> | undefined;
+}
+
+/** What one step's catalogue resolution hands back to the run loop. */
+export interface StepToolContext<TDeps> {
+  readonly stepRegistry: ToolRegistry;
+  readonly stepExecutor: ToolExecutor;
+  readonly stepTools: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  readonly primary: PreferredModelResolution;
+  readonly fallbackChain: Provider[];
+}
+
+/**
+ * Resolve the registry + executor for this step. The warm-up
+ * pair is bound to config.tools + skills; a `prepareStep` tool
+ * override builds a step-scoped pair so the advertised catalogue
+ * and the executor agree on the same tool set (incl. deferred
+ * discovery for the overridden set). Code-mode does not honour a
+ * per-step `tools` override (the meta-tools + bridge are bound to
+ * the warm-up registry), so it always uses the warm-up pair.
+ *
+ * Also assembles the per-step tool catalogue (code-mode meta-tools or
+ * eager + handoffs + promotions, read-only filtered under D2), resolves
+ * the step's preferred model (AG-15: consulting only the tools the
+ * model CALLED on the previous step), and derives the step's provider
+ * fallback chain (RB-48: a `prepareStep` provider override suppresses
+ * the chain).
+ */
+export function resolveStepToolContext<TDeps, TOutput>(
+  env: StepCatalogueEnv<TDeps, TOutput>,
+  overrides: PrepareStepOverrides<TDeps>,
+  lastStepCalledToolNames: ReadonlyArray<string>,
+): StepToolContext<TDeps> {
+  const { config, isCodeMode, toolRegistry, toolExecutor, makeToolExecutor } = env;
+  const { resultReader, handoffMap, handoffNames, codeModeAdvertised } = env;
+  const { activeRunCapability, promotedDeferred, runStartPromotions } = env;
+
+  const useOverrideRegistry = overrides.tools !== undefined && !isCodeMode;
+  const stepRegistry: ToolRegistry = useOverrideRegistry
+    ? buildToolRegistry({
+        tools: overrides.tools as ReadonlyArray<Tool<unknown, unknown, unknown>>,
+      }).registry
+    : toolRegistry;
+  if (useOverrideRegistry) {
+    registerToolSearch(
+      stepRegistry,
+      config.toolPromotion === 'run-boundary' ? 'next-run' : 'next-step',
+    );
+    registerReadResult(stepRegistry, resultReader);
+  }
+  const stepExecutor: ToolExecutor = useOverrideRegistry
+    ? makeToolExecutor(stepRegistry)
+    : toolExecutor;
+
+  // Build the per-step tool catalogue. Handoff tools are synthetic
+  // per-step entries and are always advertised.
+  const handoffTools: Tool<unknown, unknown, TDeps>[] = handoffNames.map((n) => {
+    const h = handoffMap.get(n);
+    if (h === undefined) throw new ToolNotFoundError(n);
+    return buildHandoffTool<TDeps>(h.agent);
+  });
+  // Code-mode (WI-11): advertise only the `code_search` /
+  // `code_execute` (+ `read_result`) meta-tools - the model reaches
+  // every real tool through `code_execute`, so the real tools stay
+  // registered (executable via the in-script bridge) but out of the
+  // model's catalogue. Otherwise (WI-05): advertise the eager tools
+  // (`tool_search` is itself eager iff a deferred tool exists) plus
+  // any deferred tools already promoted by a `tool_search` this run -
+  // never the rest of the deferred pool.
+  // D2 single-writer constraint: a read-only run never ADVERTISES
+  // writer tools (side-effecting / external-stateful) nor handoffs
+  // (a transfer hands the writer pen to another agent). The
+  // executor-level capability gate backs this up for calls the
+  // model fabricates anyway.
+  const readOnlyRun = activeRunCapability === 'read-only';
+  const keepReadOnly = (t: Tool<unknown, unknown, TDeps>): boolean => {
+    const cls = (t as { __sideEffectClass?: string }).__sideEffectClass ?? t.sideEffectClass;
+    return cls === 'pure' || cls === 'read-only';
+  };
+  let stepTools: ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+  if (isCodeMode) {
+    stepTools = readOnlyRun
+      ? [...codeModeAdvertised.filter(keepReadOnly)]
+      : [...codeModeAdvertised, ...handoffTools];
+  } else {
+    const eagerTools = stepRegistry.listEager() as ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+    // A7: emit promoted deferred tools in PROMOTION order (append-only) so
+    // a later promotion joins the END and the prompt-cache prefix stays
+    // byte-stable across steps. C1 (agent-11): handoff tools serialize
+    // BEFORE the growing promoted section - handoffs are fixed per run,
+    // so the stable prefix is now eager + handoffs + earlier promotions
+    // and a new promotion shifts nothing that came before it.
+    // 'run-boundary' promotion advertises only the run-start snapshot.
+    const advertisedPromotions = runStartPromotions ?? promotedDeferred;
+    const promotedTools = (
+      advertisedPromotions.size === 0
+        ? []
+        : orderPromotedTools(advertisedPromotions, stepRegistry.listDeferred())
+    ) as ReadonlyArray<Tool<unknown, unknown, TDeps>>;
+    stepTools = readOnlyRun
+      ? [...eagerTools.filter(keepReadOnly), ...promotedTools.filter(keepReadOnly)]
+      : [...eagerTools, ...handoffTools, ...promotedTools];
+  }
+
+  // AG-15: consult the hints of the tools the model CALLED on the
+  // previous step - a smart-hinted but never-called tool must not
+  // pin the whole conversation to the top cost tier. Steps with no
+  // prior calls fall through to the agent-preferred default.
+  const calledLastStep = new Set(lastStepCalledToolNames);
+  const toolPreferences = stepTools
+    .filter((t) => calledLastStep.has(t.name))
+    .map((t) => {
+      const tt = t as Tool<unknown, unknown, TDeps> & { readonly preferredModel?: unknown };
+      return tt.preferredModel as Parameters<
+        typeof resolvePreferredModel
+      >[0]['toolPreferredModels'][number];
+    });
+
+  const primary: PreferredModelResolution = resolvePreferredModel({
+    ...(overrides.provider !== undefined ? { prepareStepProvider: overrides.provider } : {}),
+    toolPreferredModels: toolPreferences,
+    ...(config.preferredModel !== undefined ? { agentPreferredModel: config.preferredModel } : {}),
+    agentDefaultProvider: config.provider,
+    ...(config.modelTierMap !== undefined ? { modelTierMap: config.modelTierMap } : {}),
+  });
+
+  // RB-48: when `prepareStep` returns an explicit provider
+  // override, the fallback chain is NOT consulted for this
+  // step (the operator's explicit choice supersedes the
+  // implicit fallback chain).
+  const fallbackChain: Provider[] =
+    primary.source === 'prepare-step'
+      ? [primary.resolvedProvider]
+      : [primary.resolvedProvider, ...(config.fallbackModels ?? []).map(specToProvider)];
+
+  return { stepRegistry, stepExecutor, stepTools, primary, fallbackChain };
+}
+
+/** What the per-step request assembly needs from the run loop's scope. */
+export interface StepRequestEnv<TDeps, TOutput> {
+  readonly config: AgentConfig<TDeps, TOutput>;
+  readonly state: MutableRunState & RunState;
+  readonly messages: Message[];
+  readonly sessionId: string;
+  readonly agentId: string;
+  readonly userId: string | undefined;
+  readonly signal: AbortSignal;
+  readonly structuredInstruction: string | undefined;
+  readonly getActiveTodos: () => ReadonlyArray<import('@graphorin/core').TodoItem> | undefined;
+}
+
+/**
+ * Assemble the step's base {@link ProviderRequest} over the shared
+ * message buffer: the D6 request-only trailing additions (structured
+ * instruction + plan recitation) ride `buildStepMessages`, the
+ * `prepareStep` overrides / config knobs spread in exactly as the
+ * inline literal did, and the effective reasoning-retention policy
+ * rides the request (RB-42).
+ */
+export function buildBaseRequest<TDeps, TOutput>(
+  env: StepRequestEnv<TDeps, TOutput>,
+  overrides: PrepareStepOverrides<TDeps>,
+  toolDefs: ReadonlyArray<ToolDefinition>,
+  reasoningPolicy: ReasoningRetention,
+  stepNumber: number,
+  currentStepSpan: AISpan<'agent.step'> | undefined,
+): ProviderRequest {
+  const { config, state, messages, sessionId, agentId, userId, signal } = env;
+  const { structuredInstruction, getActiveTodos } = env;
+  return {
+    // AG-3 fallback contract: for structured output the request
+    // carries ONE trailing system instruction (JSON-only + schema)
+    // in the request copy - never in the shared buffer or the
+    // persisted RunState. Adapters with native structured output
+    // additionally receive `outputType` below (PS-24 consumes it).
+    messages: buildStepMessages(messages, structuredInstruction, getActiveTodos()),
+    ...(config.outputType !== undefined
+      ? {
+          outputType: {
+            kind: config.outputType.kind,
+            ...(config.outputType.description !== undefined
+              ? { description: config.outputType.description }
+              : {}),
+            ...(config.outputType.jsonSchema !== undefined
+              ? { jsonSchema: config.outputType.jsonSchema }
+              : {}),
+          },
+        }
+      : {}),
+    tools: toolDefs,
+    ...(overrides.toolChoice !== undefined
+      ? { toolChoice: overrides.toolChoice }
+      : config.toolChoice !== undefined
+        ? { toolChoice: config.toolChoice as ToolChoice }
+        : {}),
+    metadata: {
+      sessionId,
+      agentId,
+      ...(userId !== undefined ? { userId } : {}),
+      runId: state.id,
+      stepNumber,
+    },
+    signal,
+    ...(overrides.temperature !== undefined ? { temperature: overrides.temperature } : {}),
+    ...(overrides.maxTokens !== undefined ? { maxTokens: overrides.maxTokens } : {}),
+    ...(config.cachePolicy !== undefined ? { cachePolicy: config.cachePolicy } : {}),
+    ...(currentStepSpan !== undefined ? { parentSpan: currentStepSpan } : {}),
+    reasoningRetention: reasoningPolicy,
+  };
+}

package/src/runtime/tool-call-walk.ts

@@ -0,0 +1,301 @@
+/**
+ * The per-step tool-call walk of the agent run loop: batches
+ * non-handoff calls for the executor (flushing before a handoff and
+ * before each approval-gated call so execution order is kept), executes
+ * the ≤1 handoff inline, pre-screens `needsApproval` with validated
+ * args (tools-02), collects EVERY gated call (agent-01), and performs
+ * the once-per-step durable-HITL suspend with its taint / promotion
+ * snapshot + checkpoint (AG-19 / AG-23). Extracted verbatim from
+ * `factory.ts` (issue #23); the former inline walk now takes an
+ * explicit {@link ToolCallWalkEnv} and returns `{ suspended }` instead
+ * of finishing the run itself.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AgentEvent,
+  CompletedToolCall,
+  RunContext,
+  ToolApproval,
+  ToolCall,
+  ToolError,
+} from '@graphorin/core';
+import type { ToolExecutor } from '@graphorin/tools/executor';
+import type { ToolRegistry } from '@graphorin/tools/registry';
+import { serializeRunState } from '../run-state/index.js';
+import type { AgentConfig } from '../types.js';
+import { getSubAgentToolRefs, type SubAgentToolRefs } from './agent-to-tool.js';
+import { invokeNeedsApproval, safeParseGatedArgs } from './approvals.js';
+import type { DispatchBatchFn } from './dispatch.js';
+import {
+  executeHandoffToolCall,
+  type HandoffEntry,
+  type HandoffRunEnv,
+  runSubAgentCall,
+} from './handoff.js';
+import { renderToolErrorMessage } from './messages.js';
+import type { AssistantCommitEnv } from './run-gates.js';
+import { isApprovalGated } from './tool-wiring.js';
+
+/**
+ * The run-scoped context the walk operates on. Extends the handoff
+ * execution env (the walk hands it through verbatim); the extra fields
+ * mirror the run-loop locals the former inline walk captured.
+ */
+export interface ToolCallWalkEnv<TDeps, TOutput> extends HandoffRunEnv<TDeps, TOutput> {
+  readonly config: Pick<AgentConfig<TDeps, TOutput>, 'deps' | 'checkpointStore'>;
+  readonly handoffMap: ReadonlyMap<string, HandoffEntry<TDeps>>;
+  readonly toolDataFlowGuard: AssistantCommitEnv['toolDataFlowGuard'];
+  readonly promotedDeferred: Set<string>;
+  readonly dispatchBatch: DispatchBatchFn<TDeps, TOutput>;
+}
+
+/**
+ * Walk calls in finalCalls order. Handoffs are special-cased
+ * inline (≤1 per step) and never routed through the executor.
+ * Non-handoff calls accumulate into a batch dispatched through
+ * the ToolExecutor; the batch is flushed before a handoff and
+ * before each approval-gated call so execution order is kept.
+ * Gated calls are COLLECTED (all of them, agent-01) and the run
+ * suspends once after the walk, so every non-gated toolCallId
+ * has a tool message before the suspend snapshot - a dropped
+ * call would persist a dangling `tool_use` that real providers
+ * reject on resume.
+ */
+export async function* processStepToolCalls<TDeps, TOutput>(
+  env: ToolCallWalkEnv<TDeps, TOutput>,
+  finalCalls: ReadonlyArray<ToolCall>,
+  stepRegistry: ToolRegistry,
+  stepExecutor: ToolExecutor,
+  execRunContext: RunContext<TDeps>,
+  stepNumber: number,
+): AsyncGenerator<
+  AgentEvent<TOutput>,
+  { readonly suspended: boolean; readonly abortPending?: boolean },
+  void
+> {
+  const { config, state, messages, signal, handoffMap } = env;
+  const { toolDataFlowGuard, promotedDeferred, dispatchBatch } = env;
+  let batch: ToolCall[] = [];
+  let stepApprovalsRequested = 0;
+
+  for (const call of finalCalls) {
+    const handoff = handoffMap.get(call.toolName);
+    if (handoff !== undefined) {
+      if (batch.length > 0) {
+        yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+        batch = [];
+      }
+      const handed = yield* executeHandoffToolCall<TDeps, TOutput>(env, call, handoff, stepNumber);
+      // W-001: the handoff child suspended awaiting approvals - it
+      // parked on the parent and the parent suspends once per step
+      // exactly like a directly-gated call.
+      if (handed.suspendRequested) stepApprovalsRequested += 1;
+      continue;
+    }
+
+    // Approval pre-screen (Adapter G / durable HITL). Evaluate the
+    // registry-resolved `needsApproval`; a gated call flushes the
+    // queued batch (prior calls' side-effects complete first) and
+    // is recorded as a pending approval. The walk CONTINUES: later
+    // gated calls are collected too, and later non-gated calls
+    // still execute before the suspend (agent-01 - previously
+    // everything after the first gated call was silently dropped,
+    // never executed and never approvable, leaving dangling
+    // `tool_use` ids in the persisted transcript).
+    const resolvedTool = stepRegistry.get(call.toolName);
+    // tools-02 (agent mirror): the approval decision must be made
+    // on the input that will actually execute. For gated tools the
+    // args are validated HERE: a schema failure fails the call fast
+    // as `invalid_input` (a human is never asked to approve args
+    // that cannot run, and the resumed dispatch can therefore never
+    // hit the repair hook), and the predicate receives the parsed
+    // value its typed signature promises - not raw pre-coercion
+    // JSON.
+    let gateInput: unknown = call.args;
+    if (resolvedTool !== undefined && isApprovalGated(resolvedTool)) {
+      const parsed = safeParseGatedArgs(resolvedTool, call.args);
+      if (parsed !== undefined && !parsed.success) {
+        const toolError: ToolError = {
+          toolCallId: call.toolCallId,
+          toolName: call.toolName,
+          kind: 'invalid_input',
+          message: `Invalid arguments for approval-gated tool '${call.toolName}': ${parsed.message}`,
+        };
+        const stepEntry = state.steps[state.steps.length - 1];
+        if (stepEntry !== undefined) {
+          (stepEntry.toolCalls as CompletedToolCall[]).push({
+            call,
+            outcome: toolError,
+            stepNumber,
+          });
+        }
+        yield { type: 'tool.execute.start', toolCallId: call.toolCallId, toolName: call.toolName };
+        yield {
+          type: 'tool.execute.error',
+          toolCallId: call.toolCallId,
+          toolName: call.toolName,
+          error: toolError,
+        };
+        const text = renderToolErrorMessage(toolError);
+        messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+        state.messages.push({ role: 'tool', toolCallId: call.toolCallId, content: text });
+        continue;
+      }
+      if (parsed !== undefined) gateInput = parsed.data;
+    }
+    const needsApproval = await invokeNeedsApproval(
+      resolvedTool,
+      gateInput,
+      execRunContext,
+      signal,
+    );
+    if (needsApproval) {
+      if (batch.length > 0) {
+        yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+        batch = [];
+      }
+      yield { type: 'tool.execute.start', toolCallId: call.toolCallId, toolName: call.toolName };
+      const approval: ToolApproval = {
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        args: call.args,
+        requestedAt: new Date().toISOString(),
+      };
+      state.pendingApprovals.push(approval);
+      stepApprovalsRequested += 1;
+      yield {
+        type: 'tool.approval.requested',
+        toolCallId: call.toolCallId,
+      };
+      continue;
+    }
+
+    // W-001: `toTool` sub-agent tools execute INLINE through the same
+    // seam as a handoff (never through the executor, which cannot
+    // suspend a run) - a child that parks on `awaiting_approval`
+    // suspends the parent instead of surfacing a terminal tool error.
+    const subRefs = getSubAgentToolRefs(resolvedTool);
+    if (subRefs !== undefined) {
+      if (batch.length > 0) {
+        yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+        batch = [];
+      }
+      const subbed = yield* executeSubAgentToolCall<TDeps, TOutput>(
+        env,
+        call,
+        subRefs,
+        execRunContext,
+        stepNumber,
+      );
+      if (subbed.suspendRequested) stepApprovalsRequested += 1;
+      continue;
+    }
+
+    batch.push(call);
+  }
+
+  if (batch.length > 0) {
+    yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+  }
+
+  // Durable-HITL suspend: once per step, carrying EVERY gated call
+  // the model batched. Runs after the final batch flush so the
+  // suspend snapshot already contains tool messages for the whole
+  // non-gated remainder of the step.
+  if (stepApprovalsRequested > 0) {
+    state.status = 'awaiting_approval';
+    // AG-19: persist the coarse taint summary + promoted-tool set into
+    // the suspended state so a resume rehydrates the sink gate and the
+    // discovered-tool catalogue instead of starting empty.
+    const taintSnap = toolDataFlowGuard?.snapshotLedger(state.id);
+    if (taintSnap !== undefined) state.taintSummary = taintSnap;
+    if (promotedDeferred.size > 0) state.promotedTools = [...promotedDeferred];
+    // W-038: an abort that arrived while this step was collecting gated
+    // calls must reach the `onPendingApprovals` policy INSTEAD of the
+    // unconditional suspend - and no 'suspended awaiting_approval'
+    // checkpoint may be written first, or the durable trail would
+    // contradict the aborted outcome and resurrect denied approvals on
+    // resume. The factory applies the policy and persists the final,
+    // policy-consistent state through the same put seam.
+    if (signal.aborted) {
+      return { suspended: true, abortPending: true };
+    }
+    if (config.checkpointStore !== undefined) {
+      await config.checkpointStore.put(
+        state.id,
+        'agent',
+        {
+          id: state.id,
+          threadId: state.id,
+          namespace: 'agent',
+          // AG-23: persist a detached, secret-redacted snapshot -
+          // never the live MutableRunState reference.
+          state: serializeRunState(state, { stripTracingApiKey: true }),
+          channelVersions: {},
+          stepNumber,
+          createdAt: new Date().toISOString(),
+        },
+        { source: 'sync', status: 'suspended', nodeName: 'agent.run', sessionId: state.sessionId },
+      );
+    }
+    return { suspended: true };
+  }
+  return { suspended: false };
+}
+
+/**
+ * W-001: execute a `toTool` sub-agent call INLINE (mirroring the
+ * handoff seam): reproduce `execute()`'s seed and output shaping via
+ * the tool's {@link SubAgentToolRefs}, and settle through the shared
+ * {@link runSubAgentCall} so a suspending child parks instead of
+ * throwing. The D2 taint fold that the executor would have applied from
+ * the ToolReturn envelope is recorded directly on the data-flow guard.
+ */
+async function* executeSubAgentToolCall<TDeps, TOutput>(
+  env: ToolCallWalkEnv<TDeps, TOutput>,
+  call: ToolCall,
+  refs: SubAgentToolRefs,
+  execRunContext: RunContext<TDeps>,
+  stepNumber: number,
+): AsyncGenerator<AgentEvent<TOutput>, { readonly suspendRequested: boolean }, void> {
+  const { config, options, messages, sessionId, signal, toolDataFlowGuard } = env;
+  yield { type: 'tool.execute.start', toolCallId: call.toolCallId, toolName: call.toolName };
+  const rawInput = (call.args ?? {}) as { readonly input?: unknown };
+  const input = { input: typeof rawInput.input === 'string' ? rawInput.input : '' };
+  const parentSpan = env.getCurrentStepSpan?.();
+  const callOpts: Record<string, unknown> = {
+    signal,
+    ...(options.deps !== undefined || config.deps !== undefined
+      ? { deps: options.deps ?? config.deps }
+      : {}),
+    sessionId,
+    ...(refs.capability !== undefined ? { capability: refs.capability } : {}),
+    // W-036: one trace tree through the inline walk too.
+    ...(parentSpan !== undefined ? { parentSpan } : {}),
+  };
+  const seed = refs.buildSeed(input, messages);
+  const subStream = refs.stream(seed, callOpts);
+  return yield* runSubAgentCall<TDeps, TOutput>(
+    env,
+    call,
+    {
+      agentName: refs.agentName,
+      subStream,
+      errorLabel: `sub-agent '${refs.agentName}'`,
+      renderCompleted: refs.shapeCompleted,
+      ...(refs.forwardEvents !== undefined ? { forwardEvents: refs.forwardEvents } : {}),
+      recordTaint: (taint, renderedText) => {
+        toolDataFlowGuard?.record({
+          toolName: call.toolName,
+          trustClass: 'first-party-user-defined',
+          taintOverride: taint,
+          outputText: renderedText,
+          runContext: execRunContext as RunContext,
+        });
+      },
+    },
+    stepNumber,
+  );
+}