@noetic-tools/core 5.4.0 → 5.4.1

package/dist/builders/acp-agent-tool.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Exposes an ACP coding agent as a `Tool`, so a `callModel` step can delegate
+ * work to it by calling it.
+ *
+ * `step.acpAgent` puts the agent in the step tree, where the *author* decides
+ * when it runs. This puts it in the model's hands instead: the model decides
+ * that a task wants a coding agent and calls the tool, the same way it would
+ * call any other. Everything else — permissions, session policy, the event
+ * bridge, usage accounting — is identical, because the tool runs the very same
+ * step underneath.
+ */
+import type { AcpAgent, AcpClientCapabilityConfig, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Tool } from '@noetic-tools/types';
+import { z } from 'zod';
+/** @public Options for {@link acpAgentTool}. */
+export interface AcpAgentToolOptions {
+    /** The ACP agent adapter to delegate to, e.g. `claudeCode()`. */
+    agent: AcpAgent;
+    /**
+     * Tool name the model calls. Defaults to `delegate_to_<agentId>` with
+     * non-identifier characters replaced, e.g. `delegate_to_claude_code`.
+     */
+    name?: string;
+    /**
+     * What the model is told the tool does. Defaults to a generic description —
+     * override it to steer *when* the model delegates, which matters far more
+     * than the default wording.
+     */
+    description?: string;
+    /** Working directory for the agent's session. Defaults to the runtime cwd. */
+    cwd?: string;
+    /** Session mode to switch to before each delegated turn. */
+    mode?: string;
+    /** Model to select before each delegated turn. */
+    model?: string;
+    /** MCP servers to expose to the agent. */
+    mcpServers?: ReadonlyArray<AcpMcpServer>;
+    /** Declarative answer to the agent's permission requests. Defaults to denying. */
+    permissions?: AcpPermissionPolicy;
+    /** Async resolver consulted when policy and steering both abstain. */
+    onPermissionRequest?: AcpPermissionHandler;
+    /** Which client capabilities to advertise to the agent. */
+    clientCapabilities?: AcpClientCapabilityConfig;
+    /**
+     * Session policy for the delegated turns. Give it a `reuse` key with
+     * `keepAlive: 'run'` (or `'harness'`) to let the model hold a *conversation*
+     * with the agent across several tool calls instead of starting cold each
+     * time — usually what you want, since the second call almost always builds
+     * on the first.
+     */
+    session?: AcpSessionPolicy;
+}
+declare const AcpAgentToolInputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+}, z.core.$strip>;
+declare const AcpAgentToolOutputSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Build a {@link Tool} that hands a prompt to an ACP coding agent.
+ *
+ * @public
+ * @param opts.agent - The agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
+ * @returns A `Tool` accepting `{ prompt }` and returning `{ text }`.
+ * @throws `NoeticConfigError` `MISSING_ACP_AGENT` when no adapter is given.
+ */
+export declare function acpAgentTool(opts: AcpAgentToolOptions): Tool<typeof AcpAgentToolInputSchema, typeof AcpAgentToolOutputSchema>;
+export {};

package/dist/builders/acp-agent-tool.js

