@automatalabs/acp-agents 0.7.0 → 0.9.0

package/README.md

@@ -45,7 +45,18 @@ try {
 }
 ```
 
-`run()` accepts the full `RunOptions` seam: `schema`, `model`, `tier`, `cwd`, `instructions`, `label`, `signal` (cancellation), `toolNames` / `disallowedToolNames`, `mcpServers`, `runId`, `baseInstructions` / `developerInstructions` (Codex-only, see below), `onUsage`, `onModelResolved`, `onModelFallback`, and `onHistory`. See `@automatalabs/shared-types` for the field-by-field contract.
+`run()` accepts the full `RunOptions` seam: `schema`, `model`, `tier`, `cwd`, `instructions`, `label`, `signal` (cancellation), `toolNames` / `disallowedToolNames`, `mcpServers`, `images` (see below), `runId`, `baseInstructions` / `developerInstructions` (Codex-only, see below), `onUsage`, `onModelResolved`, `onModelFallback`, and `onHistory`. See `@automatalabs/shared-types` for the field-by-field contract.
+
+### Image attachments (`images`)
+
+`images` appends base64 image `ContentBlock`s to the first prompt turn. The client adapts content to what the connected agent advertised at `initialize`: when the agent does not advertise `promptCapabilities.image`, each attachment degrades to a bracketed text note naming the mime type (never an error, never silently dropped). Repair/re-prompt turns stay text-only.
+
+```ts
+await runner.run("What's in this screenshot?", {
+  cwd: "/abs/path/to/worktree",
+  images: [{ data: base64Png, mimeType: "image/png" }],
+});
+```
 
 ### Codex session instructions (`baseInstructions` / `developerInstructions`)
 
@@ -65,9 +76,64 @@ await runner.run("Cut the release.", {
 });
 ```
 
+## Client-side fs / terminal handlers (`clientHandlers`)
+
+By default the agent uses its **own** built-in file and exec tools — the client never sees those operations. Register `clientHandlers` to interpose: the client then advertises exactly what you registered at `initialize` (`fs.readTextFile` / `fs.writeTextFile` per-method; `terminal` only when **all five** terminal methods are provided) and routes the agent's `fs/*` and `terminal/*` requests to your handlers. Every handler receives the request params plus an `AcpSessionContext` — `sessionId`, the session's **own** `cwd`, `label`, `runId` — so a pooled process serving many sessions still gets per-session isolation.
+
+**Confinement is your job.** The library routes requests and supplies the session context; enforcing worktree roots, resolving symlinks, scoping environment variables, bounding output, and applying timeouts belongs in your handler implementation. Requests for methods you did not register are rejected with a JSON-RPC method-not-found error (agents that respect the advertisement never send them).
+
+```ts
+const runner = createAcpRunner({
+  clientHandlers: {
+    fs: {
+      readTextFile: async ({ path }, { cwd }) => ({ content: await confinedRead(cwd, path) }),
+      writeTextFile: async ({ path, content }, { cwd }) => { await confinedWrite(cwd, path, content); },
+    },
+    // terminal: { createTerminal, terminalOutput, waitForTerminalExit, killTerminal, releaseTerminal },
+  },
+});
+```
+
+## Interactive sessions
+
+Use `runner.openSession(options)` when a host needs to hold one ACP session open across multiple prompt turns. It uses the same backend selection and session/new inputs as `run()` (`model` / `tier`, absolute `cwd`, tool policy, `mcpServers`, `meta`, `runId`, Codex instruction overrides), but it spawns a **dedicated** agent process for that session instead of borrowing from the pool. A long-lived interactive session therefore never starves `run()` calls on the same backend, even with the default pool size of one.
+
+Prompt turns are explicit and serialized: call `prompt(content, { images?, promptMeta? })`, await the returned `{ stopReason, text }`, then send the next turn. A second `prompt()` while one is in flight rejects with a host-side error; queue turns in your host if you want queued UX. `text` is only the assistant text from that turn. Per-turn `images` use the same ACP image block path as `run()` and still degrade through capability negotiation when the agent does not advertise image prompts.
+
+`cancel()` sends ACP `session/cancel` for the active turn. `release()` is idempotent: it best-effort closes the ACP session and then disposes the dedicated process. Passing `signal` to `openSession()` releases the session on abort, and `runner.dispose()` releases any still-open interactive sessions before closing the pooled processes. Dedicated process death is observed per session: the wrapper auto-releases, session-scoped listeners see `session_close`, and an in-flight prompt rejects through the normal connection-closed path. `backend_error` is connection-scoped observability on the runner bus only; it is not delivered through `session.on()`.
+
+```ts
+const runner = createAcpRunner();
+
+try {
+  const session = await runner.openSession({
+    model: "anthropic/claude-sonnet-4",
+    cwd: "/abs/path/to/worktree",
+    onPermissionRequest: async (request) => choosePermission(request),
+  });
+
+  const off = session.on("agent_message_chunk", (e) => {
+    if (e.content.type === "text") process.stdout.write(e.content.text);
+  });
+
+  try {
+    const first = await session.prompt("Inspect the failing test.");
+    const second = await session.prompt("Patch the smallest fix.", {
+      images: [{ data: base64Png, mimeType: "image/png" }],
+    });
+    console.log(first.stopReason, second.text);
+  } finally {
+    off();
+    await session.release();
+  }
+} finally {
+  await runner.dispose();
+}
+```
+
 ## Listening in: live ACP events
 
