@inixiative/agent-session 0.5.2 → 0.6.1

package/README.md

@@ -2,7 +2,7 @@
 
 Drive coding-agent CLIs as **persistent, streaming, event-captured sessions** —
 one interface, any agent, over interchangeable **transports**. Claude Code
-(CLI or Agent SDK) and Codex (MCP or app-server) today; Gemini and Grok planned.
+(CLI or Agent SDK) and Codex (app-server) today; Gemini and Grok planned.
 Also: warm **primed decision sessions**, **subscription pools** with
 deterministic routing, **limit polling** and **session continuity**.
 
@@ -64,23 +64,56 @@ arrive as `rate_limit` events.
 ```ts
 import { createSession, TRANSPORTS } from "@inixiative/agent-session";
 
-const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk, codex-mcp
+const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk
 if (TRANSPORTS[kind].capabilities.interrupt === "acknowledged") { /* … */ }
 const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOME: profile } });
 ```
 
-| | claude-cli | codex-mcp | codex-app-server | claude-agent-sdk | acp | api |
-|---|---|---|---|---|---|---|
-| Status | ✅ live | ✅ live | ✅ live | ✅ live | stub | stub |
-| Resume / fork | native / native | loaded-only / same-thread | native / – | native / native | – | – |
-| Interrupt | acknowledged | local-only | acknowledged | acknowledged | – | – |
-| Push | – | – | steer | – | – | – |
-| Approvals | mode | mode | refuse | callback | – | – |
-| Limits stream / poll | ✅ / ✅ | – / – | ✅ / ✅ | ✅ / – | – | – |
-| Primed reset | fork | – | fork | – | – | – |
+| | claude-cli | codex-app-server | claude-agent-sdk | acp | api |
+|---|---|---|---|---|---|
+| Status | ✅ live | ✅ live | ✅ live | stub | stub |
+| Resume / fork | native / native | native / – | native / native | – | – |
+| Interrupt | acknowledged | acknowledged | acknowledged | – | – |
+| Push | – | steer | – | – | – |
+| Approvals | callback | callback | callback | – | – |
+| Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
+| Primed reset | fork | fork | – | – | – |
+
+Codex runs only over `codex app-server --listen stdio://` (`CodexAppServerSession`);
+Codex CLI 0.155 has no `mcp-server` subcommand.
 
 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
@@ -144,7 +177,6 @@ snapshots in the artifact but do not fabricate a completed-turn total.
 | Runtime | Status |
 |---|---|
 | Claude Code | ✅ shipped |
-| Codex CLI (`codex mcp-server`, JSON-RPC) | ✅ shipped (`CodexSession`) |
 | Codex app-server | ✅ shipped (`CodexAppServerSession`, `CodexPrimedSessions`) |
 | Claude Agent SDK | ✅ shipped (`ClaudeAgentSdkSession`; caller supplies `query`) |
 | ACP agents / direct API | typed stubs |
@@ -158,7 +190,7 @@ Opaque runtimes degrade gracefully — fewer event types, never a hard failure.
 ## Provenance
 
 Extracted from [`inixiative/foundry`](https://github.com/inixiative/foundry),
-where this drives the Artificer session. Consumed by foundry, foundry-oracle,
+where this drives the Artificer session. Consumed by foundry, oracle,
 and the inixiative bench.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "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",
@@ -36,11 +36,11 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.5.0"
+    "@inixiative/json-rules": "^3.5.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.64",
+    "@inixiative/config": "^0.5.78",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

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

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 // ---------------------------------------------------------------------------
 // ClaudeAgentSdkSession — Claude through @anthropic-ai/claude-agent-sdk
 // ---------------------------------------------------------------------------
@@ -52,7 +53,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> {
@@ -89,6 +91,13 @@ export function sdkOptionsFromArgv(argv: readonly string[]): Record<string, unkn
       case '--append-system-prompt':
         options.systemPrompt = { type: 'preset', preset: 'claude_code', append: value() };
         break;
+      case '--append-system-prompt-file':
+        options.systemPrompt = {
+          type: 'preset',
+          preset: 'claude_code',
+          append: readFileSync(value(), 'utf8'),
+        };
+        break;
       case '--no-session-persistence':
         options.persistSession = false;
         break;
@@ -170,6 +179,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 +278,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 +333,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 +381,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 +406,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',