@@ -0,0 +1,87 @@
+/**
+ * Exposes an ACP coding agent as a `Tool`, so a `callModel` step can delegate
+ * work to it by calling it.
+ *
+ * `step.acpAgent` puts the agent in the step tree, where the *author* decides
+ * when it runs. This puts it in the model's hands instead: the model decides
+ * that a task wants a coding agent and calls the tool, the same way it would
+ * call any other. Everything else — permissions, session policy, the event
+ * bridge, usage accounting — is identical, because the tool runs the very same
+ * step underneath.
+ */
+import { NoeticConfigError } from '@noetic-tools/types';
+import { z } from 'zod';
+import { step } from './step-builders.js';
+import { tool } from './tool-builder.js';
+const AcpAgentToolInputSchema = z.object({
+    prompt: z.string().min(1).describe('What the coding agent should do, in plain language.'),
+});
+const AcpAgentToolOutputSchema = z.object({
+    text: z.string().describe("The coding agent's final response."),
+});
+//#endregion
+//#region Helpers
+/** `claude-code` → `delegate_to_claude_code`. */
+function defaultToolName(agentId) {
+    return `delegate_to_${agentId.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+}
+function defaultDescription(agentId) {
+    return [
+        `Delegate a coding task to the ${agentId} agent, which works directly in the workspace.`,
+        'Give it a complete, self-contained instruction — it does not see this conversation.',
+        'Prefer it for multi-file edits, running builds or tests, and exploring an unfamiliar codebase.',
+    ].join(' ');
+}
+//#endregion
+//#region Public API
+/**
+ * Build a {@link Tool} that hands a prompt to an ACP coding agent.
+ *
+ * @public
+ * @param opts.agent - The agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
+ * @returns A `Tool` accepting `{ prompt }` and returning `{ text }`.
+ * @throws `NoeticConfigError` `MISSING_ACP_AGENT` when no adapter is given.
+ */
+export function acpAgentTool(opts) {
+    if (!opts.agent) {
+        throw new NoeticConfigError({
+            code: 'MISSING_ACP_AGENT',
+            message: 'acpAgentTool() requires an agent adapter.',
+            hint: 'Pass an agent factory result, e.g. agent: claudeCode() from @noetic-tools/acp.',
+        });
+    }
+    const name = opts.name ?? defaultToolName(opts.agent.agentId);
+    // Built once, not per call: `step.acpAgent` registers itself in the step
+    // registry, so constructing one per invocation would fill the registry with
+    // duplicate ids. An empty `prompt` means "use the step's runtime input",
+    // which is exactly the tool's argument.
+    const delegated = step.acpAgent({
+        id: `${name}:step`,
+        agent: opts.agent,
+        prompt: '',
+        cwd: opts.cwd,
+        mode: opts.mode,
+        model: opts.model,
+        mcpServers: opts.mcpServers,
+        permissions: opts.permissions,
+        onPermissionRequest: opts.onPermissionRequest,
+        clientCapabilities: opts.clientCapabilities,
+        session: opts.session,
+    });
+    return tool({
+        name,
+        description: opts.description ?? defaultDescription(opts.agent.agentId),
+        input: AcpAgentToolInputSchema,
+        output: AcpAgentToolOutputSchema,
+        async execute(args, toolCtx) {
+            // Running through the harness on the tool's own context means the
+            // delegated turn lands in the same item log, usage totals, and event
+            // stream as any other step — it is a real step, not a side channel.
+            const text = await toolCtx.harness.run(delegated, args.prompt, toolCtx.ctx);
+            return {
+                text,
+            };
+        },
+    });
+}
+//#endregion

package/dist/builders/dynamic-workflow.js

@@ -32,11 +32,11 @@ A WorkflowNode is one of:
 - { "kind": "withContext", "id": "<unique>", "child": <WorkflowNode>, "layers": ["<layer-name>", ...] } (run the child with named context layers; only emit if the task names layers that exist, since this planner provides no layer registry and unknown names resolve to NO layers)
 - { "kind": "schedule", "id": "<unique>", "step": <WorkflowNode>, "interval": <ms>, "onError": "continue"|"fail" } (re-runs the step forever on an interval and never returns — only emit for an explicitly daemon-style task)
 - { "kind": "subflow", "id": "<unique>", "document": { "version": 1, "root": <WorkflowNode> } } (an inline sub-workflow run as one step; only emit the inline form — named refs require a registry this planner does not provide)
-- { "kind": "claude-code"|"codex"|"opencode"|"pi", "id": "<unique>", "prompt": "<turn prompt>", "settings": { "model": "<optional>", "permissionMode": "<optional>" } }
+- { "kind": "acp-agent", "id": "<unique>", "agent": "<registered agent id, e.g. claude-code>", "prompt": "<turn prompt>", "mode": "<optional session mode>", "model": "<optional>" }
 
 Every entry of a callModel node's "tools" is an OBJECT, never a bare string. Use { "type": "<tool-name>" } to let the model call one of the tools listed below. Two provider-executed tools are also available without being listed: { "type": "openrouter:web_search" } and { "type": "openrouter:web_fetch" }, each accepting an optional "parameters" object.
 
-SubHarness nodes (claude-code, codex, opencode, pi) delegate a turn to an external coding agent; only emit one if a matching harness adapter is registered for the workflow.
+An acp-agent node delegates a turn to an external coding agent over the Agent Client Protocol; only emit one if a matching agent adapter is registered for the workflow.
 
 An UntilPredicate (the "until" field of a loop) is one of:
 { "kind": "maxSteps", "n": <positive int> }, { "kind": "maxCost", "usd": <positive number> }, { "kind": "maxDuration", "duration": <ms> }, { "kind": "noToolCalls" }, { "kind": "never" } (never stops — pair with "maxIterations"), { "kind": "outputContains", "marker": "<text>" }, { "kind": "outputEquals", "sentinel": "<text>" }, { "kind": "converged", "threshold": <optional 0-1> }, { "kind": "any", "predicates": [<UntilPredicate>, ...] }, { "kind": "all", "predicates": [<UntilPredicate>, ...] }.

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

@@ -1,5 +1,5 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepCallModel, StepInvokeTool, StepRunCode, StepSubHarness, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepAcpAgent, StepCallModel, StepInvokeTool, StepRunCode, SubprocessAdapter, Tool } from '@noetic-tools/types';
 export interface RunCodeOpts<TContext, I, O> {
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
@@ -38,20 +38,36 @@ export interface InvokeToolOpts<I, O> {
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
-export interface StepSubHarnessOpts<TContext, O> {
+export interface StepAcpAgentOpts<TContext, O> {
     id: string;
-    /** The harness adapter created by a `@noetic-tools/sub-harness-*` factory. Eager or `(ctx) => SubHarness`. */
-    harness: Lazy<SubHarness, TContext>;
-    /** Turn prompt. Eager string or `(ctx) => string` getter. */
-    prompt: Lazy<string, TContext>;
-    /** Shared harness settings (model, permission mode, …). */
-    settings?: SubHarnessSettings;
-    /** System instructions applied on the first message of a fresh session. */
-    instructions?: Lazy<string | undefined, TContext>;
+    /** An ACP agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`. Eager or `(ctx) => AcpAgent`. */
+    agent: Lazy<AcpAgent, TContext>;
+    /** Turn prompt as plain text. Eager string or `(ctx) => string` getter. */
+    prompt?: Lazy<string, TContext>;
+    /**
+     * Full ACP prompt content — images, audio, resource links, embedded context.
+     * Appended after `prompt`. Rejected before the turn is sent when the agent
+     * did not advertise the matching prompt capability.
+     */
+    content?: Lazy<ReadonlyArray<AcpContentBlock> | undefined, TContext>;
+    /** MCP servers to expose to the agent for this session. */
+    mcpServers?: Lazy<ReadonlyArray<AcpMcpServer> | undefined, TContext>;
+    /** Working directory for the session. Defaults to `ctx.cwdState.cwd`. */
+    cwd?: Lazy<string | undefined, TContext>;
+    /** Session mode to switch to before prompting (e.g. `'plan'`). */
+    mode?: Lazy<string | undefined, TContext>;
+    /** Model to select before prompting, for agents that expose model selection. */
+    model?: Lazy<string | undefined, TContext>;
+    /** Declarative answer to the agent's permission requests. Defaults to denying. */
+    permissions?: AcpPermissionPolicy;
+    /** Async resolver consulted when the policy and steering both abstain. */
+    onPermissionRequest?: AcpPermissionHandler;
+    /** Which client capabilities to advertise to the agent. */
+    clientCapabilities?: AcpClientCapabilityConfig;
     /** Optional Standard Schema; when set the assistant text is JSON-parsed and validated. */
     output?: StandardSchemaV1<unknown, O>;
     /** Session reuse + teardown policy across steps. */
-    session?: SubHarnessSessionPolicy;
+    session?: AcpSessionPolicy;
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
 /**
@@ -100,45 +116,29 @@ export declare function callModel<TContext = ContextData, I = unknown, O = unkno
  */
 export declare function invokeTool<TContext = ContextData, I = unknown, O = unknown>(opts: InvokeToolOpts<I, O>): StepInvokeTool<TContext, I, O>;
 /**
- * The sub-harness step builder namespace. Unlike the flattened base builders
- * (`runCode`, `callModel`, `invokeTool`), the coding-agent harness builders
- * stay grouped under `step` — their `step.<harness>()` API is unchanged.
+ * The ACP step builder namespace. Unlike the flattened base builders
+ * (`runCode`, `callModel`, `invokeTool`), the coding-agent builder stays
+ * grouped under `step`.
  *
  * @public
  */
 export declare const step: {
     /**
-     * Creates a step that delegates a turn to the Claude Code harness.
+     * Creates a step that delegates a turn to an external coding agent over the
+     * Agent Client Protocol.
+     *
+     * One builder covers every ACP-speaking agent: the agent itself is supplied
+     * as an adapter, so adding an agent never changes this API or the published
+     * workflow schema.
      *
      * @public
      * @param opts.id - Unique step identifier.
-     * @param opts.harness - A `claudeCode(...)` adapter from `@noetic-tools/sub-harness-claude-code`.
+     * @param opts.agent - An agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
      * @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<TContext = ContextData, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TContext, O>): StepSubHarness<TContext, 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<TContext = ContextData, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TContext, O>): StepSubHarness<TContext, 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<TContext = ContextData, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TContext, O>): StepSubHarness<TContext, 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`.
+     * @param opts.permissions - Declarative policy answering the agent's permission requests.
+     * @param opts.output - Optional Standard Schema enabling structured output parsing.
+     * @returns A `StepAcpAgent`, auto-registered in the step registry.
+     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_ACP_AGENT` / `MISSING_PROMPT`.
      */
-    pi<TContext = ContextData, I = unknown, O = unknown>(opts: StepSubHarnessOpts<TContext, O>): StepSubHarness<TContext, I, O>;
+    acpAgent<TContext = ContextData, I = unknown, O = unknown>(opts: StepAcpAgentOpts<TContext, O>): StepAcpAgent<TContext, I, O>;
 };

package/dist/builders/step-builders.js

@@ -1,43 +1,35 @@
 import { NoeticConfigError } from '@noetic-tools/types';
 import { getDefaultRegistrar } from '../types/step-registrar.js';
 //#endregion
-//#region SubHarness builder helper
+//#region ACP agent 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.
+ * Validation shared by `step.acpAgent`. Kept separate from the builder so the
+ * checks stay readable and the builder stays a one-liner.
  */
-function buildSubHarnessStep(kind, builderName, opts) {
+function validateAcpAgentOpts(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", ... }).`,
+            message: 'step.acpAgent() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. step.acpAgent({ id: "review", ... }).',
         });
     }