-`AcpAgentRunner` is also a typed event bus — `runner.on(name, listener)` bubbles up the live ACP stream of every run (streaming text, tool calls, usage, permissions). Event names are the ACP `sessionUpdate` discriminants (`agent_message_chunk`, `tool_call`, `usage_update`, …) plus the cross-cutting `session_update` (catch-all), `permission_request`, `raw_message`, `session_open` / `session_close`, and `backend_error`. Each payload carries a `{ sessionId, backendId, label?, runId? }` context envelope (a pooled runner multiplexes many runs at once). `on()` / `once()` return an unsubscribe thunk; `off()` and `removeAllListeners()` round it out. Listeners are best-effort observers — a throwing listener never affects the run.
+`AcpAgentRunner` is also a typed event bus — `runner.on(name, listener)` bubbles up the live ACP stream of every run (streaming text, tool calls, usage, permissions). Event names are the ACP `sessionUpdate` discriminants (`agent_message_chunk`, `tool_call`, `usage_update`, …) plus the cross-cutting `session_update` (catch-all), `permission_pending`, `permission_request`, `raw_message`, `session_open` / `session_close`, and `backend_error`. Each payload carries a `{ sessionId, backendId, label?, runId? }` context envelope (a pooled runner multiplexes many runs at once). `permission_pending` is resolver-only and carries `{ request }` before the host resolver is invoked; `permission_request` fires exactly once with the final `{ request, outcome }` returned to the agent. `on()` / `once()` return an unsubscribe thunk; `off()` and `removeAllListeners()` round it out. Listeners are best-effort observers — a throwing listener never affects the run.
 
 ```ts
 const off = runner.on("agent_message_chunk", (e) => {
@@ -85,20 +151,24 @@ The full event map (`AcpRunnerEventMap`) and helpers (`TypedEventEmitter`) are e
 From [`src/index.ts`](./src/index.ts):
 
 - **`createAcpRunner(options?)`** — factory returning an `AcpAgentRunner` (this is what `@automatalabs/workflows` injects into the engine).
-- **`AcpAgentRunner`** — the `AgentRunner` implementation; `run(prompt, options)` and `dispose()`.
+- **`AcpAgentRunner`** — the `AgentRunner` implementation; `run(prompt, options)`, `openSession(options)`, and `dispose()`.
+- **`InteractiveSession` / `InteractiveSessionOptions` / `InteractiveTurn`** — the held-open multi-turn session surface returned by `openSession()`.
 - **`selectBackend({ model, tier }, registry?)`** — the cross-provider routing rule: which backend a spec maps to (registered custom names match first, exact or `name/<inner-model>`).
 - **`ClaudeBackend` / `CodexBackend`** — the two built-in backend strategies (spawn config + per-backend schema wiring).
-- **`CustomAcpBackend` / `resolveBackendRegistry` / `BACKENDS_ENV`** — the custom-backend registry: run **any** ACP agent as a named backend via `createAcpRunner({ backends: { name: { command, args?, env?, sessionMeta? } } })` or the `AGENTPRISM_BACKENDS` env var (JSON, same shape; the option wins per name; `claude`/`codex` reserved). Custom backends carry a `schema` as turn-level `_meta.outputSchema` and read the result off the final message as JSON.
+- **`CustomAcpBackend` / `resolveBackendRegistry` / `BACKENDS_ENV`** — the custom-backend registry: run **any** ACP agent as a named backend via `createAcpRunner({ backends: { name: { command, args?, env?, sessionMeta?, customCapabilities? } } })` or the `AGENTPRISM_BACKENDS` env var (JSON, same shape; the option wins per name; `claude`/`codex` reserved). Custom backends carry a `schema` as turn-level `_meta.outputSchema` and read the result off the final message as JSON. `customCapabilities: { namespace, gatedKeys }` declares the agent's `agentCapabilities._meta` negotiation contract: once the agent advertises that namespace, each declared bare `_meta` key is sent only when its same-named flag is `true` (no declaration = never gated).
+- **`PermissionResolver`** — async human-in-the-loop permission resolution for runner-wide or interactive sessions.
+- **`clientCapabilitiesFor` + the `ClientHandlers` / `FsHandlers` / `TerminalHandlers` / `AcpSessionContext` types** — the client-side fs/terminal interposition surface (see above).
+- **`negotiateCapabilities` / `adaptPromptContent` / `gateCustomMeta` / `unsupportedMcpServer` + `NegotiatedCapabilities`** — the `initialize` capability-negotiation primitives; the negotiated record for a live connection is exposed on `PooledConnection.capabilities`.
 - **`toJsonSchema(schema)` / `toStrictJsonSchema(schema)`** — turn a typebox schema into the on-the-wire shapes: a plain JSON Schema for Claude `outputFormat`, and an OpenAI-strict-normalized schema for Codex `outputSchema`.
 
-Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `SessionHandle`, `decidePermission`, `UsageAccumulator`, `resolveStructuredOutput` / `extractValidated` / `findJsonBlock` / `validateValue`, `errorText` / `mapThrownError`, and the event surface `TypedEventEmitter` / `AcpRunnerEventMap` / `AcpEventName` / `AcpEventListener` / `AcpEventContext` / `AcpSessionUpdate` (+ the per-event payload types), plus their associated types.
+Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `SessionHandle`, `decidePermission`, `UsageAccumulator`, `resolveStructuredOutput` / `extractValidated` / `findJsonBlock` / `validateValue`, `errorText` / `mapThrownError`, and the event surface `TypedEventEmitter` / `AcpRunnerEventMap` / `AcpEventName` / `AcpEventListener` / `AcpEventContext` / `AcpSessionUpdate` (+ the per-event payload types, including `AcpPermissionPendingEvent`), plus their associated types.
 
 ## Environment overrides
 
 | Variable | Effect |
 | --- | --- |
 | `AGENTPRISM_DEFAULT_BACKEND` | Backend when `model`/`tier` don't pick one (`codex` selects Codex; a registered custom name selects that backend; anything else is Claude). |
-| `AGENTPRISM_BACKENDS` | Custom ACP backends as JSON: `{"<name>": {"command": "…", "args": […], "env": {…}, "sessionMeta": {…}}}`. |
+| `AGENTPRISM_BACKENDS` | Custom ACP backends as JSON: `{"<name>": {"command": "…", "args": […], "env": {…}, "sessionMeta": {…}, "customCapabilities": {"namespace": "…", "gatedKeys": […]}}}`. |
 | `AGENTPRISM_ACP_INIT_TIMEOUT_MS` | Deadline (default `60000`) for a backend's one-time ACP `initialize` handshake — a non-ACP command fails fast instead of hanging. |
 | `AGENTPRISM_ACP_POOL_SIZE` | Long-lived processes to keep per backend (default `1`). |
 | `AGENTPRISM_CLAUDE_ACP_CMD` / `AGENTPRISM_CLAUDE_ACP_ARGS` | Override the command (and args) used to spawn the Claude ACP server. |

package/dist/acp-client.d.ts

@@ -1,35 +1,46 @@
-import { ClientSideConnection, type PromptResponse, type SessionConfigOption, type SessionNotification } from "@agentclientprotocol/sdk";
+import { ClientSideConnection, type ContentBlock, type PromptResponse, type RequestPermissionResponse, type SessionConfigOption, type SessionNotification } from "@agentclientprotocol/sdk";
 import type { TSchema } from "typebox";
 import { type AgentHistoryEntry, type McpServerConfig } from "@automatalabs/shared-types";
 import type { Backend, BackendId, StructuredSource } from "./backend.js";
 import { type NegotiatedCapabilities } from "./capabilities.js";
 import { type AcpEventSink } from "./events.js";
-import { type ToolPolicy } from "./permissions.js";
+import { type PermissionResolver, type ToolPolicy } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
+import { type ClientHandlers } from "./client-handlers.js";
 interface RawResultSuccess {
     type: string;
     subtype: string;
     structured_output?: unknown;
 }
 /** Per-session accumulator: assistant text, tool history, usage, the Claude raw structured_output,
- *  and the tool policy used to auto-answer permission requests for THIS session. */
+ *  and the permission policy/resolver used to answer permission requests for THIS session. */
 declare class SessionState {
+    readonly cwd: string;
     readonly policy: ToolPolicy;
+    readonly permissionResolver?: PermissionResolver | undefined;
     readonly label?: string | undefined;
     readonly runId?: string | undefined;
+    private readonly retainSessionLog;
     readonly textChunks: string[];
     readonly history: AgentHistoryEntry[];
     readonly usage: UsageAccumulator;
+    readonly pendingPermissions: Set<(outcome: RequestPermissionResponse) => void>;
     rawResultSuccess: RawResultSuccess | undefined;
     private turnStartIndex;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(policy: ToolPolicy, label?: string | undefined, runId?: string | undefined);
-    /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn. */
+    constructor(cwd: string, policy: ToolPolicy, permissionResolver?: PermissionResolver | undefined, label?: string | undefined, runId?: string | undefined, retainSessionLog?: boolean);
+    /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn.
+     *  Long-lived interactive sessions can opt out of retaining old text/history because hosts
+     *  stream live events and keep their own transcript; clearing here prevents dead logs from
+     *  growing for the lifetime of a held-open session. */
     beginTurn(): void;
     currentTurnText(): string;
     applyUpdate(update: SessionNotification["update"]): void;
     applyRawMessage(message: RawResultSuccess | undefined): void;
+    /** Settle every deferred permission still parked on this session. Used by release/cancel/death
+     *  teardown so an interactive resolver can never strand an ACP prompt turn. */
+    settlePendingPermissions(): void;
 }
 export interface AcpSessionOptions {
     /** Absolute working directory for the ACP session (worktree isolation). */
@@ -37,6 +48,9 @@ export interface AcpSessionOptions {
     /** The schema for this run, if any (drives the backend's session/prompt `_meta`). */
     schema: TSchema | undefined;
     policy: ToolPolicy;
+    /** Session-scoped permission resolver. When present it wins over the runner default and
+     *  replaces the synchronous ToolPolicy auto-response path for this session. */
+    permissionResolver?: PermissionResolver;
     signal?: AbortSignal;
     /** Client-provided MCP servers to attach at session/new. Omitted => `[]` (the default). */
     mcpServers?: McpServerConfig[];
@@ -53,6 +67,11 @@ export interface AcpSessionOptions {
      *  (bare keys) for the codex-acp adapter; the Claude backend ignores them. Omitted => unset. */
     baseInstructions?: string;
     developerInstructions?: string;
+    /** Retain accumulated assistant text/tool history for the lifetime of this ACP session.
+     *  Default true preserves run()'s diagnostic history contract. Held-open interactive sessions
+     *  pass false because hosts stream live events / keep their own transcript; retaining old turns
+     *  there is dead memory for day-long sessions. */
+    retainSessionLog?: boolean;
 }
 /** Notified by a PooledConnection when its process dies, so the pool can drop it. */
 export interface PooledConnectionDeps {
@@ -61,6 +80,10 @@ export interface PooledConnectionDeps {
      *  session lifecycle change on this connection is bubbled up through it (additive observability;
      *  it is invoked AFTER the drain accumulation and never affects the run). */
     onEvent?: AcpEventSink;
+    /** Runner-wide permission resolver default. SessionState.permissionResolver overrides it. */
+    permissionResolver?: PermissionResolver;
+    /** Client-side ACP fs/terminal handlers advertised once and routed by sessionId. */
+    clientHandlers?: ClientHandlers;
 }
 /**
  * One long-lived ACP server subprocess + its held ACP client connection. Initialized ONCE and
@@ -76,6 +99,7 @@ export declare class PooledConnection {
     private readonly client;
     private readonly onDead;
     private readonly onEvent;
+    private readonly clientHandlers;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     private disposing;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -98,8 +122,8 @@ export declare class PooledConnection {
     /** The capabilities negotiated on this connection's one-time initialize handshake, or undefined
      *  until it completes — derived-state-behind-a-getter, like `alive`/`activeSessions`. */
     get capabilities(): NegotiatedCapabilities | undefined;
-    /** Drop the fork's custom bare `_meta` keys the connected agent did not advertise support for
-     *  (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
+    /** Drop the backend-declared bare `_meta` keys the connected agent did not advertise support
+     *  for (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
     gateCustomMeta(meta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     private die;
@@ -117,9 +141,9 @@ export declare class PooledConnection {
     /** Best-effort ACP cancel for one session (wired to opts.signal). The PROCESS stays pooled. */
     cancelSession(sessionId: string): Promise<void>;
     /**
-     * Release a session: stop routing it, free the load slot, and best-effort session/close on the
-     * wire (capability-gated, bounded, never fatal). The PROCESS is NOT killed — it returns to the
-     * pool for the next agent() call.
+     * Release a session: move it to teardown-only routing, free the load slot, and best-effort
+     * session/close on the wire (capability-gated, bounded, never fatal). The PROCESS is NOT
+     * killed — it returns to the pool for the next agent() call.
      */
     releaseSession(sessionId: string): Promise<void>;
     /** Synchronous best-effort kill for a process-exit hook (no time to await a graceful close). */
@@ -134,7 +158,7 @@ export declare class PooledConnection {
  */
 export declare class SessionHandle implements StructuredSource {
     private readonly pooled;
-    private readonly sessionId;
+    readonly sessionId: string;
     private readonly state;
     private readonly opts;
     private configOptions;
@@ -180,7 +204,7 @@ export declare class SessionHandle implements StructuredSource {
     /** Set one session config option via the wire method and adopt the echoed catalog. */
     private applyConfigOption;
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
-    prompt(text: string, promptMeta?: Record<string, unknown>): Promise<PromptResponse>;
+    prompt(content: string | ContentBlock[], promptMeta?: Record<string, unknown>): Promise<PromptResponse>;
     /** StructuredSource — the latest turn's assistant text. */
     currentTurnText(): string;
     /** StructuredSource — Claude's raw structured_output for the latest turn, if any. */

package/dist/acp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}

package/dist/acp-client.js

@@ -22,12 +22,13 @@
 // other sessions' updates interleave on the same wire.
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
-import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { ClientSideConnection, CLIENT_METHODS, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
 import { META_KEYS, WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
-import { gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
+import { adaptPromptContent, gateCustomMeta, isSupportedProtocolVersion, negotiateCapabilities, unsupportedMcpServer, } from "./capabilities.js";
 import { emitSessionUpdate } from "./events.js";
 import { decidePermission } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
+import { clientCapabilitiesFor, } from "./client-handlers.js";
 /** A benign client identity. NOT JetBrains/IntelliJ 2026.1 — that exact identity makes
  *  codex-acp disable session config options (our model/effort routing channel). */
 const CLIENT_INFO = {
@@ -40,27 +41,45 @@ const CLAUDE_RAW_MESSAGE_METHOD = "_claude/sdkMessage";
 const CLOSE_SESSION_TIMEOUT_MS = 5_000;
 /** Bound the graceful SIGTERM shutdown before escalating to SIGKILL. */
 const DISPOSE_SIGKILL_GRACE_MS = 2_000;
+const TOMBSTONE_SESSION_CAP = 64;
 /** Per-session accumulator: assistant text, tool history, usage, the Claude raw structured_output,
- *  and the tool policy used to auto-answer permission requests for THIS session. */
+ *  and the permission policy/resolver used to answer permission requests for THIS session. */
 class SessionState {
+    cwd;
     policy;
+    permissionResolver;
     label;
     runId;
+    retainSessionLog;
     textChunks = [];
     history = [];
     usage = new UsageAccumulator();
+    pendingPermissions = new Set();
     rawResultSuccess;
     turnStartIndex = 0;
     /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
      *  events as context — they never affect routing or the wire request. */
-    constructor(policy, label, runId) {
+    constructor(cwd, policy, permissionResolver, label, runId, retainSessionLog = true) {
+        this.cwd = cwd;
         this.policy = policy;
+        this.permissionResolver = permissionResolver;
         this.label = label;
         this.runId = runId;
+        this.retainSessionLog = retainSessionLog;
     }
-    /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn. */
+    /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn.
+     *  Long-lived interactive sessions can opt out of retaining old text/history because hosts
+     *  stream live events and keep their own transcript; clearing here prevents dead logs from
+     *  growing for the lifetime of a held-open session. */
     beginTurn() {
-        this.turnStartIndex = this.textChunks.length;
+        if (this.retainSessionLog) {
+            this.turnStartIndex = this.textChunks.length;
+        }
+        else {
+            this.textChunks.length = 0;
+            this.history.length = 0;
+            this.turnStartIndex = 0;
+        }
         this.rawResultSuccess = undefined;
     }
     currentTurnText() {
@@ -106,6 +125,12 @@ class SessionState {
             this.rawResultSuccess = message;
         }
     }
+    /** Settle every deferred permission still parked on this session. Used by release/cancel/death
+     *  teardown so an interactive resolver can never strand an ACP prompt turn. */
+    settlePendingPermissions() {
+        for (const settle of [...this.pendingPermissions])
+            settle(cancelledPermissionResponse());
+    }
 }
 /** The single ACP Client handler for one pooled connection. It ROUTES every notification and
  *  permission request to the per-session SessionState by `sessionId`, so one process can serve
@@ -113,39 +138,141 @@ class SessionState {
 class MultiplexClient {
     backendId;
     onEvent;
+    handlers;
+    permissionResolver;
     sessions = new Map();
+    /** Recently unregistered sessions kept ONLY for the teardown window: ACP agents may
+     *  legitimately release terminals (or finish fs/terminal cleanup) after this client releases
+     *  the session because session/close is cancel + free resources and the Agent owns terminal
+     *  release. Store only the slim routing context and cap it FIFO so the memory cost is bounded. */
+    tombstones = new Map();
     /** `backendId` stamps event context; `onEvent` (optional) bubbles every notification, permission
-     *  request and session lifecycle change up to the runner's typed bus. */
-    constructor(backendId, onEvent) {
+     *  request and session lifecycle change up to the runner's typed bus. `permissionResolver` is
+     *  the runner-wide default; a SessionState resolver wins when present. */
+    constructor(backendId, onEvent, handlers, permissionResolver) {
         this.backendId = backendId;
         this.onEvent = onEvent;
+        this.handlers = handlers;
+        this.permissionResolver = permissionResolver;
     }
     contextFor(sessionId, state) {
         return { sessionId, backendId: this.backendId, label: state?.label, runId: state?.runId };
     }
+    handlerContext(params) {
+        const state = this.sessions.get(params.sessionId);
+        if (state)
+            return { sessionId: params.sessionId, cwd: state.cwd, label: state.label, runId: state.runId };
+        const tombstone = this.tombstones.get(params.sessionId);
+        if (tombstone)
+            return { sessionId: params.sessionId, ...tombstone };
+        throw unknownSession(params.sessionId);
+    }
+    dispatch(params, wireMethod, handler) {
+        if (typeof handler !== "function")
+            throw methodNotAdvertised(wireMethod);
+        const ctx = this.handlerContext(params);
+        return handler(params, ctx);
+    }
     register(sessionId, state) {
+        this.tombstones.delete(sessionId);
         this.sessions.set(sessionId, state);
         this.onEvent?.("session_open", this.contextFor(sessionId, state));
     }
     unregister(sessionId) {
         const state = this.sessions.get(sessionId);
+        state?.settlePendingPermissions();
         this.sessions.delete(sessionId);
-        if (state)
+        if (state) {
+            this.tombstones.set(sessionId, {
+                cwd: state.cwd,
+                label: state.label,
+                runId: state.runId,
+            });
+            while (this.tombstones.size > TOMBSTONE_SESSION_CAP) {
+                const oldest = this.tombstones.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.tombstones.delete(oldest);
+            }
             this.onEvent?.("session_close", this.contextFor(sessionId, state));
+        }
+    }
+    settlePendingPermissions(sessionId) {
+        this.sessions.get(sessionId)?.settlePendingPermissions();
+    }
+    settleAllPendingPermissions() {
+        for (const state of this.sessions.values()) {
+            state.settlePendingPermissions();
+        }
     }
     requestPermission(params) {
         const state = this.sessions.get(params.sessionId);
         // Unknown/closed session: refuse rather than silently allow a tool we can't attribute.
         if (!state)
-            return { outcome: { outcome: "cancelled" } };
+            return cancelledPermissionResponse();
+        const ctx = this.contextFor(params.sessionId, state);
+        const resolver = state.permissionResolver ?? this.permissionResolver;
+        if (resolver)
+            return this.requestPermissionViaResolver(params, state, ctx, resolver);
         const outcome = decidePermission(params, state.policy);
         this.onEvent?.("permission_request", {
-            ...this.contextFor(params.sessionId, state),
+            ...ctx,
             request: params,
             outcome,
         });
         return outcome;
     }
+    requestPermissionViaResolver(params, state, ctx, resolver) {
+        let settled = false;
+        let settle;
+        const response = new Promise((resolve) => {
+            settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                state.pendingPermissions.delete(settle);
+                this.onEvent?.("permission_request", { ...ctx, request: params, outcome });
+                resolve(outcome);
+            };
+            state.pendingPermissions.add(settle);
+            this.onEvent?.("permission_pending", { ...ctx, request: params });
+            try {
+                Promise.resolve(resolver(params, ctx)).then((outcome) => {
+                    settle(outcome);
+                }, () => {
+                    // No session-scoped resolver-error event exists; the permission_request event still
+                    // reports the FINAL outcome exactly once, so rejection is observable as cancellation.
+                    settle(cancelledPermissionResponse());
+                });
+            }
+            catch {
+                settle(cancelledPermissionResponse());
+            }
+        });
+        response.catch(() => { });
+        return response;
+    }
+    readTextFile(params) {
+        return this.dispatch(params, CLIENT_METHODS.fs_read_text_file, this.handlers?.fs?.readTextFile);
+    }
+    writeTextFile(params) {
+        return this.dispatch(params, CLIENT_METHODS.fs_write_text_file, this.handlers?.fs?.writeTextFile);
+    }
+    createTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_create, this.handlers?.terminal?.createTerminal);
+    }
+    terminalOutput(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_output, this.handlers?.terminal?.terminalOutput);
+    }
+    releaseTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_release, this.handlers?.terminal?.releaseTerminal);
+    }
+    waitForTerminalExit(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_wait_for_exit, this.handlers?.terminal?.waitForTerminalExit);
+    }
+    killTerminal(params) {
+        return this.dispatch(params, CLIENT_METHODS.terminal_kill, this.handlers?.terminal?.killTerminal);
+    }
     sessionUpdate(params) {
         const state = this.sessions.get(params.sessionId);
         // Fold into the accumulator FIRST (the drain contract), THEN bubble the event up unchanged.
@@ -172,6 +299,15 @@ class MultiplexClient {
         });
     }
 }
+function unknownSession(sessionId) {
+    return RequestError.invalidParams({ sessionId }, `unknown session: ${sessionId}`);
+}
+function cancelledPermissionResponse() {
+    return { outcome: { outcome: "cancelled" } };
+}
+function methodNotAdvertised(method) {
+    return new RequestError(-32601, `${method} was not advertised by this client`, { method });
+}
 const DEFAULT_INIT_TIMEOUT_MS = 60_000;
 /** Deadline for the one-time ACP `initialize` handshake per pooled process. Overridable via
  *  AGENTPRISM_ACP_INIT_TIMEOUT_MS (e.g. for slow cold-start backends). Clamped to >= 1s. */
@@ -225,6 +361,7 @@ export class PooledConnection {
     client;
     onDead;
     onEvent;
+    clientHandlers;
     /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
     disposing = false;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
@@ -243,7 +380,8 @@ export class PooledConnection {
         this.backendId = backend.id;
         this.onDead = deps.onDead;
         this.onEvent = deps.onEvent;
-        this.client = new MultiplexClient(this.backendId, this.onEvent);
+        this.clientHandlers = deps.clientHandlers;
+        this.client = new MultiplexClient(this.backendId, this.onEvent, deps.clientHandlers, deps.permissionResolver);
         const { command, args, env } = backend.spawnConfig();
         // NOTE: deliberately NO `cwd` here. cwd is per-SESSION (session/new), so one pooled process
         // serves runs in different worktrees without losing isolation.
@@ -296,10 +434,10 @@ export class PooledConnection {
     get capabilities() {
         return this.negotiated;
     }
-    /** Drop the fork's custom bare `_meta` keys the connected agent did not advertise support for
-     *  (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
+    /** Drop the backend-declared bare `_meta` keys the connected agent did not advertise support
+     *  for (see gateCustomMeta). Applied to BOTH session/new and session/prompt `_meta`. */
     gateCustomMeta(meta) {
-        return gateCustomMeta(meta, this.negotiated?.customMetaSupport);
+        return gateCustomMeta(meta, this.negotiated?.customMetaSupport, this.negotiated?.gatedKeys);
     }
     /** Mark this connection dead exactly once, then ask the pool to evict it. Idempotent. */
     die(error) {
@@ -308,6 +446,7 @@ export class PooledConnection {
         this._alive = false;
         this.deathError = error;
         this.resolveDead();
+        this.client.settleAllPendingPermissions();
         // A crash (not a graceful dispose) is worth surfacing for observability; the engine still
         // handles it by retrying the run on a fresh process. Best-effort, after death is recorded.
         if (this.onEvent && !this.disposing) {
@@ -349,15 +488,14 @@ export class PooledConnection {
             const response = await Promise.race([
                 this.race(this.rpc.initialize({
                     protocolVersion: PROTOCOL_VERSION,
-                    // Truthful advertisement: MultiplexClient implements NONE of the client-side
-                    // fs/terminal methods, so we advertise none (the ACP rule is "advertise only what you
-                    // implement"). Everything omitted here is treated as unsupported by the agent.
-                    clientCapabilities: {},
+                    // Truthful advertisement: computed from the consumer-provided handlers registered on
+                    // this runner. Omitted flags are unsupported; false flags are never sent deliberately.
+                    clientCapabilities: clientCapabilitiesFor(this.clientHandlers),
                     clientInfo: { ...CLIENT_INFO },
                 })),
                 deadline,
             ]);
-            const negotiated = negotiateCapabilities(response);
+            const negotiated = negotiateCapabilities(response, this.backend.customCapabilities);
             // Version negotiation: the agent replies with the version it chose (our requested version if
             // it supports it, else its own latest). If this client cannot speak it, the ACP spec says
             // CLOSE the connection and inform the user — kill the process (so the pool evicts it) and
@@ -395,13 +533,13 @@ export class PooledConnection {
                 throw new WorkflowError(`MCP server "${unsupported.name}" uses the "${unsupported.transport}" transport, which the ` +
                     `${this.backendId} agent does not support`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: opts.label });
             }
-            const state = new SessionState(opts.policy, opts.label, opts.runId);
+            const state = new SessionState(opts.cwd, opts.policy, opts.permissionResolver, opts.label, opts.runId, opts.retainSessionLog ?? true);
             // session/new `_meta`, layered lowest-to-highest precedence: the backend's static
             // defaults (a custom registry entry's `sessionMeta`), then the generic user passthrough
             // (opts.meta), then the backend's protocol-critical `_meta` (Claude schema channel;
             // Codex base/developer instructions), then the engine runId correlation stamp. The result
-            // is gated against the agent's advertised custom capabilities (a Codex instruction key the
-            // agent said it does not honor is dropped). When no layer survives, no `_meta` is sent.
+            // is gated against the agent's advertised custom capabilities (a declared key the agent
+            // said it does not honor is dropped). When no layer survives, no `_meta` is sent.
             const meta = this.gateCustomMeta(stampRunId(layerMeta(this.backend.sessionMetaDefaults?.(), opts.meta, this.backend.sessionMeta(opts.schema, {
                 baseInstructions: opts.baseInstructions,
                 developerInstructions: opts.developerInstructions,
@@ -423,6 +561,7 @@ export class PooledConnection {
     }
     /** Best-effort ACP cancel for one session (wired to opts.signal). The PROCESS stays pooled. */
     async cancelSession(sessionId) {
+        this.client.settlePendingPermissions(sessionId);
         if (!this._alive)
             return;
         try {
@@ -433,9 +572,9 @@ export class PooledConnection {
         }
     }
     /**
-     * Release a session: stop routing it, free the load slot, and best-effort session/close on the
-     * wire (capability-gated, bounded, never fatal). The PROCESS is NOT killed — it returns to the
-     * pool for the next agent() call.
+     * Release a session: move it to teardown-only routing, free the load slot, and best-effort
+     * session/close on the wire (capability-gated, bounded, never fatal). The PROCESS is NOT
+     * killed — it returns to the pool for the next agent() call.
      */
     async releaseSession(sessionId) {
         this.client.unregister(sessionId);
@@ -623,16 +762,18 @@ export class SessionHandle {
         this.configOptions = response.configOptions;
     }
     /** Send a prompt turn and drain it; returns the final PromptResponse. */
-    async prompt(text, promptMeta) {
+    async prompt(content, promptMeta) {
         this.opts.signal?.throwIfAborted();
         this.state.beginTurn();
-        const prompt = [{ type: "text", text }];
-        // Gate the turn `_meta` against the agent's advertised custom capabilities: the Codex
-        // outputSchema forward is dropped when the connected agent said it does not honor it.
+        const prompt = typeof content === "string"
+            ? content
+            : adaptPromptContent(content, this.pooled.capabilities?.agent ?? {}, this.pooled.backendId);
+        // Gate the turn `_meta` against the agent's advertised custom capabilities: a declared
+        // turn-level key is dropped when the connected agent said it does not honor it.
         const gatedMeta = this.pooled.gateCustomMeta(promptMeta);
         const request = {
             sessionId: this.sessionId,
-            prompt,
+            prompt: typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt,
             ...(gatedMeta ? { _meta: gatedMeta } : {}),
         };
         const response = await this.pooled.race(this.pooled.rpc.prompt(request));