@inixiative/agent-session 0.5.0 → 0.6.0

package/README.md

@@ -75,12 +75,42 @@ const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOM
 | Resume / fork | native / native | loaded-only / same-thread | native / – | native / native | – | – |
 | Interrupt | acknowledged | local-only | acknowledged | acknowledged | – | – |
 | Push | – | – | steer | – | – | – |
-| Approvals | mode | mode | refuse | callback | – | – |
+| Approvals | callback | mode | callback | callback | – | – |
 | Limits stream / poll | ✅ / ✅ | – / – | ✅ / ✅ | ✅ / – | – | – |
 | Primed reset | fork | – | fork | – | – | – |
 
 Full matrix, notes and what is stubbed: [docs/transports-pools-routing.md](docs/transports-pools-routing.md).
 
+### Tool gate
+
+`onToolRequest(gate)` puts a decision on each tool call. Gates compose in
+registration order; the first deny wins and a throwing gate denies.
+
+```ts
+const session = new ClaudeCodeSession({ cwd, permissionMode: hostMode, toolGate: true });
+session.onToolRequest(async (call) => {
+  if (call.stage === "pre-use") return structural(call) ?? { behavior: "allow" };
+  return askTheHuman(call, call.signal); // the runtime's own mode wanted to ask
+});
+```
+
+- `pre-use` (Claude only) runs before every call in every mode,
+  `bypassPermissions` included; only a deny counts. A PreToolUse callback over
+  the control protocol; one the session cannot read is denied.
+- `permission` is an ask the runtime's mode raised; the answer is final (no gate:
+  denied). Claude: `--permission-prompt-tool stdio`; `decisionReason` says why it
+  asked, `agentId` marks a subagent's call. Codex app-server: command and
+  file-change `requestApproval`, answered accept/decline, under
+  `appServer: codexPermissions(mode)`. File-change asks carry the item's
+  `toolInput.changes` (path, kind, bounded diff); command asks carry
+  `networkApprovalContext`. Gated threads pin `approvalsReviewer: "user"` and
+  are refused if a config routes approvals elsewhere. Under the default `never`
+  policy nothing is asked, so `onToolRequest` throws.
+- `call.signal` aborts when the runtime withdraws the request or the session
+  ends (kill, exit, transport failure); a decision after that is never written.
+  A turn timeout does not withdraw a pending Claude ask; `interruptNative()` does.
+- A fork starts with a snapshot of the parent's gates.
+
 ## Primed decision sessions
 
 One live, warm session per middleware role, primed once with its role

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./routing": "./src/routing.ts"
   },
   "files": [
     "src"
@@ -35,11 +36,11 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.5.0"
+    "@inixiative/json-rules": "^3.5.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.63",
+    "@inixiative/config": "^0.5.67",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-agent-sdk-session.ts

@@ -52,7 +52,8 @@ export interface ClaudeAgentSdkSessionConfig extends Omit<ClaudeCodeSessionConfi
 }
 
 const SDK_OWNED = new Set(['--print', '--verbose']);
-const SDK_OWNED_VALUE = new Set(['--input-format', '--output-format']);
+// `--permission-prompt-tool stdio` is the SDK's own canUseTool channel; the bridge wires it.
+const SDK_OWNED_VALUE = new Set(['--input-format', '--output-format', '--permission-prompt-tool']);
 
 /** Map a ClaudeCodeSession argv (without the binary) to SDK options. Exported for tests. */
 export function sdkOptionsFromArgv(argv: readonly string[]): Record<string, unknown> {
@@ -170,6 +171,94 @@ function bridge(
       },
     };
 
