specrails-core 6.6.4 → 6.7.0

package/dist/agent-runtime/session/application/active-session.js

@@ -42,11 +42,26 @@ export class ActiveSession {
     descriptor;
     /** Inputs held back for drivers without a native input queue. */
     heldInputs = [];
+    /** Interrupting inputs held for drivers without a native input queue; released before `heldInputs`. */
+    interruptQueue = [];
+    /**
+     * The turn an `interrupt` delivery is cutting and the interrupting inputs that
+     * have not started yet. Cleared when one of them starts a turn.
+     */
+    pendingInterrupt = null;
     /** Inputs the application wrote on its own (policy-driven turns). */
     systemInputIds = new Set();
     pendingDeferred = null;
     roster = null;
     handoffs = 0;
+    /** Tool calls (the turn's and its sub-agents') that started and have not completed. */
+    toolsInFlight = new Set();
+    /**
+     * Text the turn streams around its tool calls arrives as separate messages
+     * with no whitespace between them. `broken` = text was streamed and a tool
+     * call followed, so the next text starts a new paragraph.
+     */
+    textSegment = 'none';
     finishedSinceLastTurn = new Set();
     /** Finished delegated sub-agents whose results the agent has not received yet. */
     delegatedResults = new Map();
@@ -201,12 +216,95 @@ export class ActiveSession {
     }
     // ── Delivery and process lifecycle ────────────────────────────────────────
     async deliver(input) {
+        if (input.delivery === 'interrupt')
+            return this.deliverInterrupt(input);
         const caps = this.descriptor.capabilities;
         const turnRunning = this.state.openTurn !== null;
         if (!caps.nativeInputQueue && turnRunning && !(input.delivery === 'steer' && caps.steer)) {
             this.heldInputs.push(input);
             return;
         }
+        await this.write(input);
+    }
+    /**
+     * Cut the running turn and run `input` next. Idle sessions deliver it as a
+     * queued input. A driver with a native queue and a native primitive does both
+     * in one call; otherwise the application stops the turn and releases the
+     * input first when the turn ends (Codex: `turn/interrupt` then `turn/start`).
+     * A second interrupt while one is pending does not stop again: it follows the
+     * pending input, ahead of queued ones.
+     */
+    async deliverInterrupt(input) {
+        const turn = this.state.openTurn;
+        const driver = this.driver;
+        const pending = this.pendingInterrupt;
+        if (!pending && (!turn || !driver))
+            return this.deliver({ ...input, delivery: 'queue' });
+        const caps = this.descriptor.capabilities;
+        if (pending)
+            pending.inputs.push(input);
+        else
+            this.pendingInterrupt = { turnId: turn.turnId, inputs: [input] };
+        if (!caps.nativeInputQueue) {
+            this.interruptQueue.push(input);
+            // A later interrupt waits behind the pending one; it is released when that one's turn ends.
+            if (!pending)
+                await this.stopForInterrupt(driver, turn.turnId);
+            return;
+        }
+        if (caps.interrupt === 'native') {
+            if (!pending)
+                this.armInterruptGrace(turn.turnId);
+            await this.write(input);
+            return;
+        }
+        if (!pending)
+            await this.stopForInterrupt(driver, turn.turnId);
+        await this.write({ ...input, delivery: 'queue' });
+    }
+    async stopForInterrupt(driver, turnId) {
+        this.armInterruptGrace(turnId);
+        try {
+            await driver.interrupt();
+        }
+        catch (error) {
+            // The input is held either way: it runs when the turn ends, or after the grace retires the process.
+            this.commit([{ type: 'provider.diagnostic', level: 'warning', code: 'provider.interrupt_failed', message: error.message.slice(0, 2_000) }]);
+        }
+    }
+    armInterruptGrace(turnId) {
+        this.timers.arm('interruptGrace', this.deps.interruptGraceMs ?? 5_000, () => {
+            if (this.state.openTurn?.turnId === turnId)
+                void this.retireForInterrupt();
+        });
+    }
+    /**
+     * The provider did not end the cut turn in time: retire the process without
+     * losing the interrupting input or the inputs the application still holds,
+     * then deliver them to a fresh process (the provider session is resumed).
+     */
+    async retireForInterrupt() {
+        const caps = this.descriptor.capabilities;
+        const waiting = (input) => {
+            const state = this.state.inputs[input.inputId]?.state;
+            return state === 'accepted' || state === 'queued';
+        };
+        const held = caps.nativeInputQueue ? (this.pendingInterrupt?.inputs ?? []) : [...this.interruptQueue, ...this.heldInputs];
+        const carried = held.filter(waiting).map((input) => ({ ...input, delivery: input.delivery === 'interrupt' ? 'queue' : input.delivery }));
+        await this.retire('user_stop', { turnStatus: 'interrupted', subagentPhase: 'interrupted', reason: 'user_interrupt', completeStarted: true, keepInputIds: new Set(carried.map((input) => input.inputId)) });
+        if (this.state.status === 'closed' || carried.length === 0)
+            return;
+        if (caps.nativeInputQueue) {
+            for (const input of carried)
+                await this.write(input).catch(() => undefined);
+            return;
+        }
+        const [first, ...rest] = carried;
+        this.heldInputs.push(...rest);
+        await this.write(first).catch(() => undefined);
+    }
+    /** Write one input to the provider; a failed write leaves the input `interrupted`, never half-sent. */
+    async write(input) {
         try {
             const driver = await this.ensureDriver();
             await driver.send(input);
@@ -216,6 +314,7 @@ export class ActiveSession {
             if (current === 'accepted' || current === 'queued') {
                 this.commit([{ type: 'input.state', inputId: input.inputId, state: 'interrupted', reason: 'delivery_failed' }]);
             }
+            this.forgetPendingInterrupt([input.inputId]);
             throw isSessionError(error) ? error : new SessionError('internal', `Could not deliver input: ${error.message}`);
         }
     }
@@ -271,6 +370,7 @@ export class ActiveSession {
         }
     }
     handleDriverEvent(event) {
+        this.trackToolInFlight(event);
         this.markActivity();
         switch (event.kind) {
             case 'process.started':
@@ -283,6 +383,7 @@ export class ActiveSession {
                 this.driver = null;
                 this.liveGeneration = null;
                 this.timers.cancel('idle', 'stall', 'backgroundMax', 'turnInactivity', 'settle', 'interruptGrace');
+                this.toolsInFlight.clear();
                 this.endRunningWork({ turnStatus: 'failed', subagentPhase: 'interrupted', reason: 'crashed', error: `Provider process exited (code ${event.exitCode ?? 'none'}${event.signal ? `, signal ${event.signal}` : ''})` });
                 this.commit([{ type: 'session.process', state: 'exited', generation: this.generation, exitCode: event.exitCode, reason: 'crashed' }]);
                 this.deps.touched(this);
@@ -299,6 +400,8 @@ export class ActiveSession {
                 const input = this.state.inputs[event.inputId];
                 if (!input || input.state === event.state)
                     return;
+                if (event.state === 'rejected')
+                    this.forgetPendingInterrupt([event.inputId]);
                 this.commit([{ type: 'input.state', inputId: event.inputId, state: event.state, ...(this.state.openTurn && event.state !== 'queued' ? { turnId: this.state.openTurn.turnId } : {}), ...(event.reason ? { reason: event.reason } : {}) }]);
                 return;
             }
@@ -306,11 +409,13 @@ export class ActiveSession {
                 return this.startTurn(event.trigger, event.inputIds);
             case 'turn.output': {
                 const turn = this.requireTurn();
-                this.commitBuffered(this.output.add({ type: 'turn.output', turnId: turn.turnId, channel: event.channel, delta: event.delta }));
+                this.commitBuffered(this.output.add({ type: 'turn.output', turnId: turn.turnId, channel: event.channel, delta: event.channel === 'text' ? this.separateTextSegment(event.delta) : event.delta }));
                 return;
             }
             case 'turn.tool': {
                 const turn = this.requireTurn();
+                if (this.textSegment === 'open')
+                    this.textSegment = 'broken';
                 const { kind: _kind, ...tool } = event;
                 this.commit([{ type: 'turn.tool', turnId: turn.turnId, ...tool }]);
                 return;
@@ -369,6 +474,9 @@ export class ActiveSession {
             this.handoffs = 0;
         }
         this.finishedSinceLastTurn.clear();
+        this.textSegment = 'none';
+        if (this.pendingInterrupt?.inputs.some((input) => inputIds.includes(input.inputId)))
+            this.pendingInterrupt = null;
         this.timers.cancel('idle', 'stall');
         this.commit([
             ...(this.state.phase === 'turn' ? [] : [{ type: 'session.phase', phase: 'turn' }]),
@@ -376,12 +484,20 @@ export class ActiveSession {
         ]);
         this.armTurnInactivity();
     }
-    completeTurn(status, text, reported, error) {
+    completeTurn(reportedStatus, reportedText, reported, error) {
         const turn = this.requireTurn();
         this.timers.cancel('turnInactivity', 'interruptGrace');
+        this.toolsInFlight.clear();
+        // A stop the application asked for to run an interrupting input is an interruption.
+        const status = reportedStatus === 'stopped' && this.pendingInterrupt?.turnId === turn.turnId ? 'interrupted' : reportedStatus;
+        // Commit buffered deltas first so a cut turn keeps the partial text it streamed.
+        if (this.output.hasPending()) {
+            this.timers.cancel('flush');
+            this.commit(this.output.flush());
+        }
+        const text = reportedText || (status === 'interrupted' ? this.state.openTurn?.text ?? '' : '');
         const { usage, baselineOption } = this.turnUsage(reported);
         this.commit([
-            ...this.output.flush(),
             ...this.output.drainTurn(turn.turnId),
             { type: 'turn.completed', turnId: turn.turnId, status, text, usage, ...(error ? { error } : {}) },
             ...this.completeTurnInputs(turn.inputIds, turn.turnId),
@@ -456,6 +572,9 @@ export class ActiveSession {
             return;
         if (this.finishedSinceLastTurn.size === 0 || this.handoffs >= policy.limits.maxSettleHandoffs || !this.driver)
             return;
+        // A user correction runs first; the next settle point collects the sub-agents.
+        if (this.pendingInterrupt)
+            return;
         this.handoffs += 1;
         const inputId = this.deps.ids.input();
         this.systemInputIds.add(inputId);
@@ -466,6 +585,9 @@ export class ActiveSession {
     maybeDeliverDelegatedResults() {
         if (this.delegatedResults.size === 0 || this.state.openTurn || this.state.status === 'closed' || this.closing)
             return false;
+        // A user correction runs first; the results follow at the next settle point.
+        if (this.pendingInterrupt)
+            return false;
         if (this.handoffs >= this.config.policy.limits.maxSettleHandoffs)
             return false;
         const results = [...this.delegatedResults.values()];
@@ -546,9 +668,27 @@ export class ActiveSession {
     idleTeardown(reason) {
         return { turnStatus: 'interrupted', subagentPhase: 'interrupted', reason };
     }
+    separateTextSegment(delta) {
+        const separate = this.textSegment === 'broken' && !/^\s*\n/.test(delta);
+        this.textSegment = 'open';
+        return separate ? `\n\n${delta}` : delta;
+    }
+    trackToolInFlight(event) {
+        const tool = event.kind === 'turn.tool' ? event : event.kind === 'subagent.output' ? event.tool : undefined;
+        if (!tool?.toolUseId)
+            return;
+        if (tool.phase === 'started')
+            this.toolsInFlight.add(tool.toolUseId);
+        else
+            this.toolsInFlight.delete(tool.toolUseId);
+    }
     armTurnInactivity() {
-        this.timers.arm('turnInactivity', this.config.policy.limits.turnInactivityMs, () => {
-            void this.retire('stalled', { turnStatus: 'failed', subagentPhase: 'interrupted', reason: 'stalled', error: 'No provider activity before the inactivity limit' });
+        const limits = this.config.policy.limits;
+        const waitingOnTool = this.toolsInFlight.size > 0;
+        const limit = waitingOnTool ? Math.max(limits.turnInactivityMs, limits.toolInactivityMs) : limits.turnInactivityMs;
+        this.timers.arm('turnInactivity', limit, () => {
+            const error = waitingOnTool ? 'A tool call produced no provider activity before the tool inactivity limit' : 'No provider activity before the inactivity limit';
+            void this.retire('stalled', { turnStatus: 'failed', subagentPhase: 'interrupted', reason: 'stalled', error });
         });
     }
     markActivity() {
@@ -575,9 +715,17 @@ export class ActiveSession {
     async releaseHeldInput() {
         if (this.state.openTurn)
             return;
-        const next = this.heldInputs.shift();
+        const next = this.interruptQueue.shift() ?? this.heldInputs.shift();
         if (next)
-            await this.deliver(next).catch(() => undefined);
+            await this.deliver(next.delivery === 'interrupt' ? { ...next, delivery: 'queue' } : next).catch(() => undefined);
+    }
+    forgetPendingInterrupt(inputIds) {
+        const pending = this.pendingInterrupt;
+        if (!pending)
+            return;
+        pending.inputs = pending.inputs.filter((input) => !inputIds.includes(input.inputId));
+        if (pending.inputs.length === 0)
+            this.pendingInterrupt = null;
     }
     /** End whatever was running; used by retire and unexpected exits. */
     endRunningWork(teardown) {
@@ -605,11 +753,19 @@ export class ActiveSession {
             }
         }
         for (const input of Object.values(this.state.inputs)) {
+            if (teardown.keepInputIds?.has(input.inputId))
+                continue;
+            if (input.state === 'started' && teardown.completeStarted) {
+                bodies.push({ type: 'input.state', inputId: input.inputId, state: 'completed', ...(input.turnId ? { turnId: input.turnId } : {}) });
+                continue;
+            }
             if (input.state === 'accepted' || input.state === 'queued' || input.state === 'started') {
                 bodies.push({ type: 'input.state', inputId: input.inputId, state: 'interrupted', reason: teardown.reason });
             }
         }
         this.heldInputs.length = 0;
+        this.interruptQueue.length = 0;
+        this.pendingInterrupt = null;
         // With delegated work still running the session stays in the background.
         const nextPhase = this.delegatedLive().length > 0 ? 'background' : 'idle';
         if (this.state.phase !== nextPhase || turn)

package/dist/agent-runtime/session/application/session-service.d.ts

@@ -1,7 +1,7 @@
 import type { SessionEventEnvelope } from '../domain/events.js';
 import { type SessionPolicyInput } from '../domain/policy.js';
 import { type SessionSnapshot } from '../domain/snapshot.js';
-import type { Attachment, DriverDescriptor } from '../domain/types.js';
+import type { Attachment, DriverDescriptor, InputDelivery } from '../domain/types.js';
 import type { RateCard } from '../domain/usage.js';
 import type { Clock, DriverCatalog, Ids, SessionJournal, SessionSummary } from '../ports.js';
 import { type DelegateParams, type DelegatedResult } from './delegation.js';
@@ -38,7 +38,7 @@ export interface SendParams {
     inputId: string;
     text: string;
     attachments?: Attachment[];
-    delivery: 'queue' | 'steer';
+    delivery: InputDelivery;
 }
 export type SessionListener = (envelopes: SessionEventEnvelope[]) => void;
 export declare const DEFAULT_MAX_RESIDENT = 6;

package/dist/agent-runtime/session/domain/descriptor.js

@@ -27,6 +27,11 @@ export function validateDescriptor(descriptor) {
         fail('a native input queue requires a resident process');
     if (!caps.resident && caps.autonomousContinuation)
         fail('autonomous continuation requires a resident process');
+    if (caps.interrupt !== undefined && caps.interrupt !== 'native' && caps.interrupt !== 'emulated')
+        fail('capabilities.interrupt must be native|emulated when present');
+    // A native interrupt without a turn-level stop that keeps the session is meaningless for one-shot drivers.
+    if (caps.interrupt === 'native' && !caps.resident)
+        fail('a native interrupt requires a resident process');
     if (!COST.has(caps.usage?.costUsd) || !TOKENS.has(caps.usage?.tokens))
         fail('capabilities.usage is invalid');
 }

package/dist/agent-runtime/session/domain/interruption.js

@@ -1,5 +1,6 @@
 const REASONS = Object.freeze({
     user_stop: 'stopped by the user',
+    user_interrupt: 'interrupted by a newer user message',
     host_request: 'stopped by the host',
     restart: 'interrupted by an application restart',
     shutdown: 'interrupted when the application closed',

package/dist/agent-runtime/session/domain/policy.js

@@ -5,6 +5,7 @@ export const DEFAULT_LIMITS = Object.freeze({
     stallMs: 15 * 60_000,
     backgroundMaxMs: 2 * 60 * 60_000,
     turnInactivityMs: 5 * 60_000,
+    toolInactivityMs: 60 * 60_000,
     maxSettleHandoffs: 3,
     settleDebounceMs: 1_500,
 });
@@ -13,6 +14,7 @@ const LIMIT_BOUNDS = Object.freeze({
     stallMs: [1_000, 24 * 60 * 60_000],
     backgroundMaxMs: [1_000, 7 * 24 * 60 * 60_000],
     turnInactivityMs: [1_000, 24 * 60 * 60_000],
+    toolInactivityMs: [1_000, 24 * 60 * 60_000],
     maxSettleHandoffs: [0, 20],
     settleDebounceMs: [0, 60_000],
 });

package/dist/agent-runtime/session/domain/redaction.d.ts

@@ -0,0 +1,19 @@
+import type { SessionEvent } from './events.js';
+import type { SessionSnapshot } from './snapshot.js';
+/**
+ * Secret redaction at the journal boundary (docs/agent-sessions/journal.md).
+ *
+ * Only free text and tool I/O are redacted. Identifiers, sequence numbers,
+ * phases, usage numbers and host-supplied configuration (`systemPrompt`,
+ * `session.updated.changes`, `policy`) are kept as they are: configuration is
+ * read back from the snapshot to resume a session, so changing it would change
+ * what the provider receives. Event shapes never change: a redacted field keeps
+ * its type and an absent field stays absent.
+ */
+export declare function redactSessionEvent(event: SessionEvent): SessionEvent;
+/**
+ * Redact the free text a snapshot carries (open turn text, sub-agent
+ * descriptions, reasons and results). Input fingerprints, configuration and
+ * usage are untouched.
+ */
+export declare function redactSessionSnapshot(snapshot: SessionSnapshot): SessionSnapshot;

package/dist/agent-runtime/session/domain/redaction.js

@@ -0,0 +1,71 @@
+import { redactSecrets, redactSecretsDeep } from '../../../shared/secret-redaction.js';
+/**
+ * Secret redaction at the journal boundary (docs/agent-sessions/journal.md).
+ *
+ * Only free text and tool I/O are redacted. Identifiers, sequence numbers,
+ * phases, usage numbers and host-supplied configuration (`systemPrompt`,
+ * `session.updated.changes`, `policy`) are kept as they are: configuration is
+ * read back from the snapshot to resume a session, so changing it would change
+ * what the provider receives. Event shapes never change: a redacted field keeps
+ * its type and an absent field stays absent.
+ */
+export function redactSessionEvent(event) {
+    switch (event.type) {
+        case 'input.accepted':
+            return { ...event, text: redactSecrets(event.text) };
+        case 'turn.output':
+            return { ...event, delta: redactSecrets(event.delta) };
+        case 'turn.tool':
+            return { ...event, ...redactTool(event) };
+        case 'turn.completed':
+            return { ...event, text: redactSecrets(event.text), ...(event.error === undefined ? {} : { error: redactSecrets(event.error) }) };
+        case 'subagent.started':
+            return { ...event, description: redactSecrets(event.description), ...(event.prompt === undefined ? {} : { prompt: redactSecrets(event.prompt) }) };
+        case 'subagent.output':
+            return {
+                ...event,
+                ...(event.delta === undefined ? {} : { delta: redactSecrets(event.delta) }),
+                ...(event.tool === undefined ? {} : { tool: { ...event.tool, ...redactTool(event.tool) } }),
+            };
+        case 'subagent.result':
+            return { ...event, summary: redactSecrets(event.summary) };
+        case 'subagent.phase':
+        case 'input.state':
+        case 'session.process':
+            return event.reason === undefined ? event : { ...event, reason: redactSecrets(event.reason) };
+        case 'session.closed':
+            return { ...event, reason: redactSecrets(event.reason) };
+        case 'provider.diagnostic':
+            return { ...event, message: redactSecrets(event.message) };
+        default:
+            return event;
+    }
+}
+function redactTool(tool) {
+    return {
+        ...(tool.input === undefined ? {} : { input: redactSecretsDeep(tool.input) }),
+        ...(tool.output === undefined ? {} : { output: redactSecrets(tool.output) }),
+    };
+}
+/**
+ * Redact the free text a snapshot carries (open turn text, sub-agent
+ * descriptions, reasons and results). Input fingerprints, configuration and
+ * usage are untouched.
+ */
+export function redactSessionSnapshot(snapshot) {
+    const subagents = {};
+    for (const [id, node] of Object.entries(snapshot.subagents)) {
+        subagents[id] = {
+            ...node,
+            description: redactSecrets(node.description),
+            reason: node.reason === null ? null : redactSecrets(node.reason),
+            resultSummary: node.resultSummary === null ? null : redactSecrets(node.resultSummary),
+        };
+    }
+    return {
+        ...snapshot,
+        openTurn: snapshot.openTurn === null ? null : { ...snapshot.openTurn, text: redactSecrets(snapshot.openTurn.text) },
+        subagents,
+        closedReason: snapshot.closedReason === null ? null : redactSecrets(snapshot.closedReason),
+    };
+}

package/dist/agent-runtime/session/domain/types.d.ts

@@ -7,7 +7,11 @@ export type SessionPhase = 'idle' | 'turn' | 'background';
 export type SessionStatus = 'open' | 'closed';
 export type TurnOrigin = 'user' | 'subagent' | 'system';
 export type TurnStatus = 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
-export type InputDelivery = 'queue' | 'steer';
+/**
+ * `queue`: run as a later turn. `steer`: deliver into the running turn.
+ * `interrupt`: cut the running turn and run this input next (like `queue` when idle).
+ */
+export type InputDelivery = 'queue' | 'steer' | 'interrupt';
 export type InputState = 'accepted' | 'queued' | 'started' | 'completed' | 'rejected' | 'interrupted';
 export type SubagentKind = 'foreground' | 'background';
 export type SubagentPhase = 'running' | 'idle' | 'failed' | 'stopped' | 'killed' | 'interrupted';
@@ -52,6 +56,12 @@ export interface SessionLimits {
     backgroundMaxMs: number;
     /** Fail a running turn when no provider frame (including sub-agent frames) arrives for this long. */
     turnInactivityMs: number;
+    /**
+     * Replaces `turnInactivityMs` while a tool call (the turn's or a sub-agent's)
+     * has started and not completed: a long build or test run is silent until
+     * it returns, so it gets a wider bound instead of failing the turn.
+     */
+    toolInactivityMs: number;
     /** Maximum policy-driven `resume-agent` turns per settle cycle. */
     maxSettleHandoffs: number;
     /** Debounce before an empty sub-agent roster counts as settled. */
@@ -114,6 +124,12 @@ export interface DriverCapabilities {
     steer: boolean;
     /** The tool set can be restricted (`policy.tools` other than the default). */
     toolFiltering: boolean;
+    /**
+     * How `delivery: 'interrupt'` cuts a running turn. `native`: the provider's own
+     * stop primitive, keeping its session. `emulated`: the runtime stops the turn
+     * as `session.interrupt` does, then runs the input next. Absent on older Cores.
+     */
+    interrupt?: 'native' | 'emulated';
     usage: UsageSemantics;
 }
 export interface DriverDescriptor {

package/dist/agent-runtime/session/drivers/claude/argv.d.ts

@@ -2,6 +2,20 @@ import type { DriverOpenSpec } from '../../ports.js';
 /** Tools that launch sub-agents in Claude Code; removed when policy disables sub-agents. */
 export declare const CLAUDE_SUBAGENT_TOOLS: readonly ['Agent', 'Task'];
 export declare const CLAUDE_READ_ONLY_TOOLS: readonly ['Read', 'Grep', 'Glob'];
+/**
+ * Built-in tools that change files or run commands. A read-only session that
+ * allows native sub-agents also denies them: deny rules bind every sub-agent of
+ * the session, including project-defined agents that name their own tools.
+ */
+export declare const CLAUDE_WRITE_TOOLS: readonly ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash'];
+/**
+ * The read-only tool set. Native sub-agents keep the parent's restriction
+ * (verified live with Claude Code 2.1.309: a general-purpose sub-agent of a
+ * `--tools Read,Grep,Glob,Agent` session saw only those tools and could not
+ * write), so the sub-agent tool is offered when the policy allows them.
+ * `Task` is the tool's legacy name; unknown names in `--tools` are ignored.
+ */
+export declare function claudeReadOnlyTools(policy: DriverOpenSpec['policy']): string[];
 /**
  * Map an open spec + policy to Claude Code argv. Lists are passed as one
  * comma-separated argument (variadic flags would otherwise swallow later args).

package/dist/agent-runtime/session/drivers/claude/argv.js

@@ -2,6 +2,22 @@ import { nativeSubagentsAllowed } from '../../domain/policy.js';
 /** Tools that launch sub-agents in Claude Code; removed when policy disables sub-agents. */
 export const CLAUDE_SUBAGENT_TOOLS = ['Agent', 'Task'];
 export const CLAUDE_READ_ONLY_TOOLS = ['Read', 'Grep', 'Glob'];
+/**
+ * Built-in tools that change files or run commands. A read-only session that
+ * allows native sub-agents also denies them: deny rules bind every sub-agent of
+ * the session, including project-defined agents that name their own tools.
+ */
+export const CLAUDE_WRITE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash'];
+/**
+ * The read-only tool set. Native sub-agents keep the parent's restriction
+ * (verified live with Claude Code 2.1.309: a general-purpose sub-agent of a
+ * `--tools Read,Grep,Glob,Agent` session saw only those tools and could not
+ * write), so the sub-agent tool is offered when the policy allows them.
+ * `Task` is the tool's legacy name; unknown names in `--tools` are ignored.
+ */
+export function claudeReadOnlyTools(policy) {
+    return [...CLAUDE_READ_ONLY_TOOLS, ...(nativeSubagentsAllowed(policy) ? CLAUDE_SUBAGENT_TOOLS : [])];
+}
 function mcpConfig(servers) {
     return JSON.stringify({
         mcpServers: Object.fromEntries(servers.map((server) => [server.name, server.url
@@ -39,10 +55,11 @@ export function claudeArgs(spec, options = {}) {
     if (policy.tools.mode === 'none')
         args.push('--tools', '');
     else if (policy.tools.mode === 'read-only')
-        args.push('--tools', CLAUDE_READ_ONLY_TOOLS.join(','));
+        args.push('--tools', claudeReadOnlyTools(policy).join(','));
     if (policy.tools.allow?.length)
         args.push('--allowedTools', policy.tools.allow.join(','));
-    const denied = [...new Set([...(policy.tools.deny ?? []), ...(!nativeSubagentsAllowed(policy) ? CLAUDE_SUBAGENT_TOOLS : [])])];
+    const readOnlySubagents = policy.tools.mode === 'read-only' && nativeSubagentsAllowed(policy);
+    const denied = [...new Set([...(policy.tools.deny ?? []), ...(!nativeSubagentsAllowed(policy) ? CLAUDE_SUBAGENT_TOOLS : []), ...(readOnlySubagents ? CLAUDE_WRITE_TOOLS : [])])];
     if (denied.length)
         args.push('--disallowedTools', denied.join(','));
     if (policy.mcp.servers.length)

package/dist/agent-runtime/session/drivers/claude/driver.js

@@ -19,6 +19,7 @@ export const CLAUDE_DESCRIPTOR = Object.freeze({
         autonomousContinuation: true,
         steer: true,
         toolFiltering: true,
+        interrupt: 'native',
         usage: Object.freeze({ costUsd: 'session-cumulative', tokens: 'per-turn' }),
     }),
 });
@@ -47,6 +48,12 @@ class ClaudeDriverSession {
         this.cleanup = cleanup;
     }
     async send(input) {
+        // Interrupt delivery: stop the running turn (once per cut turn), then put the
+        // input first. Verified on 2.1.299: after the stop, `now` runs the input alone
+        // in the next turn and already queued commands follow; `next` or the default
+        // would batch it behind them.
+        if (input.delivery === 'interrupt' && this.translator.interruptible)
+            this.writeInterrupt();
         this.translator.noteInput(input.inputId);
         const frame = {
             type: 'user',
@@ -54,13 +61,16 @@ class ClaudeDriverSession {
             session_id: '',
             parent_tool_use_id: null,
             // `next` delivers into the running turn; otherwise the CLI queues it for the next turn.
-            ...(input.delivery === 'steer' ? { priority: 'next' } : {}),
+            ...(input.delivery === 'steer' ? { priority: 'next' } : input.delivery === 'interrupt' ? { priority: 'now' } : {}),
             message: { role: 'user', content: userContent(input) },
         };
         if (!this.process.write(JSON.stringify(frame)))
             throw new Error('Claude input is closed');
     }
     async interrupt() {
+        this.writeInterrupt();
+    }
+    writeInterrupt() {
         this.translator.noteInterrupt();
         this.process.write(JSON.stringify({ type: 'control_request', request_id: randomUUID(), request: { subtype: 'interrupt' } }));
     }

package/dist/agent-runtime/session/drivers/claude/translator.d.ts

@@ -15,6 +15,8 @@ export declare class ClaudeTranslator {
     private turnOpen;
     private interruptRequested;
     private readonly written;
+    /** Inputs the CLI reported started; a later `cancelled` only echoes their interrupted turn. */
+    private readonly started;
     private startedInputs;
     /** tool_use id → task id of the agent that issued it (null = main agent). */
     private readonly toolOwner;
@@ -26,6 +28,8 @@ export declare class ClaudeTranslator {
     /** The driver wrote this input; its receipts and replays belong to us. */
     noteInput(inputId: string): void;
     noteInterrupt(): void;
+    /** A turn is running and no stop was requested for it yet. */
+    get interruptible(): boolean;
     translate(frame: Frame): DriverEvent[];
     private system;
     private taskStarted;

package/dist/agent-runtime/session/drivers/claude/translator.js

@@ -6,7 +6,8 @@ const TASK_PHASE = Object.freeze({
 });
 /** System subtypes that carry nothing the session model needs. */
 const IGNORED_SYSTEM = new Set(['thinking_tokens', 'task_summary', 'post_turn_summary', 'status', 'hook_response', 'hook_started', 'compact_boundary']);
-const IGNORED_TYPES = new Set(['rate_limit_event', 'stream_event', 'keep_alive']);
+// `control_response` acknowledges our interrupt (`still_queued` lists commands that survive it).
+const IGNORED_TYPES = new Set(['rate_limit_event', 'stream_event', 'keep_alive', 'control_response']);
 function str(value) {
     return typeof value === 'string' ? value : undefined;
 }
@@ -25,6 +26,8 @@ export class ClaudeTranslator {
     turnOpen = false;
     interruptRequested = false;
     written = new Set();
+    /** Inputs the CLI reported started; a later `cancelled` only echoes their interrupted turn. */
+    started = new Set();
     startedInputs = [];
     /** tool_use id → task id of the agent that issued it (null = main agent). */
     toolOwner = new Map();
@@ -37,6 +40,8 @@ export class ClaudeTranslator {
     noteInput(inputId) { this.written.add(inputId); }
     noteInterrupt() { if (this.turnOpen)
         this.interruptRequested = true; }
+    /** A turn is running and no stop was requested for it yet. */
+    get interruptible() { return this.turnOpen && !this.interruptRequested; }
     translate(frame) {
         const type = str(frame.type);
         switch (type) {
@@ -145,8 +150,16 @@ export class ClaudeTranslator {
         const state = str(frame.state);
         if (!inputId || !this.written.has(inputId))
             return [];
-        if (state === 'started' && !this.turnOpen)
-            this.startedInputs.push(inputId);
+        if (state === 'started') {
+            this.started.add(inputId);
+            if (!this.turnOpen)
+                this.startedInputs.push(inputId);
+        }
+        if (state === 'completed')
+            this.started.delete(inputId);
+        // After an interrupt the CLI reports the cut turn's input `cancelled`; the turn result already settled it.
+        if (state === 'cancelled' && this.started.has(inputId))
+            return [];
         if (state === 'queued' || state === 'started' || state === 'completed')
             return [{ kind: 'input.receipt', inputId, state }];
         if (state === 'failed' || state === 'rejected' || state === 'cancelled')

package/dist/agent-runtime/session/drivers/codex/driver.js

@@ -18,6 +18,8 @@ export const CODEX_DESCRIPTOR = Object.freeze({
         autonomousContinuation: false,
         steer: true,
         toolFiltering: false,
+        // `turn/interrupt`, then `turn/start` once the turn completed (sequenced by the application).
+        interrupt: 'native',
         usage: Object.freeze({ costUsd: 'none', tokens: 'cumulative' }),
     }),
 });