@inixiative/agent-session 0.5.2 → 0.6.1

package/src/claude-code-session.ts

@@ -1,3 +1,6 @@
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import {
   claudeRateLimitSnapshot,
   claudeUsageSnapshot,
@@ -5,6 +8,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 +57,9 @@ import type {
   SessionResult,
   SessionSendOptions,
   SessionTokens,
+  ToolDecision,
+  ToolGate,
+  ToolRequest,
 } from './harness-session';
 
 // Re-export types so existing import paths keep working
@@ -88,7 +95,8 @@ export interface ClaudeCodeSessionConfig {
   /**
    * Base context to pre-load at session startup.
    *
-   * Injected via --append-system-prompt on process spawn. Persists for the
+   * Injected via --append-system-prompt-file on process spawn (a private 0600 file, removed when the
+   * process ends), so a base past Linux's 128 KiB per-argument limit still starts. Persists for the
    * entire session lifetime. Include all stable context here (system,
    * conventions, memory, architecture) so per-message delta is minimal.
    */
@@ -113,6 +121,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.
@@ -246,12 +262,19 @@ export class ClaudeCodeSession implements HarnessSession {
   private _permissionMode: string;
   private _defaultTimeout: number;
   private _baseContext?: string;
+  /** The private directory holding the base context file while a process runs. */
+  private _baseContextDir?: string;
   private _forking = false;
   private _awaitingForkIdentity = false;
   private _spawn?: ClaudeCodeSessionConfig['spawn'];
   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 +348,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 +401,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 () => {
@@ -422,16 +454,21 @@ export class ClaudeCodeSession implements HarnessSession {
     delete env.ANTHROPIC_AUTH_TOKEN;
     for (const key of Object.keys(env)) if (env[key] === undefined) delete env[key];
 
-    if (this._spawn) {
-      this._proc = this._spawn([this._bin, ...args], { cwd: this._cwd, env });
-    } else {
-      this._proc = Bun.spawn([this._bin, ...args], {
-        cwd: this._cwd,
-        stdin: 'pipe',
-        stdout: 'pipe',
-        stderr: 'pipe',
-        env,
-      }) as unknown as PipedSubprocess;
+    try {
+      if (this._spawn) {
+        this._proc = this._spawn([this._bin, ...args], { cwd: this._cwd, env });
+      } else {
+        this._proc = Bun.spawn([this._bin, ...args], {
+          cwd: this._cwd,
+          stdin: 'pipe',
+          stdout: 'pipe',
+          stderr: 'pipe',
+          env,
+        }) as unknown as PipedSubprocess;
+      }
+    } catch (error) {
+      this._removeBaseContext();
+      throw error;
     }
 
     this._alive = true;
@@ -444,7 +481,10 @@ export class ClaudeCodeSession implements HarnessSession {
     this._readStderr();
 
     // Monitor process exit for cleanup
+    // The process read its base context file at startup; it goes when the process does.
+    const baseDir = this._baseContextDir;
     proc.exited.then(async (code) => {
+      this._removeBaseContext(baseDir);
       if (this._proc !== proc || !this._alive) return;
       this._alive = false;
       await stdoutDone; // Drain buffered terminal evidence before interpreting process exit.
@@ -456,11 +496,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 +589,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 +617,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;
   }
@@ -687,6 +748,7 @@ export class ClaudeCodeSession implements HarnessSession {
       /* already dead */
     }
     this._proc = null;
+    this._removeBaseContext();
 
     this._emit({ kind: 'session_end', timestamp: Date.now() });
   }
@@ -930,9 +992,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 +1179,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 +1323,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
@@ -1134,12 +1343,32 @@ export class ClaudeCodeSession implements HarnessSession {
 
     // Stable base context injected once at process startup
     if (this._baseContext) {
-      args.push('--append-system-prompt', this._baseContext);
+      args.push('--append-system-prompt-file', this._writeBaseContext(this._baseContext));
     }
 
     return args;
   }
 
+  /** The base context as a private file: argv carries its path, never its text. */
+  private _writeBaseContext(text: string): string {
+    this._removeBaseContext();
+    if (!swept) {
+      swept = true;
+      sweepOrphanedBaseContexts();
+    }
+    this._baseContextDir = mkdtempSync(join(tmpdir(), `${BASE_CONTEXT_PREFIX}${process.pid}-`));
+    const file = join(this._baseContextDir, 'append-system-prompt.md');
+    writeFileSync(file, text, { mode: 0o600 });
+    return file;
+  }
+
+  /** Remove a spawn's base context directory: the current one by default. */
+  private _removeBaseContext(dir = this._baseContextDir): void {
+    if (!dir) return;
+    rmSync(dir, { recursive: true, force: true });
+    if (dir === this._baseContextDir) this._baseContextDir = undefined;
+  }
+
   // ---------------------------------------------------------------------------
   // Private — event classification
   // ---------------------------------------------------------------------------
@@ -1297,3 +1526,35 @@ export class ClaudeCodeSession implements HarnessSession {
     }
   }
 }
+
+const BASE_CONTEXT_PREFIX = 'agent-session-base-';
+let swept = false;
+
+/**
+ * Remove base context files a crashed or killed process left behind (each holds a whole composed
+ * context). Runs once per process; a directory belongs to the pid in its name and goes only when
+ * that process is gone.
+ */
+export function sweepOrphanedBaseContexts(dir = tmpdir()): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const pid = Number(new RegExp(`^${BASE_CONTEXT_PREFIX}(\\d+)-`).exec(entry)?.[1]);
+    if (!pid || pid === process.pid || processAlive(pid)) continue;
+    rmSync(join(dir, entry), { recursive: true, force: true });
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: it exists under another user.
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}