@inixiative/agent-session 0.5.2 → 0.6.1

package/src/harness-session.ts

@@ -10,7 +10,7 @@
 // HarnessSession is stateful: it owns a running process, tracks turns,
 // captures every event for Oracle, and supports fork/interrupt.
 //
-// Implementations: ClaudeCodeSession, CodexMcpSession, CodexAppServerSession,
+// Implementations: ClaudeCodeSession, CodexAppServerSession,
 // ClaudeAgentSdkSession. How a model is reached is the session's transport
 // (see transport.ts); every transport implements this one contract.
 // ---------------------------------------------------------------------------
@@ -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

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

package/src/pool.ts

@@ -31,7 +31,7 @@ import {
 import { TRANSPORTS, type TransportKind } from './transport';
 import { createSession } from './transports';
 
-export type PooledTransport = 'claude-cli' | 'codex-mcp' | 'codex-app-server' | 'claude-agent-sdk';
+export type PooledTransport = 'claude-cli' | 'codex-app-server' | 'claude-agent-sdk';
 
 export interface InstanceConfig {
   readonly id: string;

package/src/primed.ts

@@ -262,7 +262,7 @@ export class Slots {
   }
 }
 
-/** Per-key serialization: a key's decisions run one at a time, in order. */
+/** Per-key serialization: a key's tasks run one at a time, in order. */
 export class KeyedQueue {
   private _tails = new Map<string, Promise<void>>();
   run<T>(key: string, task: () => Promise<T>): Promise<T> {

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

@@ -13,28 +13,22 @@
 // is declared absent, with a note.
 // ---------------------------------------------------------------------------
 
-export type TransportKind =
-  | 'claude-cli'
-  | 'codex-mcp'
-  | 'codex-app-server'
-  | 'claude-agent-sdk'
-  | 'acp'
-  | 'api';
+export type TransportKind = 'claude-cli' | 'codex-app-server' | 'claude-agent-sdk' | 'acp' | 'api';
 
 export type TransportRuntime = 'claude' | 'codex' | 'external';
 
 export interface TransportCapabilities {
-  /** Continue a thread by native ID in a new process (`loaded-only`: only while the original process holds it). */
-  readonly resume: 'native' | 'loaded-only' | 'none';
-  /** `native`: a new branch with its own ID; `same-thread`: continues the parent thread (not a real fork). */
-  readonly fork: 'native' | 'same-thread' | 'none';
+  /** Continue a thread by native ID in a new process. */
+  readonly resume: 'native' | 'none';
+  /** `native`: a new branch with its own ID. */
+  readonly fork: 'native' | 'none';
   /** Drop the last N turns of native history. */
   readonly rollback: 'native' | 'none';
   /** `acknowledged`: interruptNative() confirms the stop through the turn's terminal; `local-only`: interrupt() releases the local waiter only. */
   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 +66,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,30 +78,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.',
-    ],
-  },
-  'codex-mcp': {
-    kind: 'codex-mcp',
-    runtime: 'codex',
-    status: 'implemented',
-    verified: 'live',
-    capabilities: {
-      resume: 'loaded-only',
-      fork: 'same-thread',
-      rollback: 'none',
-      interrupt: 'local-only',
-      push: 'none',
-      approvals: 'mode',
-      usage: true,
-      limits: none,
-      textOnly: false,
-      primed: 'none',
-      billing: 'subscription',
-    },
-    notes: [
-      '`codex mcp-server`; `codex-reply` continues only threads loaded in the same process.',
-      'fork() continues the parent thread; it is not a native fork.',
+      '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-app-server': {
@@ -121,7 +93,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 +104,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.',
     ],

package/src/transports.ts

@@ -6,7 +6,7 @@ import {
   type ClaudeAgentSdkSessionConfig,
 } from './claude-agent-sdk-session';
 import { ClaudeCodeSession, type ClaudeCodeSessionConfig } from './claude-code-session';
-import { CodexAppServerSession, CodexMcpSession, type CodexSessionConfig } from './codex-session';
+import { CodexAppServerSession, type CodexSessionConfig } from './codex-session';
 import type { HarnessSession } from './harness-session';
 import {
   TRANSPORTS,
@@ -36,7 +36,6 @@ export interface ApiSessionConfig {
 
 export interface TransportConfigs {
   'claude-cli': ClaudeCodeSessionConfig;
-  'codex-mcp': CodexSessionConfig;
   'codex-app-server': CodexSessionConfig;
   'claude-agent-sdk': ClaudeAgentSdkSessionConfig;
   acp: AcpSessionConfig;
@@ -81,8 +80,6 @@ export function createSession<K extends TransportKind>(
   switch (kind) {
     case 'claude-cli':
       return new ClaudeCodeSession(config as ClaudeCodeSessionConfig);
-    case 'codex-mcp':
-      return new CodexMcpSession(config as CodexSessionConfig);
     case 'codex-app-server':
       return new CodexAppServerSession(config as CodexSessionConfig);
     case 'claude-agent-sdk':