@noetic-tools/core 1.1.1 → 1.2.0

package/dist/builders/step-builders.d.ts

@@ -1,5 +1,5 @@
 import type { ContextMemory } from '@noetic-tools/memory';
-import type { Context, Lazy, ModelParams, RetryPolicy, StepLLM, StepRun, StepTool, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { Context, Lazy, ModelParams, RetryPolicy, StepLLM, StepRun, StepSubHarness, StepTool, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
 import type { ZodType } from 'zod';
 interface StepRunOpts<TMemory, I, O> {
     id: string;
@@ -29,6 +29,22 @@ interface StepToolOpts<I, O> {
     tool: Tool<ZodType<I>, ZodType<O>>;
     args?: Partial<I>;
 }
+interface StepSubHarnessOpts<TMemory, O> {
+    id: string;
+    /** The harness adapter created by a `@noetic-tools/sub-harness-*` factory. Eager or `(ctx) => SubHarness`. */
+    harness: Lazy<SubHarness, TMemory>;
+    /** Turn prompt. Eager string or `(ctx) => string` getter. */
+    prompt: Lazy<string, TMemory>;
+    /** Shared harness settings (model, permission mode, …). */
+    settings?: SubHarnessSettings;
+    /** System instructions applied on the first message of a fresh session. */
+    instructions?: Lazy<string | undefined, TMemory>;
+    /** Optional Zod schema; when set the assistant text is JSON-parsed and validated. */
+    output?: ZodType<O>;
+    /** Session reuse + teardown policy across steps. */
+    session?: SubHarnessSessionPolicy;
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+}
 export declare const step: {
     /**
      * Creates a pure async computation step.
@@ -75,5 +91,39 @@ export declare const step: {
      * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
      */
     tool<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepToolOpts<I, O>): StepTool<TMemory, I, O>;
+    /**
+     * Creates a step that delegates a turn to the Claude Code harness.
+     *
+     * @public
+     * @param opts.id - Unique step identifier.
+     * @param opts.harness - A `claudeCode(...)` adapter from `@noetic-tools/sub-harness-claude-code`.
+     * @param opts.prompt - The turn prompt; eager string or `(ctx) => string` getter.
+     * @param opts.settings - Shared harness settings (model, permission mode, …).
+     * @param opts.output - Optional Zod schema enabling structured output parsing.
+     * @returns A `StepSubHarness` of kind `claude-code`, auto-registered in the step registry.
+     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_SUB_HARNESS` / `SUB_HARNESS_KIND_MISMATCH`.
+     */
+    claudeCode<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    /**
+     * Creates a step that delegates a turn to the Codex harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `codex(...)` adapter.
+     * @returns A `StepSubHarness` of kind `codex`.
+     */
+    codex<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    /**
+     * Creates a step that delegates a turn to the opencode harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is an `opencode(...)` adapter.
+     * @returns A `StepSubHarness` of kind `opencode`.
+     */
+    opencode<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
+    /**
+     * Creates a step that delegates a turn to the pi harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `pi(...)` adapter.
+     * @returns A `StepSubHarness` of kind `pi`.
+     */
+    pi<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TMemory, O>): StepSubHarness<TMemory, I, O>;
 };
 export {};

package/dist/builders/step-builders.js

@@ -1,6 +1,45 @@
 import { NoeticConfigError } from '@noetic-tools/types';
 import { getDefaultRegistrar } from '../types/step-registrar.js';
 //#endregion
+//#region SubHarness builder helper
+/**
+ * Shared construction for every harness step kind. Each `step.<kind>()` is a
+ * thin wrapper so the kinds stay individually typed while the validation and
+ * registration live in one place.
+ */
+function buildSubHarnessStep(kind, builderName, opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: `${builderName}() requires a non-empty id.`,
+            hint: `Pass a unique string as the id field, e.g. ${builderName}({ id: "review", ... }).`,
+        });
+    }
+    if (!opts.harness) {
+        throw new NoeticConfigError({
+            code: 'MISSING_SUB_HARNESS',
+            message: `${builderName}() requires a harness adapter.`,
+            hint: `Pass a harness factory result, e.g. harness: ${builderName.replace('step.', '')}({ model }).`,
+        });
+    }
+    // Eager adapters are validated now; function-form adapters are validated
+    // post-resolution in executeSubHarness so the same SUB_HARNESS_KIND_MISMATCH
+    // error surfaces whether the caller passes an adapter or a getter.
+    if (typeof opts.harness !== 'function' && opts.harness.harnessId !== kind) {
+        throw new NoeticConfigError({
+            code: 'SUB_HARNESS_KIND_MISMATCH',
+            message: `${builderName}() was given a '${opts.harness.harnessId}' harness.`,
+            hint: `Use the matching builder, e.g. step.${opts.harness.harnessId}({ ... }).`,
+        });
+    }
+    const built = {
+        kind,
+        ...opts,
+    };
+    getDefaultRegistrar().register(built);
+    return built;
+}
+//#endregion
 //#region Builders
 export const step = {
     /**
@@ -114,5 +153,47 @@ export const step = {
         getDefaultRegistrar().register(built);
         return built;
     },
+    /**
+     * Creates a step that delegates a turn to the Claude Code harness.
+     *
+     * @public
+     * @param opts.id - Unique step identifier.
+     * @param opts.harness - A `claudeCode(...)` adapter from `@noetic-tools/sub-harness-claude-code`.
+     * @param opts.prompt - The turn prompt; eager string or `(ctx) => string` getter.
+     * @param opts.settings - Shared harness settings (model, permission mode, …).
+     * @param opts.output - Optional Zod schema enabling structured output parsing.
+     * @returns A `StepSubHarness` of kind `claude-code`, auto-registered in the step registry.
+     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_SUB_HARNESS` / `SUB_HARNESS_KIND_MISMATCH`.
+     */
+    claudeCode(opts) {
+        return buildSubHarnessStep('claude-code', 'step.claudeCode', opts);
+    },
+    /**
+     * Creates a step that delegates a turn to the Codex harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `codex(...)` adapter.
+     * @returns A `StepSubHarness` of kind `codex`.
+     */
+    codex(opts) {
+        return buildSubHarnessStep('codex', 'step.codex', opts);
+    },
+    /**
+     * Creates a step that delegates a turn to the opencode harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is an `opencode(...)` adapter.
+     * @returns A `StepSubHarness` of kind `opencode`.
+     */
+    opencode(opts) {
+        return buildSubHarnessStep('opencode', 'step.opencode', opts);
+    },
+    /**
+     * Creates a step that delegates a turn to the pi harness.
+     * @public
+     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `pi(...)` adapter.
+     * @returns A `StepSubHarness` of kind `pi`.
+     */
+    pi(opts) {
+        return buildSubHarnessStep('pi', 'step.pi', opts);
+    },
 };
 //#endregion