+    // Tool gate: the SDK's canUseTool and PreToolUse hook become the CLI's own control requests
+    // on the bridged stdout, so ClaudeCodeSession answers them exactly as on the CLI transport.
+    const gated = cmd.includes('--permission-prompt-tool');
+    let hookCallbackId: string | undefined;
+    const awaiting = new Map<string, (response: unknown) => void>();
+    const ask = (request: Record<string, unknown>, signal?: AbortSignal) =>
+      new Promise<unknown>((resolve) => {
+        const id = `sdk-bridge-${crypto.randomUUID()}`;
+        awaiting.set(id, resolve);
+        signal?.addEventListener(
+          'abort',
+          () => {
+            if (awaiting.delete(id)) {
+              emit({ type: 'control_cancel_request', request_id: id });
+              resolve(undefined);
+            }
+          },
+          { once: true },
+        );
+        emit({ type: 'control_request', request_id: id, request });
+      });
+    const gate = gated
+      ? {
+          canUseTool: async (
+            toolName: string,
+            input: Record<string, unknown>,
+            context: {
+              signal?: AbortSignal;
+              toolUseID?: string;
+              blockedPath?: string;
+              decisionReason?: string;
+              description?: string;
+              agentID?: string;
+            } = {},
+          ) =>
+            ((await ask(
+              {
+                subtype: 'can_use_tool',
+                tool_name: toolName,
+                input,
+                ...(context.toolUseID ? { tool_use_id: context.toolUseID } : {}),
+                ...(context.blockedPath ? { blocked_path: context.blockedPath } : {}),
+                ...(typeof context.decisionReason === 'string' && context.decisionReason
+                  ? { decision_reason: context.decisionReason }
+                  : {}),
+                ...(typeof context.description === 'string' && context.description
+                  ? { description: context.description }
+                  : {}),
+                ...(context.agentID ? { agent_id: context.agentID } : {}),
+              },
+              context.signal,
+            )) as Record<string, unknown> | undefined) ?? {
+              behavior: 'deny',
+              message: 'Approval withdrawn',
+            },
+          hooks: {
+            PreToolUse: [
+              {
+                matcher: '.*',
+                hooks: [
+                  async (
+                    input: Record<string, unknown>,
+                    toolUseID: string | undefined,
+                    context: { signal?: AbortSignal } = {},
+                  ) =>
+                    ((await ask(
+                      {
+                        subtype: 'hook_callback',
+                        callback_id: hookCallbackId,
+                        input,
+                        ...(toolUseID ? { tool_use_id: toolUseID } : {}),
+                      },
+                      context.signal,
+                    )) as Record<string, unknown> | undefined) ?? {
+                      // No answer (bridge closed, or the session could not read it): fail closed.
+                      hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'deny',
+                        permissionDecisionReason: 'Tool gate unavailable',
+                      },
+                    },
+                ],
+              },
+            ],
+          },
+        }
+      : undefined;
+
     const stringEnv = Object.fromEntries(
       Object.entries(env).filter(
         (entry): entry is [string, string] => typeof entry[1] === 'string',
@@ -181,6 +270,19 @@ function bridge(
       cwd,
       env: stringEnv,
       ...(config.canUseTool ? { canUseTool: config.canUseTool } : {}),
+      ...(gate
+        ? {
+            canUseTool: gate.canUseTool,
+            hooks: {
+              ...((config.sdkOptions?.hooks as Record<string, unknown> | undefined) ?? {}),
+              PreToolUse: [
+                ...(((config.sdkOptions?.hooks as Record<string, unknown[]> | undefined)
+                  ?.PreToolUse ?? []) as unknown[]),
+                ...gate.hooks.PreToolUse,
+              ],
+            },
+          }
+        : {}),
       ...(config.bundledCli ? {} : { pathToClaudeCodeExecutable: Bun.which(cmd[0]!) ?? cmd[0] }),
     };
     let query: ClaudeAgentSdkQuery,
@@ -223,10 +325,27 @@ function bridge(
               inbox.push({ ...message, parent_tool_use_id: null, session_id: '' });
               wake?.();
               wake = undefined;
+            } else if (message.type === 'control_response') {
+              const response = message.response as Record<string, unknown> | undefined;
+              const id = String(response?.request_id);
+              const resolve = awaiting.get(id);
+              if (resolve) {
+                awaiting.delete(id);
+                resolve(response?.subtype === 'success' ? response.response : undefined);
+              }
             } else if (message.type === 'control_request') {
               const id = String(message.request_id);
-              const subtype = (message.request as Record<string, unknown> | undefined)?.subtype;
-              if (subtype === 'interrupt')
+              const request = message.request as Record<string, unknown> | undefined;
+              const subtype = request?.subtype;
+              if (subtype === 'initialize' && gated) {
+                // Hooks were configured as SDK options at launch; only the callback id is new.
+                const pre = (request?.hooks as Record<string, unknown> | undefined)?.PreToolUse;
+                const ids = Array.isArray(pre)
+                  ? (pre[0] as { hookCallbackIds?: unknown } | undefined)?.hookCallbackIds
+                  : undefined;
+                hookCallbackId = Array.isArray(ids) ? String(ids[0]) : undefined;
+                queueMicrotask(() => respond(id));
+              } else if (subtype === 'interrupt')
                 query.interrupt().then(
                   () => respond(id),
                   (e) => respond(id, String((e as Error)?.message ?? e)),
@@ -254,6 +373,8 @@ function bridge(
       kill() {
         if (killed) return;
         killed = true;
+        for (const resolve of awaiting.values()) resolve(undefined);
+        awaiting.clear();
         inputEnded = true;
         wake?.();
         wake = undefined;
@@ -277,6 +398,10 @@ export class ClaudeAgentSdkSession extends ClaudeCodeSession {
   constructor(config: ClaudeAgentSdkSessionConfig) {
     if (typeof config?.query !== 'function')
       throw Error('ClaudeAgentSdkSession requires `query` from @anthropic-ai/claude-agent-sdk');
+    if (config.canUseTool && config.toolGate)
+      throw Error(
+        'ClaudeAgentSdkSession: pass either canUseTool or toolGate (gates registered through onToolRequest), not both',
+      );
     if (config.canUseTool && config.permissionMode === 'bypassPermissions')
       throw Error(
         'ClaudeAgentSdkSession: canUseTool is never consulted under permissionMode "bypassPermissions"; pass another mode or drop canUseTool',

package/src/claude-code-session.ts

@@ -5,6 +5,7 @@ import {
   mergeLimits,
 } from './limits';
 import { retainEvidence } from './retained-evidence';
+import { mcpToolParts, ToolGates } from './tool-gate';
 import { TRANSPORTS } from './transport';
 import { TurnState } from './turn-state';
 
@@ -53,6 +54,9 @@ import type {
   SessionResult,
   SessionSendOptions,
   SessionTokens,
+  ToolDecision,
+  ToolGate,
+  ToolRequest,
 } from './harness-session';
 
 // Re-export types so existing import paths keep working
@@ -113,6 +117,14 @@ export interface ClaudeCodeSessionConfig {
   textOnly?: boolean;
   /** False adds `--no-session-persistence` (nothing written to history; cannot be resumed). Default true. */
   persistSession?: boolean;
+  /**
+   * Launch for per-call tool decisions: `--permission-prompt-tool stdio` plus a PreToolUse
+   * callback registered over the control protocol at start(). Gates added with
+   * onToolRequest() decide (a `permission` ask with no gate is denied). A callback or ask that
+   * cannot be read as a tool request is denied (fail closed). A turn timeout leaves a pending
+   * ask open; interruptNative() withdraws it. Not with textOnly.
+   */
+  toolGate?: boolean;
   /**
    * Override for the process spawner. Defaults to Bun.spawn. Tests inject a
    * fake subprocess that emulates the claude CLI's stream-json protocol.
@@ -252,6 +264,11 @@ export class ClaudeCodeSession implements HarnessSession {
   private _env?: ClaudeCodeSessionConfig['env'];
   private _textOnly: boolean;
   private _persistSession: boolean;
+  private _toolGate: boolean;
+  private _gates = new ToolGates();
+  /** Inbound control requests awaiting a gate decision, by request id. */
+  private _inbound = new Map<string, AbortController>();
+  private readonly _hookCallbackId = `agent-session-pre-tool-${crypto.randomUUID()}`;
   private _limits?: LimitSnapshot;
   private _controlSeq = 0;
   private _control = new Map<
@@ -325,6 +342,9 @@ export class ClaudeCodeSession implements HarnessSession {
     this._env = config?.env;
     this._textOnly = config?.textOnly ?? false;
     this._persistSession = config?.persistSession ?? true;
+    this._toolGate = config?.toolGate ?? false;
+    if (this._toolGate && this._textOnly)
+      throw new Error('toolGate requires a session with tools; textOnly sessions have none');
     this._startedAt = Date.now();
   }
 
@@ -375,6 +395,12 @@ export class ClaudeCodeSession implements HarnessSession {
     };
   }
 
+  /** Register a tool gate. A fork gets a snapshot of the gates registered at fork() time. */
+  onToolRequest(gate: ToolGate): () => void {
+    if (!this._toolGate) throw new Error('Tool gates need a session launched with toolGate: true');
+    return this._gates.add(gate);
+  }
+
   onBeforeSend(hook: BeforeSendHook): () => void {
     this._beforeSendHooks.push(hook);
     return () => {
@@ -456,11 +482,30 @@ export class ClaudeCodeSession implements HarnessSession {
       this._rejectControl(new Error('Session ended'));
       this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
     });
+
+    // The PreToolUse callback is registered before any turn is written, so it covers the first call.
+    if (this._toolGate) {
+      try {
+        await this._controlRequest(
+          {
+            subtype: 'initialize',
+            hooks: { PreToolUse: [{ matcher: '.*', hookCallbackIds: [this._hookCallbackId] }] },
+          },
+          30_000,
+        );
+      } catch (error) {
+        this.kill();
+        throw new Error(`Tool gate registration failed: ${(error as Error).message}`);
+      }
+    }
   }
 
   private _rejectControl(error: Error): void {
     for (const pending of this._control.values()) pending.reject(error);
     this._control.clear();
+    // Decisions still pending have nowhere to go: withdraw them.
+    for (const inbound of this._inbound.values()) inbound.abort();
+    this._inbound.clear();
   }
 
   // ---------------------------------------------------------------------------
@@ -530,7 +575,7 @@ export class ClaudeCodeSession implements HarnessSession {
   }
 
   // ---------------------------------------------------------------------------
-  // fork() — branch from current conversation state
+  // fork() — branch from current conversation state (and a snapshot of the tool gates)
   // ---------------------------------------------------------------------------
 
   fork(opts?: {
@@ -558,7 +603,9 @@ export class ClaudeCodeSession implements HarnessSession {
       env: this._env,
       textOnly: this._textOnly,
       persistSession: opts?.persistSession ?? this._persistSession,
+      toolGate: this._toolGate,
     });
+    for (const gate of this._gates.list()) forked._gates.add(gate);
     forked._forking = true;
     return forked;
   }
@@ -930,9 +977,32 @@ export class ClaudeCodeSession implements HarnessSession {
       }
       return;
     }
+    if (raw.type === 'control_cancel_request') {
+      const id = typeof raw.request_id === 'string' ? raw.request_id : undefined;
+      const inbound = id ? this._inbound.get(id) : undefined;
+      if (inbound && id) {
+        this._inbound.delete(id);
+        inbound.abort();
+      }
+      return;
+    }
     if (raw.type === 'control_request') {
-      // No client-side handlers (can_use_tool, hooks) are registered on this transport.
       const id = typeof raw.request_id === 'string' ? raw.request_id : undefined;
+      const request = raw.request as Record<string, unknown> | undefined;
+      const toolRequest =
+        id && this._toolGate && this._proc ? this._toolRequestFrom(request) : undefined;
+      if (id && toolRequest) {
+        this._answerToolRequest(this._proc!, id, toolRequest);
+        return;
+      }
+      // A gated ask or our own callback that cannot be read is denied: an error reply allows.
+      const unreadable = id && this._toolGate && this._proc ? this._unreadable(request) : undefined;
+      if (id && unreadable) {
+        this._writeControlResponse(this._proc!, id, unreadable);
+        this._unattributed(raw, 'unrecognized-event');
+        return;
+      }
+      // No other client-side handlers are registered on this transport.
       if (id && this._proc) {
         try {
           this._proc.stdin.write(
@@ -1094,6 +1164,129 @@ export class ClaudeCodeSession implements HarnessSession {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Private — tool gate (control protocol: hook_callback, can_use_tool)
+  // ---------------------------------------------------------------------------
+
+  private _toolRequestFrom(
+    request: Record<string, unknown> | undefined,
+  ): Omit<ToolRequest, 'signal'> | undefined {
+    const record = (value: unknown) =>
+      value && typeof value === 'object' && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : undefined;
+    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    let stage: ToolRequest['stage'];
+    let source: Record<string, unknown> | undefined;
+    let toolName: string | undefined;
+    let toolInput: Record<string, unknown> | undefined;
+    if (request && this._ownHookCallback(request)) {
+      source = record(request.input);
+      if (source?.hook_event_name !== 'PreToolUse') return undefined;
+      stage = 'pre-use';
+      toolName = text(source.tool_name);
+      toolInput = record(source.tool_input);
+    } else if (request?.subtype === 'can_use_tool') {
+      source = request;
+      stage = 'permission';
+      toolName = text(request.tool_name);
+      toolInput = record(request.input);
+    } else return undefined;
+    if (!toolName) return undefined;
+    const callId = text(source?.tool_use_id) ?? text(request.tool_use_id);
+    const agentId = text(source?.agent_id) ?? text(request.agent_id);
+    const turn = this._inflight;
+    return {
+      stage,
+      toolName,
+      ...mcpToolParts(toolName),
+      toolInput: Object.freeze(structuredClone(toolInput ?? {})),
+      ...(callId ? { callId } : {}),
+      ...(turn?.evidence.dispatch === 'attempted' && turn.evidence.nativeOutcome === 'unknown'
+        ? { admissionId: turn.evidence.admissionId }
+        : {}),
+      ...(text(request.description) ? { description: text(request.description) } : {}),
+      ...(text(request.decision_reason) ? { decisionReason: text(request.decision_reason) } : {}),
+      ...(text(request.blocked_path) ? { blockedPath: text(request.blocked_path) } : {}),
+      ...(agentId ? { agentId } : {}),
+    };
+  }
+
+  private _ownHookCallback(request: Record<string, unknown> | undefined): boolean {
+    return request?.subtype === 'hook_callback' && request.callback_id === this._hookCallbackId;
+  }
+
+  /** The deny for a gated request _toolRequestFrom could not read; undefined when not ours. */
+  private _unreadable(
+    request: Record<string, unknown> | undefined,
+  ): Record<string, unknown> | undefined {
+    if (this._ownHookCallback(request))
+      return this._toolResponse(
+        { stage: 'pre-use', toolName: '', toolInput: {} },
+        { behavior: 'deny', message: 'Tool gate: unreadable PreToolUse callback' },
+      );
+    if (request?.subtype === 'can_use_tool')
+      return { behavior: 'deny', message: 'Tool gate: unreadable permission request' };
+    return undefined;
+  }
+
+  private _answerToolRequest(
+    proc: PipedSubprocess,
+    requestId: string,
+    request: Omit<ToolRequest, 'signal'>,
+  ): void {
+    const controller = new AbortController();
+    this._inbound.set(requestId, controller);
+    void this._gates
+      .decide({ ...request, signal: controller.signal })
+      .then((decision) => {
+        // Withdrawn by the runtime, or the process is gone: nothing may be written for it.
+        if (controller.signal.aborted || this._proc !== proc || !this._alive) return;
+        this._inbound.delete(requestId);
+        this._writeControlResponse(proc, requestId, this._toolResponse(request, decision));
+      })
+      .finally(() => {
+        if (this._inbound.get(requestId) === controller) this._inbound.delete(requestId);
+      });
+  }
+
+  private _toolResponse(
+    request: Omit<ToolRequest, 'signal'>,
+    decision: ToolDecision | undefined,
+  ): Record<string, unknown> {
+    if (request.stage === 'pre-use')
+      return decision?.behavior === 'deny'
+        ? {
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              permissionDecision: 'deny',
+              permissionDecisionReason: decision.message,
+            },
+          }
+        : {};
+    return decision?.behavior === 'allow'
+      ? { behavior: 'allow', updatedInput: structuredClone(request.toolInput) }
+      : { behavior: 'deny', message: decision?.message ?? 'Denied' };
+  }
+
+  private _writeControlResponse(
+    proc: PipedSubprocess,
+    requestId: string,
+    response: Record<string, unknown>,
+  ): void {
+    try {
+      proc.stdin.write(
+        `${JSON.stringify({
+          type: 'control_response',
+          response: { subtype: 'success', request_id: requestId, response },
+        })}\n`,
+      );
+      proc.stdin.flush();
+    } catch {
+      /* transport failure surfaces on the stream */
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Private — spawn args (called once at start())
   // ---------------------------------------------------------------------------
@@ -1115,6 +1308,7 @@ export class ClaudeCodeSession implements HarnessSession {
       '--permission-mode',
       this._permissionMode,
       '--include-hook-events',
+      ...(this._toolGate ? ['--permission-prompt-tool', 'stdio'] : []),
     ];
 
     // Resume for fork or crash recovery. _externalSessionId is set from

package/src/codex-session.ts

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from 'node:util';
 import { codexLimitSnapshot, type LimitSnapshot, mergeLimits } from './limits';
 import { retainEvidence } from './retained-evidence';
+import { ToolGates } from './tool-gate';
 import { TRANSPORTS } from './transport';
 import { TurnState } from './turn-state';
 // ---------------------------------------------------------------------------
@@ -40,6 +41,7 @@ import type {
   SessionEvent,
   SessionEventHandler,
   SessionResult,
+  ToolGate,
 } from './harness-session';
 
 // Re-export types so importers can stay on one path (mirrors claude-code-session).
@@ -63,6 +65,40 @@ export interface PipedSubprocess {
   kill(): void;
 }
 
+export type CodexApprovalPolicy = 'never' | 'on-request' | 'untrusted';
+export type CodexSandbox = 'read-only' | 'workspace-write' | 'danger-full-access';
+export type HostPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'bypassPermissions';
+
+/**
+ * The app-server approval policy and sandbox for a host permission mode (Claude's mode ids).
+ * `acceptEdits` maps like `default`: under workspace-write, edits inside the workspace are never
+ * asked about; only escalations (writes outside it, commands needing more access) reach the gates.
+ */
+export function codexPermissions(mode: HostPermissionMode): {
+  approvalPolicy: CodexApprovalPolicy;
+  sandbox: CodexSandbox;
+} {
+  switch (mode) {
+    case 'default':
+    case 'acceptEdits':
+      return { approvalPolicy: 'on-request', sandbox: 'workspace-write' };
+    case 'plan':
+      return { approvalPolicy: 'never', sandbox: 'read-only' };
+    case 'bypassPermissions':
+      return { approvalPolicy: 'never', sandbox: 'danger-full-access' };
+  }
+}
+
+const SANDBOX_TYPES: Record<CodexSandbox, string> = {
+  'read-only': 'readOnly',
+  'workspace-write': 'workspaceWrite',
+  'danger-full-access': 'dangerFullAccess',
+};
+const APPROVAL_METHODS = new Set([
+  'item/commandExecution/requestApproval',
+  'item/fileChange/requestApproval',
+]);
+
 export type CodexSpawn = (
   cmd: string[],
   opts: { cwd: string; env: Record<string, string | undefined> },
@@ -81,6 +117,17 @@ export interface CodexSessionConfig {
     requireConfiguration?: boolean;
     config?: Readonly<Record<string, unknown>>;
     requiredMcpServer?: { readonly name: string; readonly tools: readonly string[] };
+    /**
+     * Native approval policy and sandbox for the thread. Default `never` / `danger-full-access`.
+     * With `on-request` or `untrusted`, approval requests go to the gates registered through
+     * onToolRequest() (stage `permission` only; Codex has no pre-use stage); with none registered
+     * they are declined. The thread is started with `approvalsReviewer: "user"` and refused if the
+     * runtime reports another reviewer (a config.toml `approvals_reviewer` would bypass the gates).
+     * Under `never` nothing reaches a gate and onToolRequest() throws.
+     * `codexPermissions(mode)` maps the host permission modes.
+     */
+    approvalPolicy?: CodexApprovalPolicy;
+    sandbox?: CodexSandbox;
   };
   /** Path to codex CLI binary. Defaults to "codex". */
   bin?: string;
@@ -304,6 +351,7 @@ abstract class BaseCodexSession implements HarnessSession {
     this._rejectQueue(new Error('Session killed'));
     for (const p of this._pending.values()) p.reject(new Error('Session killed'));
     this._pending.clear();
+    this._withdrawRequests();
 
     try {
       this._proc.stdin.end();
@@ -388,6 +436,7 @@ abstract class BaseCodexSession implements HarnessSession {
       this._rejectQueue(new Error('Session ended'));
       for (const p of this._pending.values()) p.reject(new Error('Session ended'));
       this._pending.clear();
+      this._withdrawRequests();
       this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
     });
 
@@ -595,6 +644,7 @@ abstract class BaseCodexSession implements HarnessSession {
     this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
     for (const p of this._pending.values()) p.reject(err);
     this._pending.clear();
+    this._withdrawRequests();
   }
 
   protected _rejectQueue(err: Error): void {
@@ -791,6 +841,9 @@ abstract class BaseCodexSession implements HarnessSession {
 
   protected _observeRpcResult(_id: number, _result: unknown): void {}
 
+  /** The process is gone (kill, exit, transport failure): withdraw server requests still pending. */
+  protected _withdrawRequests(): void {}
+
   /** Shared fork constructor — subclass passes its own ctor. */
   fork(opts?: { cwd?: string; baseContext?: string }): HarnessSession {
     if (this._inflight) throw new Error('Cannot fork while native ownership is unresolved');
@@ -1237,6 +1290,11 @@ export class CodexAppServerSession extends BaseCodexSession {
   private _nativeSessionId?: string;
   private _appAdmission?: string;
   private _turnDone?: () => void;
+  private _gates = new ToolGates();
+  /** Approval requests awaiting a gate decision, by JSON-RPC request id. */
+  private _approvals = new Map<string, AbortController>();
+  /** The owned turn's in-progress fileChange items' changes, by item id, for their approvals. */
+  private _fileChanges = new Map<string, readonly CodexFileChange[]>();
   private _items = new Map<
     string,
     {
@@ -1284,7 +1342,113 @@ export class CodexAppServerSession extends BaseCodexSession {
     }
   }
 
+  /** Needs an `approvalPolicy` other than `never`. Gates registered here are not copied (no fork). */
+  onToolRequest(gate: ToolGate): () => void {
+    if (this._approvalPolicy === 'never')
+      throw new Error(
+        'Tool gates need an app-server session launched with approvalPolicy "on-request" or "untrusted"; under "never" no approval reaches them',
+      );
+    return this._gates.add(gate);
+  }
+
+  protected override _withdrawRequests(): void {
+    for (const approval of this._approvals.values()) approval.abort();
+    this._approvals.clear();
+  }
+
+  private get _approvalPolicy(): CodexApprovalPolicy {
+    return this._options.approvalPolicy ?? 'never';
+  }
+
+  /** Approval requests are asked of this client, so they must reach the gates. */
+  private get _gated(): boolean {
+    return this._approvalPolicy !== 'never';
+  }
+
+  private get _sandbox(): CodexSandbox {
+    return this._options.sandbox ?? 'danger-full-access';
+  }
+
+  /** A command or file-change approval for the owned turn, decided by the gates. */
+  private _approval(request: Record<string, unknown>): boolean {
+    const method = request.method as string;
+    const params = object(request.params);
+    const a = this._inflight?.evidence;
+    if (
+      !APPROVAL_METHODS.has(method) ||
+      !a?.identity.turnId ||
+      params?.threadId !== a.identity.threadId ||
+      params?.turnId !== a.identity.turnId ||
+      (typeof request.id !== 'string' && typeof request.id !== 'number')
+    )
+      return false;
+    const str = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    const command = method === 'item/commandExecution/requestApproval';
+    const network = object(params.networkApprovalContext);
+    const host = str(network?.host),
+      protocol = str(network?.protocol);
+    const changes = str(params.itemId) ? this._fileChanges.get(params.itemId as string) : undefined;
+    const toolInput: Record<string, unknown> = command
+      ? {
+          ...(str(params.command) ? { command: params.command } : {}),
+          ...(str(params.cwd) ? { cwd: params.cwd } : {}),
+          ...(str(params.kind) ? { kind: params.kind } : {}),
+          ...(host ? { networkApprovalContext: { host, ...(protocol ? { protocol } : {}) } } : {}),
+        }
+      : {
+          ...(str(params.grantRoot) ? { grantRoot: params.grantRoot } : {}),
+          ...(changes ? { changes: structuredClone(changes) } : {}),
+        };
+    const proc = this._proc;
+    const id = request.id;
+    const key = JSON.stringify(id);
+    const controller = new AbortController();
+    this._approvals.get(key)?.abort();
+    this._approvals.set(key, controller);
+    const identity = { ...a.identity, admissionId: a.admissionId };
+    this._emit({
+      ...identity,
+      kind: 'native_status',
+      timestamp: Date.now(),
+      raw: { type: 'approval-request', method },
+    });
+    void this._gates
+      .decide({
+        stage: 'permission',
+        toolName: command ? 'shell' : 'apply_patch',
+        toolInput: Object.freeze(toolInput),
+        ...(str(params.itemId) ? { callId: params.itemId as string } : {}),
+        admissionId: a.admissionId,
+        ...(str(params.reason) ? { description: params.reason as string } : {}),
+        signal: controller.signal,
+      })
+      .then((decision) => {
+        if (controller.signal.aborted || this._proc !== proc || !this._alive || !proc) return;
+        this._approvals.delete(key);
+        const accepted = decision?.behavior === 'allow';
+        try {
+          proc.stdin.write(
+            `${JSON.stringify({ jsonrpc: '2.0', id, result: { decision: accepted ? 'accept' : 'decline' } })}\n`,
+          );
+          proc.stdin.flush();
+        } catch {
+          return;
+        }
+        this._emit({
+          ...identity,
+          kind: 'native_status',
+          timestamp: Date.now(),
+          raw: { type: 'approval-response', method, decision: accepted ? 'accept' : 'decline' },
+        });
+      })
+      .finally(() => {
+        if (this._approvals.get(key) === controller) this._approvals.delete(key);
+      });
+    return true;
+  }
+
   protected override _serverRequest(request: Record<string, unknown>): boolean {
+    if (this._approval(request)) return true;
     // JSON-RPC's explicit method-not-supported refusal also covers unknown future
     // requests. Never approve native work or echo private request parameters.
     const payload = `${JSON.stringify({
@@ -1435,8 +1599,10 @@ export class CodexAppServerSession extends BaseCodexSession {
           ...(binding ? { threadId: binding } : {}),
           model: this._model,
           cwd: this._cwd,
-          approvalPolicy: 'never',
-          sandbox: 'danger-full-access',
+          approvalPolicy: this._approvalPolicy,
+          // Approvals go to the gates, never to a config-selected reviewer (auto_review, guardian).
+          ...(this._gated ? { approvalsReviewer: 'user' } : {}),
+          sandbox: this._sandbox,
           ...(this._options.config ? { config: this._options.config } : {}),
         }),
       );
@@ -1458,6 +1624,16 @@ export class CodexAppServerSession extends BaseCodexSession {
             ? String(object(thread?.status)?.type)
             : 'unknown',
         );
+      if (
+        this._gated &&
+        (response?.approvalsReviewer !== 'user' || response.approvalPolicy !== this._approvalPolicy)
+      )
+        this._refuse(
+          'approvals-not-routed-to-user',
+          ['user', 'auto_review', 'guardian_subagent'].includes(String(response?.approvalsReviewer))
+            ? String(response?.approvalsReviewer)
+            : 'unknown',
+        );
       if (
         this._options.requireConfiguration &&
         (typeof response?.model !== 'string' ||
@@ -1465,9 +1641,9 @@ export class CodexAppServerSession extends BaseCodexSession {
           typeof response.modelProvider !== 'string' ||
           !response.modelProvider ||
           response.cwd !== this._cwd ||
-          response.approvalPolicy !== 'never' ||
+          response.approvalPolicy !== this._approvalPolicy ||
           response.approvalsReviewer !== 'user' ||
-          object(response.sandbox)?.type !== 'dangerFullAccess' ||
+          object(response.sandbox)?.type !== SANDBOX_TYPES[this._sandbox] ||
           !Array.isArray(thread?.turns) ||
           thread.turns.some((value) => !this._turn(value)))
       )
@@ -1587,6 +1763,13 @@ export class CodexAppServerSession extends BaseCodexSession {
       const snapshot = codexLimitSnapshot(msg.params, 'stream');
       return snapshot ? [this._observeLimits(snapshot)] : [];
     }
+    if (method === 'serverRequest/resolved') {
+      // The runtime settled or withdrew an approval itself: a later gate decision is discarded.
+      const requestId = object(msg.params)?.requestId;
+      const key = JSON.stringify(requestId);
+      this._approvals.get(key)?.abort();
+      this._approvals.delete(key);
+    }
     const params = object(msg.params),
       turn = this._turn(params?.turn),
       item = object(params?.item);
@@ -1645,6 +1828,7 @@ export class CodexAppServerSession extends BaseCodexSession {
       if (turn.error != null && typeof error?.message !== 'string')
         return unowned('unrecognized-event');
       this._seenTerminals.add(turnId);
+      this._fileChanges.clear();
       this._turnDone?.();
       this._turnDone = undefined;
       return [
@@ -1703,8 +1887,19 @@ export class CodexAppServerSession extends BaseCodexSession {
         },
       ];
     }
+    if (method === 'item/fileChange/patchUpdated') {
+      // Changes only feed the item's approval request; the event itself stays a diagnostic.
+      if (itemId && this._fileChanges.has(itemId))
+        this._fileChanges.set(itemId, fileChanges(params?.changes));
+      return unowned('unrecognized-event');
+    }
     if (method === 'item/completed' || method === 'item/started') {
       if (!itemId || !item || typeof item.type !== 'string') return unowned('unrecognized-event');
+      if (item.type === 'fileChange') {
+        if (method === 'item/started') this._fileChanges.set(itemId, fileChanges(item.changes));
+        else this._fileChanges.delete(itemId);
+        return unowned('unrecognized-event');
+      }
       if (item.type === 'agentMessage') {
         if (method !== 'item/completed') return status();
         if (this._items.get(itemId)?.completed) return unowned('after-terminal');
@@ -1844,6 +2039,49 @@ const object = (value: unknown): Record<string, unknown> | undefined =>
     ? (value as Record<string, unknown>)
     : undefined;
 
+/** A fileChange item's change as a file-change gate sees it (`toolInput.changes`). */
+export interface CodexFileChange {
+  readonly path: string;
+  readonly kind: 'add' | 'delete' | 'update';
+  /** Rename target of an `update`. */
+  readonly movePath?: string;
+  /** Unified diff, present while it fits the bound; otherwise `diffOmitted`. */
+  readonly diff?: string;
+  readonly diffOmitted?: true;
+}
+const FILE_CHANGE_DIFF_LIMIT = 16 * 1024;
+const FILE_CHANGE_DIFF_TOTAL = 64 * 1024;
+
+/** Native FileUpdateChange[] (codex 0.155.1) → CodexFileChange[]; diffs only within the bound. */
+function fileChanges(value: unknown): readonly CodexFileChange[] {
+  if (!Array.isArray(value)) return [];
+  let budget = FILE_CHANGE_DIFF_TOTAL;
+  const out: CodexFileChange[] = [];
+  for (const entry of value) {
+    const change = object(entry);
+    const kind = object(change?.kind);
+    if (
+      typeof change?.path !== 'string' ||
+      !change.path ||
+      (kind?.type !== 'add' && kind?.type !== 'delete' && kind?.type !== 'update')
+    )
+      continue;
+    const diff = typeof change.diff === 'string' ? change.diff : undefined;
+    const fits =
+      diff !== undefined && diff.length <= FILE_CHANGE_DIFF_LIMIT && diff.length <= budget;
+    if (fits) budget -= diff.length;
+    out.push({
+      path: change.path,
+      kind: kind.type,
+      ...(kind.type === 'update' && typeof kind.move_path === 'string' && kind.move_path
+        ? { movePath: kind.move_path }
+        : {}),
+      ...(fits ? { diff } : diff ? { diffOmitted: true as const } : {}),
+    });
+  }
+  return out;
+}
+
 function publicMcpArguments(value: unknown): Pick<SessionEvent, 'toolInput' | 'toolInputOmitted'> {
   if (!object(value)) return { toolInputOmitted: 'Native arguments absent or not an object' };
   let omitted = false;

package/src/harness-session.ts

@@ -232,6 +232,47 @@ export interface SessionSendOptions {
   onAdmission?: (attempt: SessionAttempt) => void | Promise<void>;
 }
 
+// ---------------------------------------------------------------------------
+// Tool gate — per-call decisions from the runtime's native approval channel
+// ---------------------------------------------------------------------------
+
+export interface ToolRequest {
+  /**
+   * `pre-use` (Claude only; Codex has no pre-use stage): before every tool call, in every
+   * permission mode (bypass included). Only a deny counts; an allow leaves the runtime's own mode
+   * to decide. `permission`: the runtime's own mode would ask the user; the decision is final.
+   */
+  readonly stage: 'pre-use' | 'permission';
+  readonly toolName: string;
+  /** `mcp__<server>__<tool>` split, as tool_use events carry it. */
+  readonly toolServer?: string;
+  readonly toolMethod?: string;
+  readonly toolInput: Readonly<Record<string, unknown>>;
+  /** Native tool_use id (Claude) or item id (Codex). */
+  readonly callId?: string;
+  /** The in-flight admission, when one is attributable. */
+  readonly admissionId?: string;
+  /** The runtime's own description of, or reason for, the call. */
+  readonly description?: string;
+  /** Claude `can_use_tool` decision_reason: why the runtime's mode escalated to an ask. */
+  readonly decisionReason?: string;
+  /** Claude `can_use_tool` blocked_path. */
+  readonly blockedPath?: string;
+  /** Claude subagent id (`agent_id`) when a subagent, not the main thread, makes the call. */
+  readonly agentId?: string;
+  /**
+   * Aborted when the runtime withdraws the request or the session ends; a later decision is
+   * discarded. A turn timeout does not withdraw a pending Claude ask; interruptNative() does
+   * (the CLI sends control_cancel_request).
+   */
+  readonly signal?: AbortSignal;
+}
+export type ToolDecision =
+  | { readonly behavior: 'allow' }
+  | { readonly behavior: 'deny'; readonly message: string };
+/** Gates compose in registration order: the first deny wins; a thrown or rejected gate denies. */
+export type ToolGate = (request: ToolRequest) => ToolDecision | Promise<ToolDecision>;
+
 // ---------------------------------------------------------------------------
 // HarnessSession interface
 // ---------------------------------------------------------------------------
@@ -277,7 +318,8 @@ export interface HarnessSession {
 
   /**
    * Fork: create a new (unstarted) session branching from current state.
-   * Caller must call start() on the forked session.
+   * Caller must call start() on the forked session. A fork starts with a snapshot of the
+   * parent's tool gates; gates registered or unregistered afterwards on either side stay local.
    */
   fork(opts?: { cwd?: string; baseContext?: string }): HarnessSession;
 
@@ -297,6 +339,14 @@ export interface HarnessSession {
    */
   onBeforeSend(hook: BeforeSendHook): () => void;
 
+  /**
+   * Register a tool gate. Present where the transport declares `approvals: "callback"`; the
+   * session must be launched for callbacks (Claude: `toolGate: true`; Codex app-server: an
+   * `approvalPolicy` other than `never`), otherwise this throws. Forks copy the gates registered
+   * at fork() time. Returns an unregister function.
+   */
+  onToolRequest?(gate: ToolGate): () => void;
+
   /**
    * Mid-turn push: out-of-band signal injected into an in-flight turn.
    * Used by guards and Herald to deliver urgent feedback. Best-effort —

package/src/index.ts

@@ -30,11 +30,16 @@ export {
 // Codex CLI adapter (persistent JSON-RPC session). CodexSession defaults to the
 // mcp-server variant; CodexAppServerSession is the app-server one.
 export {
+  type CodexApprovalPolicy,
   CodexAppServerSession,
+  type CodexFileChange,
   CodexMcpSession,
+  type CodexSandbox,
   CodexSession,
   type CodexSessionConfig,
   type CodexSpawn,
+  codexPermissions,
+  type HostPermissionMode,
 } from './codex-session';
 // The provider-agnostic interface + event taxonomy.
 export * from './harness-session';

package/src/pool.ts

@@ -19,12 +19,14 @@ import type { HarnessSession } from './harness-session';
 import { type LimitSnapshot, mergeLimits } from './limits';
 import { probeClaudeLimits, probeCodexLimits } from './limits-probe';
 import {
+  type BillingMode,
   type ExclusionReason,
   type OrderingSpec,
   type RankedCandidate,
   type ResolvedOrdering,
   rankCandidates,
   type SubscriptionCandidate,
+  type UnknownUtilizationPolicy,
 } from './routing';
 import { TRANSPORTS, type TransportKind } from './transport';
 import { createSession } from './transports';
@@ -66,6 +68,9 @@ export interface PoolRequest {
   readonly ordering?: OrderingSpec;
   /** Only the preferred instance may serve. Requires preferredInstanceId. */
   readonly pinned?: boolean;
+  /** Billing modes this request may use. Default: subscription only. */
+  readonly allowedBilling?: readonly BillingMode[];
+  readonly unknownUtilization?: UnknownUtilizationPolicy;
   /** Restrict to these transports (e.g. only resumable ones). */
   readonly transports?: readonly TransportKind[];
   readonly excludeInstanceIds?: readonly string[];
@@ -228,6 +233,8 @@ export class SubscriptionPool {
       const limit = config.concurrencyLimit ?? 1;
       if (!Number.isSafeInteger(limit) || limit < 1)
         throw Error(`Instance ${config.id}: concurrencyLimit must be a positive integer`);
+      if (config.priority !== undefined && !Number.isSafeInteger(config.priority))
+        throw Error(`Instance ${config.id}: priority must be a safe integer`);
       this._instances.set(config.id, {
         config,
         runtime,
@@ -332,6 +339,10 @@ export class SubscriptionPool {
         maximumObservationAgeMs: this._maxAge,
         ordering: request.ordering,
         ...(request.pinned !== undefined ? { pinned: request.pinned } : {}),
+        ...(request.allowedBilling !== undefined ? { allowedBilling: request.allowedBilling } : {}),
+        ...(request.unknownUtilization !== undefined
+          ? { unknownUtilization: request.unknownUtilization }
+          : {}),
         organizationId: request.organizationId,
         preferredId: request.preferredInstanceId,
       },

package/src/routing.ts

@@ -74,9 +74,8 @@ const ROUTING_FIELDS = Object.keys(NATURAL_DIRECTION) as RoutingField[];
 /** Resolve a strategy name or explicit term list into terms, each with a direction. */
 export const resolveOrdering = (spec: OrderingSpec = DEFAULT_STRATEGY): ResolvedOrdering => {
   if (typeof spec === 'string') {
-    const preset = ROUTING_STRATEGIES[spec];
-    if (!preset) throw Error(`Unknown routing strategy "${spec}"`);
-    return resolveOrdering(preset);
+    if (!Object.hasOwn(ROUTING_STRATEGIES, spec)) throw Error(`Unknown routing strategy "${spec}"`);
+    return resolveOrdering(ROUTING_STRATEGIES[spec]);
   }
   if (!spec.length) throw Error('Ordering requires at least one term');
   return spec.map((term) => {
@@ -228,7 +227,7 @@ export function repositoryIdentity(remote: string): string {
   return `${url.hostname.toLowerCase()}/${normalized}`;
 }
 
-/** Why one candidate is ineligible, or undefined with its utilization when eligible. */
+/** Why one candidate is ineligible, or its utilization when eligible. */
 export function assessCandidate(
   request: CandidateRequest,
   account: SubscriptionCandidate,
@@ -257,13 +256,13 @@ export function assessCandidate(
     return { excluded: 'unavailable' };
   if (account.activeRuns >= account.concurrencyLimit) return { excluded: 'occupied' };
   if (account.blocked) return { excluded: 'blocked' };
-  const unreadable = request.unknownUtilization === 'rank-last' ? null : undefined;
-  if (account.windows.length === 0) {
-    if (unreadable === undefined) return { excluded: 'no-observation' };
-    return { utilizationPercent: null };
-  }
-  const fractions: number[] = [];
+  const rankLast = request.unknownUtilization === 'rank-last';
+  if (account.windows.length === 0)
+    return rankLast ? { utilizationPercent: null } : { excluded: 'no-observation' };
+  const readable: number[] = [];
+  let unreadable = false;
   for (const window of account.windows) {
+    // Corrupt is not unknown: a structurally impossible reading is never routable under any policy.
     if (
       window.usedPercent === null ||
       !Number.isFinite(window.usedPercent) ||
@@ -272,7 +271,7 @@ export function assessCandidate(
       !Number.isFinite(window.reservedPercent) ||
       window.reservedPercent < 0
     )
-      return unreadable === undefined ? { excluded: 'invalid' } : { utilizationPercent: null };
+      return { excluded: 'invalid' };
     // resetsAt === Infinity: the provider reported no reset for this window, so no reset can have crossed the observation.
     if (
       !Number.isFinite(window.observedAt) ||
@@ -280,14 +279,17 @@ export function assessCandidate(
       request.now - window.observedAt > request.maximumObservationAgeMs ||
       (window.resetsAt !== Number.POSITIVE_INFINITY &&
         (!Number.isFinite(window.resetsAt) || window.resetsAt <= request.now))
-    )
-      return unreadable === undefined
-        ? { excluded: 'stale-observation' }
-        : { utilizationPercent: null };
-    fractions.push(window.usedPercent + window.reservedPercent);
+    ) {
+      if (!rankLast) return { excluded: 'stale-observation' };
+      unreadable = true;
+      continue;
+    }
+    readable.push(window.usedPercent + window.reservedPercent);
   }
-  if (fractions.some((p) => p >= 100)) return { excluded: 'exhausted' };
-  return { utilizationPercent: Math.max(...fractions) };
+  // A window that is readable and full exhausts the instance even when another is not.
+  if (readable.some((p) => p >= 100)) return { excluded: 'exhausted' };
+  if (unreadable || !readable.length) return { utilizationPercent: null };
+  return { utilizationPercent: Math.max(...readable) };
 }
 
 /** Term fields as own properties, so json-rules orders them by name. */
@@ -318,6 +320,8 @@ export function rankCandidates(
     throw Error('Invalid observation policy');
   if (request.pinned && !request.preferredId)
     throw Error('Pinned routing requires a preferred instance');
+  if (request.allowedBilling?.length === 0)
+    throw Error('Ordering requires at least one billing mode');
   if (new Set(accounts.map((a) => a.id)).size !== accounts.length)
     throw Error('Duplicate account identity');
   const ordering = resolveOrdering(request.ordering);

package/src/tool-gate.ts

@@ -0,0 +1,61 @@
+import type { ToolDecision, ToolGate, ToolRequest } from './harness-session';
+
+/**
+ * A session's registered tool gates. They compose in registration order and the first deny
+ * wins; a gate that throws or rejects denies. `pre-use` with no deny is no decision (the
+ * runtime's own mode decides); `permission` with no gate registered is denied.
+ */
+export class ToolGates {
+  private readonly _gates: ToolGate[] = [];
+
+  get size(): number {
+    return this._gates.length;
+  }
+
+  add(gate: ToolGate): () => void {
+    this._gates.push(gate);
+    return () => {
+      const index = this._gates.indexOf(gate);
+      if (index !== -1) this._gates.splice(index, 1);
+    };
+  }
+
+  /** The gates in order, for a sibling session (fork). */
+  list(): readonly ToolGate[] {
+    return [...this._gates];
+  }
+
+  /** Never rejects. Undefined means no decision: only a `pre-use` request without a deny. */
+  async decide(request: ToolRequest): Promise<ToolDecision | undefined> {
+    const gates = [...this._gates];
+    if (!gates.length)
+      return request.stage === 'permission'
+        ? { behavior: 'deny', message: 'No approval handler' }
+        : undefined;
+    for (const gate of gates) {
+      let decision: ToolDecision;
+      try {
+        decision = await gate(request);
+      } catch (error) {
+        return {
+          behavior: 'deny',
+          message: `Tool gate failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+      if (decision?.behavior === 'deny')
+        return { behavior: 'deny', message: String(decision.message ?? 'Denied') };
+      if (decision?.behavior !== 'allow')
+        return { behavior: 'deny', message: 'Tool gate failed: malformed decision' };
+    }
+    return request.stage === 'permission' ? { behavior: 'allow' } : undefined;
+  }
+}
+
+/** `mcp__<server>__<tool>` split into its server and method. */
+export function mcpToolParts(toolName: string): { toolServer?: string; toolMethod?: string } {
+  if (!toolName.startsWith('mcp__')) return {};
+  const rest = toolName.slice(5);
+  const split = rest.indexOf('__');
+  if (split <= 0 || split + 2 >= rest.length) return {};
+  return { toolServer: rest.slice(0, split), toolMethod: rest.slice(split + 2) };
+}

package/src/transport.ts

@@ -34,7 +34,7 @@ export interface TransportCapabilities {
   readonly interrupt: 'acknowledged' | 'local-only';
   /** `steer`: push() adds input to the in-flight turn; `none`: push() records push_ignored. */
   readonly push: 'steer' | 'none';
-  /** `callback`: per-call decision hook; `mode`: a fixed launch policy (bypass); `refuse`: runtime requests are refused. */
+  /** `callback`: per-call decisions through onToolRequest(); `mode`: a fixed launch policy (bypass); `refuse`: runtime requests are refused. */
   readonly approvals: 'callback' | 'mode' | 'refuse';
   /** Token usage reported per turn. */
   readonly usage: boolean;
@@ -72,7 +72,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       rollback: 'none',
       interrupt: 'acknowledged',
       push: 'none',
-      approvals: 'mode',
+      approvals: 'callback',
       usage: true,
       limits: { stream: true, poll: true },
       textOnly: true,
@@ -84,7 +84,8 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       'textOnly launches with no tools, MCP servers, slash commands or user settings.',
       'Primed decisions (ClaudePrimedSessions) fork a persisted primed session per cycle with a pre-spawned spare.',
       "interruptNative() and readLimits() use the CLI's stdio control protocol (`interrupt`, `get_usage`).",
-      'Rollback (`--resume-session-at`) and per-call approvals (`--permission-prompt-tool stdio`) exist natively but are not wired here.',
+      'toolGate: true launches with `--permission-prompt-tool stdio` and registers a PreToolUse callback over the control protocol: onToolRequest() gates see every call (`pre-use`, any mode, bypass included; only a deny counts) and the asks the permission mode raises (`permission`, final).',
+      'Rollback (`--resume-session-at`) exists natively but is not wired here.',
     ],
   },
   'codex-mcp': {
@@ -121,7 +122,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       rollback: 'none',
       interrupt: 'acknowledged',
       push: 'steer',
-      approvals: 'refuse',
+      approvals: 'callback',
       usage: true,
       limits: { stream: true, poll: true },
       textOnly: false,
@@ -132,6 +133,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       '`codex app-server --listen stdio://` with thread/start, thread/resume, turn/start.',
       "CodexAppServerSession runs with the profile's tools; tool-free text sessions are CodexPrimedSessions (primed: fork).",
       'interruptNative() sends turn/interrupt; push() sends turn/steer against the owned turn.',
+      'appServer.approvalPolicy/sandbox (default never / danger-full-access; `codexPermissions(mode)`) set the thread policy; command and file-change approvals for the owned turn go to onToolRequest() gates (`permission`) and are answered accept/decline. Other server requests are refused (-32601).',
       'Primed decisions (CodexPrimedSessions) host every key as a thread of one process per account and fork the primed thread per cycle.',
       'thread/rollback is refused by codex-cli 0.155 for both ephemeral and paginated threads; session fork() is not wired.',
     ],