-    if (!opts.harness) {
+    if (!opts.agent) {
         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 }).`,
+            code: 'MISSING_ACP_AGENT',
+            message: 'step.acpAgent() requires an agent adapter.',
+            hint: 'Pass an agent factory result, e.g. agent: claudeCode() from @noetic-tools/acp.',
         });
     }
-    // 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) {
+    // Presence, not emptiness: an empty `prompt` is a valid way to say "use the
+    // step's runtime input as the prompt", which the handler supports.
+    if (opts.prompt === undefined && opts.content === undefined) {
         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}({ ... }).`,
+            code: 'MISSING_PROMPT',
+            message: 'step.acpAgent() requires a prompt or content blocks.',
+            hint: 'Pass `prompt` for plain text, or `content` for image/audio/resource blocks.',
         });
     }
-    const built = {
-        kind,
-        ...opts,
-    };
-    getDefaultRegistrar().register(built);
-    return built;
 }
 //#endregion
 //#region Builders
@@ -153,54 +145,38 @@ export function invokeTool(opts) {
     return built;
 }
 /**
- * The sub-harness step builder namespace. Unlike the flattened base builders
- * (`runCode`, `callModel`, `invokeTool`), the coding-agent harness builders
- * stay grouped under `step` — their `step.<harness>()` API is unchanged.
+ * The ACP step builder namespace. Unlike the flattened base builders
+ * (`runCode`, `callModel`, `invokeTool`), the coding-agent builder stays
+ * grouped under `step`.
  *
  * @public
  */
 export const step = {
     /**
-     * Creates a step that delegates a turn to the Claude Code harness.
+     * Creates a step that delegates a turn to an external coding agent over the
+     * Agent Client Protocol.
+     *
+     * One builder covers every ACP-speaking agent: the agent itself is supplied
+     * as an adapter, so adding an agent never changes this API or the published
+     * workflow schema.
      *
      * @public
      * @param opts.id - Unique step identifier.
-     * @param opts.harness - A `claudeCode(...)` adapter from `@noetic-tools/sub-harness-claude-code`.
+     * @param opts.agent - An agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
      * @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`.
+     * @param opts.permissions - Declarative policy answering the agent's permission requests.
+     * @param opts.output - Optional Standard Schema enabling structured output parsing.
+     * @returns A `StepAcpAgent`, auto-registered in the step registry.
+     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_ACP_AGENT` / `MISSING_PROMPT`.
      */
-    pi(opts) {
-        return buildSubHarnessStep('pi', 'step.pi', opts);
+    acpAgent(opts) {
+        validateAcpAgentOpts(opts);
+        const built = {
+            kind: 'acp-agent',
+            ...opts,
+        };
+        getDefaultRegistrar().register(built);
+        return built;
     },
 };
 //#endregion

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

@@ -6,20 +6,24 @@
  * ones — they register in the step registry, carry retry policies, etc.
  */
 import type { ContextData, ContextLayer } from '@noetic-tools/context';
-import type { ExecuteStepFn, OutputCodec, Step, SubHarness, SubHarnessKind, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { AcpAgent, ExecuteStepFn, OutputCodec, Step, SubprocessAdapter, 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, ContextLayer>;
-    /** SubHarness adapters keyed by harness id, resolving `claude-code`/`codex`/… nodes. */
-    subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
+    /**
+     * ACP agent adapters keyed by `agentId`, resolving an `acp-agent` node's
+     * `agent` field. An OPEN registry — supporting a new agent needs no schema
+     * change, only another entry here.
+     */
+    acpAgents?: ReadonlyMap<string, AcpAgent>;
     /**
      * Output codecs keyed by the `library` ref a `callModel` node's `output` codec
      * reference names — the live codec built from a component library, e.g.
      * `new Map([['dashboard-lib', openUi(dashboardLibrary)]])` from
-     * `@noetic-tools/openui`. Resolved the same way sub-harness adapters are.
+     * `@noetic-tools/openui`. Resolved the same way ACP agent adapters are.
      */
     uiLibraries?: ReadonlyMap<string, OutputCodec>;
     /**

package/dist/builders/workflow-hydrator.js

@@ -374,33 +374,28 @@ function hydrateScheduleNode(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') {
+function hydrateAcpAgentNode(node, ctx) {
+    if (node.kind !== 'acp-agent') {
         return frameworkCast(undefined);
     }
-    const harness = ctx.subHarnesses?.get(node.kind);
-    if (!harness) {
+    const agent = ctx.acpAgents?.get(node.agent);
+    if (!agent) {
         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 })]]).`,
+            code: 'UNKNOWN_ACP_AGENT_REFERENCE',
+            message: `ACP agent '${node.agent}' referenced in workflow node '${node.id}' is not registered.`,
+            hint: 'Pass agent adapters via HydrationContext.acpAgents, e.g. createAcpAgentRegistry(claudeCode()) from @noetic-tools/acp.',
         });
     }
-    return SUB_HARNESS_BUILDERS[node.kind]({
+    return step.acpAgent({
         id: node.id,
-        harness,
+        agent,
         prompt: node.prompt,
-        instructions: node.instructions,
-        settings: node.settings,
+        cwd: node.cwd,
+        mode: node.mode,
+        model: node.model,
+        mcpServers: node.mcpServers,
+        permissions: node.permissions,
+        clientCapabilities: node.clientCapabilities,
         session: node.session,
     });
 }
@@ -487,10 +482,7 @@ const NODE_HYDRATORS = {
     sequence: hydrateSequenceNode,
     schedule: hydrateScheduleNode,
     subflow: hydrateSubflowNode,
-    'claude-code': hydrateSubHarnessNode,
-    codex: hydrateSubHarnessNode,
-    opencode: hydrateSubHarnessNode,
-    pi: hydrateSubHarnessNode,
+    'acp-agent': hydrateAcpAgentNode,
 };
 //#endregion
 //#region Helpers

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

@@ -6,7 +6,7 @@
  * import cycle.
  */
 import type { ContextData, ContextLayer } from '@noetic-tools/context';
-import type { OutputCodec, StepRunCode, SubHarness, SubHarnessKind, SubprocessAdapter, Tool, WorkflowDocument } from '@noetic-tools/types';
+import type { AcpAgent, OutputCodec, StepRunCode, SubprocessAdapter, Tool, WorkflowDocument } from '@noetic-tools/types';
 /** @public Options for `workflow`. */
 export interface WorkflowOpts {
     id: string;
@@ -20,8 +20,8 @@ export interface WorkflowOpts {
     layers?: ReadonlyMap<string, ContextLayer>;
     /** Named sub-workflows for `subflow` nodes — and for resolving `ref` itself. */
     workflows?: ReadonlyMap<string, WorkflowDocument>;
-    /** SubHarness adapters for `claude-code`/`codex`/`opencode`/`pi` nodes. */
-    subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
+    /** ACP agent adapters, keyed by `agentId`, for `acp-agent` nodes. */
+    acpAgents?: ReadonlyMap<string, AcpAgent>;
     /** Output codecs for `callModel` nodes' `output` codec references. */
     uiLibraries?: ReadonlyMap<string, OutputCodec>;
     /** Resolver for named subprocess adapters on `runCode` nodes. */

package/dist/builders/workflow-step.js

@@ -91,7 +91,7 @@ function hydrate(opts, executeStep) {
         executeStep,
         layers: opts.layers,
         workflows: opts.workflows,
-        subHarnesses: opts.subHarnesses,
+        acpAgents: opts.acpAgents,
         uiLibraries: opts.uiLibraries,
         resolveSubprocess: opts.resolveSubprocess,
         subflowAncestry: opts.ref

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

@@ -1,8 +1,9 @@
 import { ItemSchemaRegistry } from '@noetic-tools/types';
+import { AcpSessionStore } from '../runtime/acp-session-store.js';
 import type { LayerStateStore, RecallCache } from './deps/context.js';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
-import type { AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubHarnessSession, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
+import type { AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 /**
  * Storage-scoped environment configuration for `AgentHarness`.
@@ -160,12 +161,40 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private readonly defaultDeliveryMode;
     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.
+     * @internal Live ACP connections. Reached by the interpreter via
+     * `frameworkCast`; use {@link listAcpSessions}, {@link getAcpSession},
+     * {@link cancelAcpSession}, and {@link closeAcpSessions} from outside core.
      */
-    readonly subHarnessSessions: Map<string, SubHarnessSession>;
+    readonly acpSessions: AcpSessionStore;
+    /**
+     * Snapshot of every live ACP sub-agent, for a UI that wants to show what is
+     * running and let a user act on it. Read-only: a session's turns are driven
+     * by steps, so nothing here can start work behind the runtime's back.
+     * @public
+     */
+    listAcpSessions(): AcpSessionInfo[];
+    /**
+     * The live connection + session behind a handle from {@link listAcpSessions}
+     * (or a step's `session.reuse` key), or `undefined` when nothing matches.
+     * @public
+     */
+    getAcpSession(key: string): AcpLiveSession | undefined;
+    /**
+     * Interrupt whatever the sub-agent under `key` is doing, via `session/cancel`.
+     * The connection stays open and the turn still returns — with the `cancelled`
+     * stop reason, which the running step surfaces as a `cancelled` error.
+     * Returns false when nothing matches the key.
+     * @public
+     */
+    cancelAcpSession(key: string): Promise<boolean>;
+    /**
+     * Close every ACP connection this harness still holds, whatever its
+     * keep-alive scope. A connection owns a live agent — usually a child process
+     * whose stdio keeps the event loop alive — so a `keepAlive: 'harness'`
+     * session must be closed by its owner or the host will not exit. Idempotent.
+     * @public
+     */
+    closeAcpSessions(): Promise<void>;
     readonly layerStateStore: LayerStateStore;
     /** Per-harness memoization cache for `recallMode: 'eventual'` layers. */
     readonly recallCache: RecallCache;
@@ -346,7 +375,7 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      *
      * Aborting a context rejects everything blocked on it (channel `recv`
      * waiters, parked senders) with `{ kind: 'cancelled' }`, stops its in-flight
-     * model call and sub-harness turn, and makes the next step boundary throw
+     * model call and ACP agent turn, and makes the next step boundary throw
      * `cancelled`.
      *
      * Cancellation is cooperative: a layer hook already in flight is allowed to