package/dist/builders/workflow-hydrator.d.ts

@@ -6,13 +6,15 @@
  * ones — they register in the step registry, carry retry policies, etc.
  */
 import type { ContextMemory, MemoryLayer } from '@noetic-tools/memory';
-import type { ExecuteStepFn, Step, Tool } from '@noetic-tools/types';
+import type { ExecuteStepFn, Step, SubHarness, SubHarnessKind, Tool } from '@noetic-tools/types';
 import type { WorkflowDocument, WorkflowNode } from '../schemas/workflow.js';
 /** @public Context required to hydrate a JSON workflow into live steps. */
 export interface HydrationContext {
     tools: ReadonlyMap<string, Tool>;
     executeStep: ExecuteStepFn;
     layers?: ReadonlyMap<string, MemoryLayer>;
+    /** SubHarness adapters keyed by harness id, resolving `claude-code`/`codex`/… nodes. */
+    subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
 }
 /**
  * Hydrates a single `WorkflowNode` into a live `Step`.

package/dist/builders/workflow-hydrator.js

@@ -246,6 +246,36 @@ function hydrateEveryNode(node, ctx) {
         onError: node.onError,
     });
 }
+const SUB_HARNESS_BUILDERS = {
+    'claude-code': (opts) => step.claudeCode(opts),
+    codex: (opts) => step.codex(opts),
+    opencode: (opts) => step.opencode(opts),
+    pi: (opts) => step.pi(opts),
+};
+function hydrateSubHarnessNode(node, ctx) {
+    if (node.kind !== 'claude-code' &&
+        node.kind !== 'codex' &&
+        node.kind !== 'opencode' &&
+        node.kind !== 'pi') {
+        return frameworkCast(undefined);
+    }
+    const harness = ctx.subHarnesses?.get(node.kind);
+    if (!harness) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_SUB_HARNESS_REFERENCE',
+            message: `SubHarness '${node.kind}' referenced in workflow node '${node.id}' is not registered.`,
+            hint: `Pass harness adapters via HydrationContext.subHarnesses, e.g. new Map([['${node.kind}', ${node.kind.replace(/-([a-z])/g, (_, c) => c.toUpperCase())}({ model })]]).`,
+        });
+    }
+    return SUB_HARNESS_BUILDERS[node.kind]({
+        id: node.id,
+        harness,
+        prompt: node.prompt,
+        instructions: node.instructions,
+        settings: node.settings,
+        session: node.session,
+    });
+}
 //#endregion
 //#region Handler Registry
 const NODE_HYDRATORS = {
@@ -258,6 +288,10 @@ const NODE_HYDRATORS = {
     loop: hydrateLoopNode,
     sequence: hydrateSequenceNode,
     every: hydrateEveryNode,
+    'claude-code': hydrateSubHarnessNode,
+    codex: hydrateSubHarnessNode,
+    opencode: hydrateSubHarnessNode,
+    pi: hydrateSubHarnessNode,
 };
 //#endregion
 //#region Helpers

package/dist/harness/agent-harness.d.ts

@@ -2,7 +2,7 @@ import { ItemSchemaRegistry } from '@noetic-tools/types';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { LayerStateStore, RecallCache } from './deps/memory.js';
 import type { CheckpointStore, EventBroadcaster } from './deps/runtime.js';
-import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextMemory, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, MemoryLayer, ProjectionPolicy, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 interface AgentHarnessOpts<TParams extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
@@ -95,6 +95,13 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private readonly defaultDeliveryMode;
     private readonly streamIdleTimeoutMs;
     private readonly sessions;
+    /**
+     * @internal Cross-step harness sessions keyed by `step.session.reuse`, kept
+     * alive for the life of this harness so reused coding-agent sessions span
+     * multiple steps. Reached by the interpreter's harness handler via
+     * `frameworkCast`; do not access from outside core.
+     */
+    readonly subHarnessSessions: Map<string, SubHarnessSession>;
     readonly layerStateStore: LayerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     readonly recallCache: RecallCache;

