praxis-agent 0.26.0 → 0.28.0

package/dist/core/runtime.js

@@ -1,3 +1,5 @@
+import { ToolExecutionScheduler } from './tool-execution-scheduler.js';
+import { resolveToolSchedulingPolicy } from './tool-scheduling-policy.js';
 const permissionDecisionSources = new WeakMap();
 const autoModePermissionOutcomes = new WeakMap();
 export function annotatePermissionDecision(decision, source) {
@@ -274,13 +276,23 @@ export class AgentRuntime {
         const definitions = this.provider.capabilities.tools
             ? (this.options.tools?.definitions() ?? [])
             : [];
-        const maxModelTurns = request.maxModelTurns ?? this.options.maxModelTurns ?? 16;
+        const maxModelTurns = request.maxModelTurns ?? this.options.maxModelTurns;
+        if (maxModelTurns !== undefined &&
+            (!Number.isSafeInteger(maxModelTurns) || maxModelTurns <= 0)) {
+            throw new TypeError('maxModelTurns must be a positive integer');
+        }
         const maxModelOutputBytes = this.options.maxModelOutputBytes ?? 1024 * 1024;
         const maxToolCallsPerTurn = this.options.maxToolCallsPerTurn ?? 32;
         const maxToolInputBytes = this.options.maxToolInputBytes ?? 1024 * 1024;
         let pendingToolUseSummary;
         try {
-            for (let turn = 0; turn < maxModelTurns; turn += 1) {
+            let modelTurns = 0;
+            while (true) {
+                if (request.signal?.aborted)
+                    return this.cancel();
+                if (maxModelTurns !== undefined && modelTurns >= maxModelTurns) {
+                    throw new Error(`Maximum model turns of ${maxModelTurns} exceeded`);
+                }
                 if (pendingToolUseSummary) {
                     const summaryRequest = pendingToolUseSummary;
                     pendingToolUseSummary = undefined;
@@ -326,6 +338,7 @@ export class AgentRuntime {
                     spent >= this.options.maxBudgetUsd) {
                     throw new Error(`Maximum budget of $${this.options.maxBudgetUsd.toFixed(6)} exceeded`);
                 }
+                modelTurns += 1;
                 this.emit({ type: 'state', state: 'awaiting-model' });
                 const providerRequest = {
                     messages: prepareProviderMessages(messages, this.provider.capabilities.images === true, this.provider.capabilities.documents === true),
@@ -347,6 +360,25 @@ export class AgentRuntime {
                 let streaming = false;
                 const toolCalls = [];
                 let terminalReason;
+                const toolScheduler = new ToolExecutionScheduler({
+                    ...(request.signal ? { parentSignal: request.signal } : {}),
+                    execute: (call, signal) => this.executeScheduledToolCall(call, request, messages, signal),
+                    isError: (result) => result.isError,
+                    cancelledResult: (call, reason) => ({
+                        content: `${call.name} cancelled: ${reason instanceof Error ? reason.message : String(reason)}`,
+                        isError: true,
+                    }),
+                    failedResult: (call, reason) => ({
+                        content: `${call.name} failed: ${reason instanceof Error ? reason.message : String(reason)}`,
+                        isError: true,
+                    }),
+                    resultCompleted: (call, result) => this.presentToolResult(call, result),
+                });
+                const failScheduledTurn = async (error) => {
+                    toolScheduler.abort(error);
+                    await toolScheduler.settle().catch(() => undefined);
+                    throw error;
+                };
                 const apiStartedAt = request.collectMetrics ? performance.now() : 0;
                 let turnApiDurationMs = 0;
                 let turnApiDurationWithoutRetriesMs;
@@ -422,6 +454,7 @@ export class AgentRuntime {
                             }
                             toolCalls.push(event.call);
                             this.emit(event);
+                            toolScheduler.schedule(event.call, resolveToolSchedulingPolicy(this.options.tools, event.call));
                         }
                         else if (event.type === 'terminal') {
                             terminalReason = event.reason;
@@ -433,6 +466,19 @@ export class AgentRuntime {
                         }
                     }
                 }
+                catch (error) {
+                    if (!request.signal?.aborted &&
+                        !(error instanceof AgentRunCancelledError)) {
+                        toolScheduler.abort(error);
+                    }
+                    else {
+                        toolScheduler.releaseExclusiveTools();
+                    }
+                    await toolScheduler.settle().catch(() => undefined);
+                    if (request.signal?.aborted)
+                        return this.cancel();
+                    throw error;
+                }
                 finally {
                     if (request.collectMetrics) {
                         turnApiDurationMs = Math.max(0, performance.now() - apiStartedAt);
@@ -442,15 +488,15 @@ export class AgentRuntime {
                 }
                 if (this.provider.capabilities.terminalReasons === true &&
                     terminalReason === undefined) {
-                    throw new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true });
+                    return failScheduledTurn(new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true }));
                 }
                 if (terminalReason === 'tool_use' && toolCalls.length === 0) {
-                    throw new ModelProviderError('Provider reported tool_use without a completed tool call', { retryable: false });
+                    return failScheduledTurn(new ModelProviderError('Provider reported tool_use without a completed tool call', { retryable: false }));
                 }
                 if (terminalReason !== undefined &&
                     terminalReason !== 'tool_use' &&
                     toolCalls.length > 0) {
-                    throw new ModelProviderError(`Provider reported ${terminalReason} with completed tool calls`, { retryable: false });
+                    return failScheduledTurn(new ModelProviderError(`Provider reported ${terminalReason} with completed tool calls`, { retryable: false }));
                 }
                 if (request.collectMetrics) {
                     const turnApiDurationWithoutRetriesMsResolved = turnApiDurationWithoutRetriesMs ?? turnApiDurationMs;
@@ -480,8 +526,14 @@ export class AgentRuntime {
                         ...(thinkingBlocks.length > 0 ? { thinkingBlocks } : {}),
                         toolCalls,
                     };
-                await request.observer?.assistantCompleted(assistantMessage);
+                try {
+                    await request.observer?.assistantCompleted(assistantMessage);
+                }
+                catch (error) {
+                    return failScheduledTurn(error);
+                }
                 messages.push(assistantMessage);
+                toolScheduler.releaseExclusiveTools();
                 if (toolCalls.length === 0) {
                     const stopResult = (await request.onStop?.(text)) ?? [];
                     const stopBatch = Array.isArray(stopResult)
@@ -547,10 +599,11 @@ export class AgentRuntime {
                         ...(linesRemoved === 0 ? {} : { linesRemoved }),
                     };
                 }
+                const scheduledToolResults = await toolScheduler.settle();
                 const followUpUserMessages = [];
                 const completedTools = [];
-                for (const call of toolCalls) {
-                    const result = await this.completeToolCall(call, request, messages);
+                for (const { call, result } of scheduledToolResults) {
+                    await this.persistToolCall(call, result, request);
                     completedTools.push({
                         name: call.name,
                         input: call.input,
@@ -584,6 +637,10 @@ export class AgentRuntime {
                     });
                     followUpUserMessages.push(...(result.followUpUserMessages ?? []));
                 }
+                const toolFailure = toolScheduler.failure;
+                if (toolFailure) {
+                    throw toolFailure.error;
+                }
                 if (this.options.generateToolUseSummary) {
                     const summarySignal = request.signal ?? new AbortController().signal;
                     pendingToolUseSummary = {
@@ -609,7 +666,6 @@ export class AgentRuntime {
                     messages.splice(0, messages.length, ...reloadedMessages);
                 }
             }
-            throw new Error(`Agent exceeded ${maxModelTurns} model turns`);
         }
         catch (error) {
             if (request.signal?.aborted)
@@ -659,19 +715,38 @@ export class AgentRuntime {
         return result;
     }
     async completeToolCall(call, request, messages = request.messages ?? [], emitPresentation = true) {
+        const signal = request.signal ?? new AbortController().signal;
+        let result;
+        try {
+            result = await this.executeScheduledToolCall(call, request, messages, signal, emitPresentation);
+        }
+        catch (error) {
+            if (request.signal?.aborted)
+                return this.cancel();
+            throw error;
+        }
+        if (emitPresentation)
+            this.presentToolResult(call, result);
+        await this.persistToolCall(call, result, request);
+        return result;
+    }
+    async executeScheduledToolCall(call, request, messages, signal, emitPresentation = true) {
         const startedAt = performance.now();
-        const emitProgress = () => this.emit({
+        const emitProgress = (elapsedTimeSeconds) => this.emit({
             type: 'tool-progress',
             toolUseId: call.id,
             toolName: call.name,
-            elapsedTimeSeconds: Math.max(0, Math.round(((performance.now() - startedAt) / 1000) * 1000) / 1000),
+            elapsedTimeSeconds: elapsedTimeSeconds ??
+                Math.max(0, Math.round(((performance.now() - startedAt) / 1000) * 1000) / 1000),
         });
         const progressTimer = emitPresentation
             ? setInterval(emitProgress, 1000)
             : undefined;
         progressTimer?.unref();
         try {
-            const executed = await this.executeTool(call, request, messages);
+            if (emitPresentation)
+                emitProgress(0);
+            const executed = await this.executeTool(call, { ...request, signal }, messages);
             const unsupportedImages = executed.images?.length && this.provider.capabilities.images !== true;
             const unsupportedDocuments = executed.documents?.length &&
                 this.provider.capabilities.documents !== true;
@@ -690,16 +765,8 @@ export class AgentRuntime {
                         : {}),
                 }
                 : executed;
-            this.emit({ type: 'state', state: 'persisting-results' });
-            await request.observer?.toolCompleted(call, result);
             if (emitPresentation) {
                 emitProgress();
-                this.emit({
-                    type: 'tool-result',
-                    callId: call.id,
-                    content: result.content,
-                    isError: result.isError,
-                });
             }
             return result;
         }
@@ -708,6 +775,18 @@ export class AgentRuntime {
                 clearInterval(progressTimer);
         }
     }
+    presentToolResult(call, result) {
+        this.emit({
+            type: 'tool-result',
+            callId: call.id,
+            content: result.content,
+            isError: result.isError,
+        });
+    }
+    async persistToolCall(call, result, request) {
+        this.emit({ type: 'state', state: 'persisting-results' });
+        await request.observer?.toolCompleted(call, result);
+    }
     async executeTool(call, request, messages) {
         const tools = this.options.tools;
         const permissions = this.options.permissions;
@@ -808,8 +887,9 @@ export class AgentRuntime {
                         : 'Permission approval was not provided');
             return { content: reason, isError: true };
         }
-        if (request.signal?.aborted)
-            return this.cancel();
+        if (request.signal?.aborted) {
+            throw request.signal.reason ?? new AgentRunCancelledError();
+        }
         this.emit({ type: 'state', state: 'executing-tools' });
         context.permissionPhase = 'execute';
         context.permissionApproved = true;
@@ -829,8 +909,9 @@ export class AgentRuntime {
             };
         }
         catch (error) {
-            if (request.signal?.aborted)
-                return this.cancel();
+            if (request.signal?.aborted) {
+                throw request.signal.reason ?? new AgentRunCancelledError();
+            }
             const durationToolMs = Math.max(0, performance.now() - toolStartedAt);
             return {
                 content: error instanceof Error ? error.message : String(error),
@@ -840,13 +921,15 @@ export class AgentRuntime {
         }
     }
     async requireRecoveryApproval(call, request) {
-        if (request.signal?.aborted)
-            return this.cancel();
+        if (request.signal?.aborted) {
+            throw request.signal.reason ?? new AgentRunCancelledError();
+        }
         if (request.approveRecovery && !(await request.approveRecovery(call))) {
             throw new Error(`Tool call ${call.id} recovery was declined`);
         }
-        if (request.signal?.aborted)
-            return this.cancel();
+        if (request.signal?.aborted) {
+            throw request.signal.reason ?? new AgentRunCancelledError();
+        }
     }
     cancel() {
         this.emit({ type: 'state', state: 'cancelled' });

package/dist/core/tool-execution-scheduler.d.ts

@@ -0,0 +1,38 @@
+import type { ModelToolCall, ToolSchedulingPolicy } from './runtime.js';
+interface ScheduledToolResult<TResult> {
+    call: ModelToolCall;
+    result: TResult;
+}
+interface ToolExecutionSchedulerOptions<TResult> {
+    parentSignal?: AbortSignal;
+    execute(call: ModelToolCall, signal: AbortSignal): Promise<TResult>;
+    isError(result: TResult): boolean;
+    cancelledResult(call: ModelToolCall, reason: unknown): TResult;
+    failedResult(call: ModelToolCall, reason: unknown): TResult;
+    resultCompleted(call: ModelToolCall, result: TResult): void;
+}
+export declare class ToolExecutionScheduler<TResult> {
+    private readonly options;
+    private readonly groupController;
+    private readonly exclusiveStart;
+    private releaseExclusiveStart;
+    private exclusiveStarted;
+    private hasFailure;
+    private firstFailure;
+    private readonly scheduled;
+    private readonly completionOrder;
+    private precedingBarrier;
+    private concurrentGroup;
+    constructor(options: ToolExecutionSchedulerOptions<TResult>);
+    schedule(call: ModelToolCall, policy: ToolSchedulingPolicy): void;
+    abort(reason?: unknown): void;
+    releaseExclusiveTools(): void;
+    settle(): Promise<readonly ScheduledToolResult<TResult>[]>;
+    get failure(): {
+        error: unknown;
+    } | undefined;
+    private record;
+    private executionSignal;
+}
+export {};
+//# sourceMappingURL=tool-execution-scheduler.d.ts.map

package/dist/core/tool-execution-scheduler.js

@@ -0,0 +1,95 @@
+const settled = Promise.resolve();
+export class ToolExecutionScheduler {
+    options;
+    groupController = new AbortController();
+    exclusiveStart;
+    releaseExclusiveStart;
+    exclusiveStarted = false;
+    hasFailure = false;
+    firstFailure;
+    scheduled = [];
+    completionOrder = [];
+    precedingBarrier = settled;
+    concurrentGroup = [];
+    constructor(options) {
+        this.options = options;
+        this.exclusiveStart = new Promise((resolve) => {
+            this.releaseExclusiveStart = resolve;
+        });
+    }
+    schedule(call, policy) {
+        const predecessors = policy.concurrency === 'exclusive'
+            ? Promise.allSettled([
+                ...(policy.startAfterAssistant ? [this.exclusiveStart] : []),
+                this.precedingBarrier,
+                ...this.concurrentGroup,
+            ]).then(() => undefined)
+            : this.precedingBarrier;
+        const signal = this.executionSignal(policy);
+        const execution = predecessors.then(async () => {
+            let result;
+            try {
+                if (signal.aborted)
+                    throw signal.reason;
+                result = await this.options.execute(call, signal);
+                if (signal.aborted)
+                    throw signal.reason;
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    result = this.options.cancelledResult(call, error);
+                }
+                else {
+                    if (!this.hasFailure) {
+                        this.hasFailure = true;
+                        this.firstFailure = error;
+                    }
+                    result = this.options.failedResult(call, error);
+                }
+            }
+            this.record(call, result);
+            if (policy.abortGroupOnError && this.options.isError(result)) {
+                this.groupController.abort(new Error(`Tool ${call.name} failed; cancelling streamed siblings`));
+            }
+        });
+        this.scheduled.push(execution);
+        if (policy.concurrency === 'exclusive') {
+            this.precedingBarrier = execution.catch(() => undefined);
+            this.concurrentGroup = [];
+        }
+        else {
+            this.concurrentGroup.push(execution.catch(() => undefined));
+        }
+    }
+    abort(reason) {
+        this.releaseExclusiveTools();
+        this.groupController.abort(reason);
+    }
+    releaseExclusiveTools() {
+        if (this.exclusiveStarted)
+            return;
+        this.exclusiveStarted = true;
+        this.releaseExclusiveStart();
+    }
+    async settle() {
+        await Promise.all(this.scheduled);
+        return this.completionOrder;
+    }
+    get failure() {
+        return this.hasFailure ? { error: this.firstFailure } : undefined;
+    }
+    record(call, result) {
+        this.completionOrder.push({ call, result });
+        this.options.resultCompleted(call, result);
+    }
+    executionSignal(policy) {
+        const signals = [this.groupController.signal];
+        if (policy.cancelOnInterrupt && this.options.parentSignal) {
+            signals.push(this.options.parentSignal);
+        }
+        return signals.length === 1
+            ? this.groupController.signal
+            : AbortSignal.any(signals);
+    }
+}
+//# sourceMappingURL=tool-execution-scheduler.js.map

package/dist/core/tool-scheduling-policy.d.ts

@@ -0,0 +1,4 @@
+import type { ModelToolCall, ToolRegistry, ToolSchedulingPolicy } from './runtime.js';
+export declare const exclusiveToolSchedulingPolicy: ToolSchedulingPolicy;
+export declare function resolveToolSchedulingPolicy(tools: ToolRegistry | undefined, call: ModelToolCall): ToolSchedulingPolicy;
+//# sourceMappingURL=tool-scheduling-policy.d.ts.map

package/dist/core/tool-scheduling-policy.js

@@ -0,0 +1,24 @@
+export const exclusiveToolSchedulingPolicy = {
+    concurrency: 'exclusive',
+};
+export function resolveToolSchedulingPolicy(tools, call) {
+    try {
+        const policy = tools?.schedulingPolicy?.(structuredClone(call));
+        if (!policy ||
+            (policy.concurrency !== 'concurrent' &&
+                policy.concurrency !== 'exclusive') ||
+            (policy.cancelOnInterrupt !== undefined &&
+                typeof policy.cancelOnInterrupt !== 'boolean') ||
+            (policy.abortGroupOnError !== undefined &&
+                typeof policy.abortGroupOnError !== 'boolean') ||
+            (policy.startAfterAssistant !== undefined &&
+                typeof policy.startAfterAssistant !== 'boolean')) {
+            return exclusiveToolSchedulingPolicy;
+        }
+        return policy;
+    }
+    catch {
+        return exclusiveToolSchedulingPolicy;
+    }
+}
+//# sourceMappingURL=tool-scheduling-policy.js.map

package/dist/extensions/claude-extension-tools.d.ts

@@ -5,6 +5,7 @@ export declare class ClaudeExtensionToolRegistry implements ToolRegistry {
     private readonly catalog;
     constructor(base: ToolRegistry, catalog: ClaudeExtensionCatalog);
     definitions(): readonly ModelToolDefinition[];
+    schedulingPolicy(call: ModelToolCall): import("../core/runtime.js").ToolSchedulingPolicy;
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
 }

package/dist/extensions/claude-extension-tools.js

@@ -1,3 +1,4 @@
+import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 function skillInput(call) {
     const skill = call.input.skill;
     const args = call.input.args ?? '';
@@ -39,6 +40,11 @@ export class ClaudeExtensionToolRegistry {
             },
         ];
     }
+    schedulingPolicy(call) {
+        if (call.name === 'Skill')
+            return { concurrency: 'exclusive' };
+        return resolveToolSchedulingPolicy(this.base, call);
+    }
     async prepare(call, context) {
         if (call.name !== 'Skill')
             return this.base.prepare(call, context);

package/dist/hooks/claude-hook-tools.d.ts

@@ -19,6 +19,10 @@ export declare class ClaudeHookToolCoordinator implements ToolRegistry, Permissi
     private readonly prepared;
     constructor(options: ClaudeHookToolCoordinatorOptions);
     definitions(): readonly import("../core/runtime.js").ModelToolDefinition[];
+    schedulingPolicy(): {
+        concurrency: "exclusive";
+        startAfterAssistant: boolean;
+    };
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     resolve(call: ModelToolCall, context?: PermissionResolutionContext): Promise<PermissionDecision>;
     execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;

package/dist/hooks/claude-hook-tools.js

@@ -7,6 +7,12 @@ export class ClaudeHookToolCoordinator {
     definitions() {
         return this.options.tools.definitions();
     }
+    schedulingPolicy() {
+        return {
+            concurrency: 'exclusive',
+            startAfterAssistant: true,
+        };
+    }
     async prepare(call, context) {
         const outcome = await this.options.hooks.run({
             ...this.options.session,

package/dist/mcp/claude-mcp-tools.d.ts

@@ -102,6 +102,7 @@ export declare class ClaudeMcpToolRegistry implements ToolRegistry, ClaudeMcpRun
     private constructor();
     static connect(options: ClaudeMcpToolRegistryOptions): Promise<ClaudeMcpToolRegistry>;
     definitions(): readonly ModelToolDefinition[];
+    schedulingPolicy(call: ModelToolCall): import("../core/runtime.js").ToolSchedulingPolicy;
     serverStatuses(): readonly ClaudeMcpServerStatus[];
     inspect(): Promise<readonly ClaudeMcpServerStatus[]>;
     reconnect(name: string): Promise<void>;

package/dist/mcp/claude-mcp-tools.js

@@ -7,6 +7,8 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { ElicitRequestSchema, ElicitationCompleteNotificationSchema, PromptListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 import { redactSensitiveError, redactSensitiveText, redactSensitiveValue, sanitizeChildEnvironment, sensitiveEnvironmentValues, } from '../platform/sensitive-data.js';
 import { parsePermissionUpdates } from '../permissions/permission-updates.js';
 import { loadMcpOAuthProvider, mcpOAuthServerIdentity, } from './claude-mcp-oauth.js';
@@ -77,6 +79,28 @@ const MCP_RESOURCE_TOOL_DEFINITIONS = [
         },
     },
 ];
+const schedulingAjv = new Ajv2020({ strict: false, validateFormats: false });
+function schedulingInputValidator(schema) {
+    try {
+        const validate = schedulingAjv.compile(schema);
+        return (input) => validate(input) === true;
+    }
+    catch {
+        return undefined;
+    }
+}
+function mcpResourceSchedulingInputIsValid(call) {
+    const keys = Object.keys(call.input);
+    if (call.name === 'ListMcpResourcesTool') {
+        return (keys.every((name) => name === 'server') &&
+            (call.input.server === undefined || typeof call.input.server === 'string'));
+    }
+    return ((call.name === 'ReadMcpResourceDirTool' ||
+        call.name === 'ReadMcpResourceTool') &&
+        keys.every((name) => name === 'server' || name === 'uri') &&
+        typeof call.input.server === 'string' &&
+        typeof call.input.uri === 'string');
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -687,6 +711,21 @@ export class ClaudeMcpToolRegistry {
             ...(this.resourceServers.size > 0 ? MCP_RESOURCE_TOOL_DEFINITIONS : []),
         ];
     }
+    schedulingPolicy(call) {
+        if (MCP_RESOURCE_TOOL_DEFINITIONS.some((definition) => definition.name === call.name)) {
+            return mcpResourceSchedulingInputIsValid(call)
+                ? { concurrency: 'concurrent', cancelOnInterrupt: true }
+                : { concurrency: 'exclusive', cancelOnInterrupt: true };
+        }
+        const connected = this.connectedTools.get(call.name);
+        if (connected) {
+            return connected.readOnly &&
+                connected.schedulingInputIsValid?.(call.input)
+                ? { concurrency: 'concurrent', cancelOnInterrupt: true }
+                : { concurrency: 'exclusive', cancelOnInterrupt: true };
+        }
+        return resolveToolSchedulingPolicy(this.options.base, call);
+    }
     serverStatuses() {
         return [...this.statuses.values()].map(({ name, status }) => ({
             name,
@@ -1070,10 +1109,13 @@ export class ClaudeMcpToolRegistry {
                 if (this.connectedTools.has(name) || connectedTools.has(name)) {
                     throw new Error(`Duplicate MCP tool ${name}`);
                 }
+                const inputIsValid = schedulingInputValidator(tool.inputSchema);
                 connectedTools.set(name, {
                     client,
                     serverName,
                     toolName: tool.name,
+                    readOnly: tool.annotations?.readOnlyHint === true,
+                    ...(inputIsValid ? { schedulingInputIsValid: inputIsValid } : {}),
                     sensitiveValues,
                     definition: {
                         name,

package/dist/permissions/claude-permission-resolver.js

@@ -9,7 +9,7 @@ import { shellPermissionMatchCandidates } from './bash-normalization.js';
 import { pathIsInsideRoots, validateBashPathSafety, } from './bash-path-safety.js';
 import { validateSedSafety } from './sed-safety.js';
 import { parseShellRule, shellRuleMatches } from './shell-rule-matching.js';
-import { effectiveAdditionalDirectories, effectivePermissionMode, filePermissionSuggestions, permissionRuleValueFromString, permissionRuleValueToString, shellCommandIsReadOnly, shellPermissionSuggestions, shellSubcommands, skillPermissionSuggestions, } from './permission-updates.js';
+import { effectiveAdditionalDirectories, effectivePermissionMode, filePermissionSuggestions, permissionRuleValueFromString, permissionRuleValueToString, shellInputIsReadOnly, shellPermissionSuggestions, shellSubcommands, skillPermissionSuggestions, } from './permission-updates.js';
 const DEFAULT_BEHAVIOR = {
     Agent: 'allow',
     SendMessage: 'allow',
@@ -536,8 +536,8 @@ export class ClaudePermissionResolver {
         if (command &&
             (permissionMode !== 'auto' || !this.shouldClassify(call)) &&
             subcommands.length > 0 &&
-            subcommands.every((subcommand) => shellCommandIsReadOnly(subcommand) ||
-                matchingRule('allow', subcommandCall(subcommand)) !== undefined)) {
+            (shellInputIsReadOnly(command) ||
+                subcommands.every((subcommand) => matchingRule('allow', subcommandCall(subcommand)) !== undefined))) {
             return annotatePermissionDecision({ behavior: 'allow' }, 'rule');
         }
         const filePath = FILE_TOOLS.has(call.name) ? permissionTarget(call) : null;

package/dist/permissions/permission-updates.d.ts

@@ -11,6 +11,7 @@ export declare function readDirectoryPermissionUpdate(path: string, cwd: string,
 export declare function filePermissionSuggestions(path: string, cwd: string, operation: 'read' | 'write', mode: PermissionMode, outsideWorkingDirectory: boolean, pathsToCheck?: readonly string[], targetIsDirectory?: boolean): readonly PermissionUpdate[];
 export declare function shellSubcommands(command: string, shell?: 'bash' | 'powershell'): readonly string[];
 export declare function shellCommandIsReadOnly(command: string): boolean;
+export declare function shellInputIsReadOnly(command: string): boolean;
 export declare function shellPermissionSuggestions(toolName: 'Bash' | 'PowerShell', command: string, include?: (subcommand: string) => boolean): readonly PermissionUpdate[];
 export declare function skillPermissionSuggestions(skill: string): readonly PermissionUpdate[];
 //# sourceMappingURL=permission-updates.d.ts.map

package/dist/permissions/permission-updates.js

@@ -281,11 +281,23 @@ const READ_ONLY_SHELL_COMMANDS = new Set([
 function commandName(command) {
     return command.trim().split(/\s+/u)[0] ?? '';
 }
+const AMBIGUOUS_SHELL_SYNTAX = /[<>`$*?[\]{}~]/u;
 export function shellCommandIsReadOnly(command) {
-    if (/[<>`]|$\(|\|\||&&|[;|\n\r]/u.test(command))
+    if (AMBIGUOUS_SHELL_SYNTAX.test(command) || /[&;|\n\r]/u.test(command)) {
         return false;
+    }
     return READ_ONLY_SHELL_COMMANDS.has(commandName(command));
 }
+export function shellInputIsReadOnly(command) {
+    if (AMBIGUOUS_SHELL_SYNTAX.test(command) ||
+        /(^|[^&])&($|[^&])/u.test(command)) {
+        return false;
+    }
+    const analysis = analyzeBashCommands(command);
+    return (analysis.parsed &&
+        analysis.commands.length > 0 &&
+        analysis.commands.every(shellCommandIsReadOnly));
+}
 export function shellPermissionSuggestions(toolName, command, include = () => true) {
     const parts = shellSubcommands(command, toolName === 'Bash' ? 'bash' : 'powershell');
     const candidates = (parts.length > 0 ? parts : [command]).filter((part) => !shellCommandIsReadOnly(part) && include(part));

package/dist/tools/claude-capabilities.d.ts

@@ -72,6 +72,7 @@ export declare class ClaudeCapabilityToolRegistry implements ToolRegistry {
     private readonly capabilities;
     constructor(base: ToolRegistry, capabilities: ReadonlySet<string>);
     definitions(): readonly ModelToolDefinition[];
+    schedulingPolicy(call: ModelToolCall): import("../core/runtime.js").ToolSchedulingPolicy;
     prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
     execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
     private assertEnabled;

package/dist/tools/claude-capabilities.js

@@ -1,3 +1,4 @@
+import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 /** Stable environment names. Explicit input booleans override these. */
 export const CLAUDE_CODE_ENABLE_TASKS = 'CLAUDE_CODE_ENABLE_TASKS';
 export const CLAUDE_CODE_DISABLE_CRON = 'CLAUDE_CODE_DISABLE_CRON';
@@ -170,6 +171,10 @@ export class ClaudeCapabilityToolRegistry {
     definitions() {
         return filterClaudeToolDefinitions(this.base.definitions(), this.capabilities);
     }
+    schedulingPolicy(call) {
+        this.assertEnabled(call.name);
+        return resolveToolSchedulingPolicy(this.base, call);
+    }
     async prepare(call, context) {
         this.assertEnabled(call.name);
         return this.base.prepare(call, context);