package/dist/harness/agent-harness.js

@@ -100,6 +100,13 @@ export class AgentHarness {
     defaultDeliveryMode;
     streamIdleTimeoutMs;
     sessions = new Map();
+    /**
+     * @internal Cross-step harness sessions keyed by `step.session.reuse`, kept
+     * alive for the life of this harness so reused coding-agent sessions span
+     * multiple steps. Reached by the interpreter's harness handler via
+     * `frameworkCast`; do not access from outside core.
+     */
+    subHarnessSessions = new Map();
     layerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     recallCache;
@@ -339,6 +346,16 @@ export class AgentHarness {
     }
     //#endregion
     async run(s, input, ctx) {
+        // Populate the unified tool pool when an embedder drives a step directly on
+        // a bare `createContext()` context (the turn pipeline does this per turn).
+        // Without it, steps that resolve tools dynamically from `ctx.unifiedTools`
+        // — and any sub-agents spawned from them — would see no tools.
+        if (!ctx.unifiedTools && (s !== undefined || this.harnessTools.length > 0)) {
+            this.setUnifiedTools(ctx, [
+                ...collectAllTools(s),
+                ...this.harnessTools,
+            ]);
+        }
         return execute(s, input, ctx);
     }
     /** Run all layer `init` hooks before the first step executes. Per spec 11,

package/dist/harness/deps/types.d.ts

@@ -1,4 +1,4 @@
 export type { ContextMemory, ExecutionContext, MemoryLayer, ProjectionPolicy, StorageAdapter, } from '@noetic-tools/memory';
-export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
+export type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaExtensions, LLMResponse, LlmProviderConfig, RecallLayerOutput, SessionScope, ShellAdapter, Span, SteeringDecision, Step, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, } from '@noetic-tools/types';
 export { SteeringAction } from '@noetic-tools/types';
 export type { ZodType } from 'zod';

package/dist/index.d.ts

@@ -108,7 +108,7 @@ export { getRegistry, lookupStep, registerStep } from './runtime/step-registry.j
 /** @public */
 export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from '@noetic-tools/types';
 /** @public */
-export type { BranchRoute, BranchWorkflowNode, EveryWorkflowNode, ForkWorkflowNode, LlmWorkflowNode, LoopWorkflowNode, MergeStrategy, ProvideWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, ToolWorkflowNode, UntilPredicate, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
+export type { BranchRoute, BranchWorkflowNode, EveryWorkflowNode, ForkWorkflowNode, LlmWorkflowNode, LoopWorkflowNode, MergeStrategy, ProvideWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubHarnessWorkflowNode, ToolWorkflowNode, UntilPredicate, WorkflowDocument, WorkflowNode, } from './schemas/workflow.js';
 /** @public */
 export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, } from './schemas/workflow.js';
 /** @public */
@@ -153,7 +153,11 @@ export type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams,
 /** @public */
 export { LedgerEntryKind, SteeringAction } from '@noetic-tools/types';
 /** @public */
-export type { ExecuteStepFn, SettleResult, Snapshot, Step, StepBranch, StepFork, StepForkAll, StepForkRace, StepForkSettle, StepLLM, StepLoop, StepProvide, StepRun, StepSpawn, StepTool, Until, Verdict, } from '@noetic-tools/types';
+export type { ExecuteStepFn, SettleResult, Snapshot, Step, StepBranch, StepFork, StepForkAll, StepForkRace, StepForkSettle, StepLLM, StepLoop, StepProvide, StepRun, StepSpawn, StepSubHarness, StepTool, Until, Verdict, } from '@noetic-tools/types';
+/** @public */
+export type { SubHarness, SubHarnessBuiltinTool, SubHarnessContinueState, SubHarnessContinueTurnOptions, SubHarnessFinishReason, SubHarnessPromptTurnOptions, SubHarnessResumeState, SubHarnessRunContext, SubHarnessSession, SubHarnessSessionPolicy, SubHarnessSettings, SubHarnessStartOptions, SubHarnessStreamPart, SubHarnessTurnResult, } from '@noetic-tools/types';
+/** @public */
+export { SUB_HARNESS_KINDS, SubHarnessKind, SubHarnessStreamPartSchema } from '@noetic-tools/types';
 /** @public */
 export type { FsAdapter, FsStats } from '@noetic-tools/types';
 /** @public */

package/dist/index.js

@@ -108,6 +108,8 @@ export { Slot } from '@noetic-tools/memory';
 /** @public */
 export { LedgerEntryKind, SteeringAction } from '@noetic-tools/types';
 /** @public */
+export { SUB_HARNESS_KINDS, SubHarnessKind, SubHarnessStreamPartSchema } from '@noetic-tools/types';
+/** @public */
 export { TIMEOUT_ERROR_PREFIX } from '@noetic-tools/types';
 /** @public Reusable error-serialiser used by custom SubprocessAdapter implementations. */
 export { serializeError } from './adapters/in-memory-subprocess/metadata.js';

package/dist/interpreter/collect-tools.js

@@ -38,6 +38,12 @@ function walkStep(step, out) {
             return;
         case 'run':
         case 'tool':
+        // SubHarness steps run their own built-in tools inside the external agent;
+        // they contribute nothing to the host unified tool set.
+        case 'claude-code':
+        case 'codex':
+        case 'opencode':
+        case 'pi':
             return;
         case 'branch':
             if (step._optimizable) {

package/dist/interpreter/execute-action.d.ts

@@ -4,6 +4,16 @@
 import type { ItemSchemaRegistry, LayerStateStore } from './action-deps.js';
 import type { AgentHarnessContract, Context, ExecuteStepFn, MemoryLayer, StepLLM, StepProvide, StepRun, StepSpawn, StepTool } from './action-types.js';
 export declare function executeRun<TMemory, I, O>(step: StepRun<TMemory, I, O>, input: I, ctx: Context<TMemory>): Promise<O>;
+/**
+ * Resolves a `Lazy<T>` step field. If the value is a function, it is invoked
+ * with the current context; otherwise the value is returned as-is. Supports
+ * both sync and async getters.
+ *
+ * Lazy fields let a step inspect `ctx.harness.config.params`, `ctx.unifiedTools`,
+ * or memory layer state to produce per-execution values (model, instructions,
+ * tools) without baking them in at build time.
+ */
+export declare function resolveLazy<T, TMemory>(value: T | ((ctx: Context<TMemory>) => T | Promise<T>), ctx: Context<TMemory>): Promise<T>;
 export declare function executeLLM<TMemory, I, O>(step: StepLLM<TMemory, I, O>, input: I, ctx: Context<TMemory>, layers?: MemoryLayer[]): Promise<O>;
 export interface ExecuteSpawnOpts {
     layerStore?: LayerStateStore;

package/dist/interpreter/execute-action.js

@@ -95,7 +95,7 @@ function mergeRecallResults(base, overrides, slotOf) {
  * or memory layer state to produce per-execution values (model, instructions,
  * tools) without baking them in at build time.
  */
-async function resolveLazy(value, ctx) {
+export async function resolveLazy(value, ctx) {
     if (typeof value !== 'function') {
         return value;
     }
@@ -411,6 +411,19 @@ async function collectSpawnItems({ layers, parentExecutionCtx, childExecutionCtx
     });
     return spawnResults.flatMap((r) => r.items);
 }
+/** Adds a spawned child's accumulated token/cost usage to its parent. */
+function rollUpSpawnUsage(parent, child) {
+    if (!isMutableContext(parent)) {
+        return;
+    }
+    parent.tokens.input += child.tokens.input;
+    parent.tokens.output += child.tokens.output;
+    parent.tokens.total += child.tokens.total;
+    if (child.tokens.cached !== undefined) {
+        parent.tokens.cached = (parent.tokens.cached ?? 0) + child.tokens.cached;
+    }
+    parent.cost += child.cost;
+}
 export async function executeSpawn(step, input, ctx, executeStep, opts) {
     const baseCtx = frameworkCast(ctx);
     const layers = resolveLayersForSpawn(step, opts?.parentLayers);
@@ -441,12 +454,20 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
             itemSchemas: opts?.itemSchemas,
         });
     }
-    // Build unified tool set for child from its step tree + layers
+    // Build unified tool set for child from its step tree + layers, plus the
+    // parent's unified tools. Sub-agents that read tools dynamically (via
+    // `ctx.unifiedTools`) otherwise lose the harness tool pool at the spawn
+    // boundary — a child whose `step.llm` resolves `tools` from context would
+    // see nothing. Inheriting the parent's tools keeps the harness toolset
+    // available across spawns; the child's own step/layer tools take precedence
+    // on name collision (dedup keeps the first occurrence), and children that
+    // need a restricted set filter explicitly.
     const childStepTools = collectAllTools(step.child);
     const childLayerTools = layers.length > 0 ? resolveLayerTools(layers, baseCtx.harness, baseCtx) : [];
     const childUnifiedTools = deduplicateTools([
         ...childStepTools,
         ...childLayerTools,
+        ...(baseCtx.unifiedTools ?? []),
     ]);
     // Create child context — empty by default, layers provide items via onSpawn.
     // `id: childId` keeps the ContextImpl's id in sync with the executionId
@@ -468,6 +489,12 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
     try {
         // Execute the child step
         const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
+        // Roll the child's token/cost usage up into the parent. A sub-agent's
+        // spend is the parent's spend; without this it would be stranded on the
+        // child context and invisible to `ctx.tokens` / `ctx.cost` / until.maxCost.
+        // Because every spawn boundary rolls up, nested sub-agents propagate to the
+        // root recursively.
+        rollUpSpawnUsage(baseCtx, childCtx);
         // Pipeline result through layer onReturn hooks
         if (!hasLayers || !parentExecutionCtx) {
             return childOutput;

package/dist/interpreter/execute-sub-harness.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SubHarness step handler: drives an external coding-agent harness
+ * (Claude Code, Codex, opencode, pi) for one agentic turn and folds its output
+ * back into the Noetic execution context — the harness analogue of
+ * `executeLLM`.
+ */
+import type { Context, StepSubHarness } from '@noetic-tools/types';
+export declare function executeSubHarness<TMemory, I, O>(step: StepSubHarness<TMemory, I, O>, input: I, ctx: Context<TMemory>): Promise<O>;

package/dist/interpreter/execute-sub-harness.js

@@ -0,0 +1,220 @@
+/**
+ * SubHarness step handler: drives an external coding-agent harness
+ * (Claude Code, Codex, opencode, pi) for one agentic turn and folds its output
+ * back into the Noetic execution context — the harness analogue of
+ * `executeLLM`.
+ */
+import { createMessage, extractAssistantText, frameworkCast, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
+import { ZodError } from 'zod';
+import { resolveLazy } from './execute-action.js';
+import { trackUsage } from './message-helpers.js';
+import { SubHarnessEventBridge } from './sub-harness-events.js';
+import { isFunctionCall, isMutableContext } from './typeguards.js';
+//#endregion
+//#region Helpers
+function sessionStore(ctx) {
+    return frameworkCast(ctx.harness).subHarnessSessions;
+}
+async function resolveSubHarness(step, ctx) {
+    const resolved = await resolveLazy(step.harness, ctx);
+    if (!resolved) {
+        throw new NoeticConfigError({
+            code: 'MISSING_SUB_HARNESS',
+            message: `step.${step.kind}(${JSON.stringify(step.id)}) resolved no harness adapter.`,
+            hint: 'Pass a harness factory result, e.g. harness: claudeCode({ model }).',
+        });
+    }
+    if (resolved.harnessId !== step.kind) {
+        throw new NoeticConfigError({
+            code: 'SUB_HARNESS_KIND_MISMATCH',
+            message: `step.${step.kind}(${JSON.stringify(step.id)}) was given a '${resolved.harnessId}' harness.`,
+            hint: `Use the matching builder for this adapter, e.g. step.${resolved.harnessId}({ ... }).`,
+        });
+    }
+    return resolved;
+}
+function resolveTurnText(resolvedPrompt, input) {
+    if (resolvedPrompt && resolvedPrompt.length > 0) {
+        return resolvedPrompt;
+    }
+    return typeof input === 'string' ? input : '';
+}
+function buildRunContext(ctx) {
+    return {
+        cwd: ctx.cwdState.cwd,
+        fs: ctx.fs,
+        shell: ctx.shell,
+        subprocess: ctx.subprocess,
+        threadId: ctx.threadId,
+    };
+}
+function toLlmResponse(result) {
+    const usage = result.usage;
+    return {
+        items: result.items,
+        usage: {
+            inputTokens: usage?.input ?? 0,
+            outputTokens: usage?.output ?? 0,
+            cachedTokens: usage?.cached,
+        },
+        cost: result.cost,
+    };
+}
+function applyTurnResult(ctx, result) {
+    const toolCalls = [];
+    for (const item of result.items) {
+        ctx.itemLog.append(item);
+        if (isFunctionCall(item)) {
+            toolCalls.push(item);
+        }
+    }
+    const llmResponse = toLlmResponse(result);
+    trackUsage(ctx, llmResponse);
+    const meta = {
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        usage: result.usage ? llmResponse.usage : undefined,
+        cost: result.cost,
+        responseItems: result.items,
+    };
+    if (isMutableContext(ctx)) {
+        ctx.lastStepMeta = meta;
+    }
+}
+async function teardownSession(session, mode) {
+    if (mode === 'detach' && session.doDetach) {
+        await session.doDetach();
+        return;
+    }
+    if (mode === 'destroy' && session.doDestroy) {
+        await session.doDestroy();
+        return;
+    }
+    await session.doStop();
+}
+async function startOrReuseSession(step, harness, ctx, baseCtx, history) {
+    const reuseKey = step.session?.reuse;
+    const store = sessionStore(baseCtx);
+    if (reuseKey) {
+        const existing = store.get(reuseKey);
+        if (existing) {
+            return {
+                session: existing,
+                reuseKey,
+            };
+        }
+    }
+    const session = await harness.doStart({
+        settings: step.settings,
+        instructions: await resolveLazy(step.instructions, ctx),
+        history,
+        ctx: buildRunContext(baseCtx),
+    });
+    if (reuseKey) {
+        store.set(reuseKey, session);
+    }
+    return {
+        session,
+        reuseKey,
+    };
+}
+/**
+ * Tear the session down per policy after a successful turn. Reused sessions
+ * stay alive by default; an explicit `onComplete` overrides that.
+ */
+async function finalizeSession(resolution, policy, baseCtx) {
+    const { session, reuseKey } = resolution;
+    if (!reuseKey) {
+        await teardownSession(session, policy?.onComplete ?? 'stop');
+        return;
+    }
+    const mode = policy?.onComplete;
+    if (mode === 'stop' || mode === 'destroy') {
+        await teardownSession(session, mode);
+        sessionStore(baseCtx).delete(reuseKey);
+        return;
+    }
+    if (mode === 'detach') {
+        await teardownSession(session, 'detach');
+    }
+    // Default for a reused session: keep it alive in the store.
+}
+//#endregion
+//#region Public API
+export async function executeSubHarness(step, input, ctx) {
+    const baseCtx = frameworkCast(ctx);
+    const harness = await resolveSubHarness(step, ctx);
+    const resolvedPrompt = await resolveLazy(step.prompt, ctx);
+    const turnText = resolveTurnText(resolvedPrompt, input);
+    if (turnText.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'MISSING_PROMPT',
+            message: `step.${step.kind}(${JSON.stringify(step.id)}) resolved an empty prompt.`,
+            hint: 'Provide a non-empty `prompt`, or pass a string input to the step.',
+        });
+    }
+    // Capture the conversation so far (from earlier LLM/sub-harness steps and
+    // turns) BEFORE appending this turn's prompt, so a fresh session is seeded
+    // with full context of the conversation.
+    const priorHistory = [
+        ...baseCtx.itemLog.items,
+    ];
+    baseCtx.itemLog.append(createMessage(turnText, 'user'));
+    const resolution = await startOrReuseSession(step, harness, ctx, baseCtx, priorHistory);
+    const bridge = new SubHarnessEventBridge(step, baseCtx);
+    bridge.begin();
+    let result;
+    try {
+        result = await resolution.session.doPromptTurn({
+            prompt: turnText,
+            emit: (part) => bridge.forward(part),
+        });
+    }
+    catch (e) {
+        // Best-effort teardown of a fresh session before surfacing the failure;
+        // reused sessions are left intact for a later step to retry against.
+        if (!resolution.reuseKey) {
+            await teardownSession(resolution.session, 'destroy').catch(() => undefined);
+        }
+        if (e instanceof NoeticErrorImpl) {
+            throw e;
+        }
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: step.id,
+            cause: e instanceof Error ? e : new Error(String(e)),
+            retriesExhausted: false,
+        });
+    }
+    bridge.finalize(result);
+    applyTurnResult(baseCtx, result);
+    await finalizeSession(resolution, step.session, baseCtx);
+    const lastText = result.text.length > 0 ? result.text : extractAssistantText(result.items);
+    if (step.output) {
+        try {
+            const parsed = JSON.parse(lastText);
+            return step.output.parse(parsed);
+        }
+        catch (e) {
+            if (e instanceof SyntaxError || e instanceof ZodError) {
+                throw new NoeticErrorImpl({
+                    kind: 'llm_parse_error',
+                    stepId: step.id,
+                    raw: lastText,
+                    schema: step.output,
+                    zodError: e instanceof ZodError
+                        ? e
+                        : new ZodError([
+                            {
+                                code: 'custom',
+                                message: `Invalid JSON: ${e.message}`,
+                                path: [],
+                            },
+                        ]),
+                });
+            }
+            throw e;
+        }
+    }
+    return frameworkCast(lastText);
+}
+//#endregion