@zergai/ztc 0.3.0-beta.1 → 0.3.1-dev.36465749722

package/dist/agent/request_encoder.js

@@ -126,6 +126,7 @@ export class RequestEncoder {
                 const verdict = this.deps.selectorVerdict;
                 const rerendered = toolResults.map(r => ({
                     tool_use_id: r.tool_use_id,
+                    ...(r.is_error === undefined ? {} : { is_error: r.is_error }),
                     // Coerce to '' as a last resort: a tool_result entry that carries a
                     // tool_use_id but no content must still encode as a valid tool_result
                     // block (content must be a string for the API), not as undefined —
@@ -241,6 +242,7 @@ export class RequestEncoder {
                 return {
                     type: 'tool_result',
                     tool_use_id: result.tool_use_id,
+                    ...(result.is_error === undefined ? {} : { is_error: result.is_error }),
                     content: [
                         { type: 'text', text: parsed.text },
                         {
@@ -269,6 +271,7 @@ export class RequestEncoder {
             return {
                 type: 'tool_result',
                 tool_use_id: result.tool_use_id,
+                ...(result.is_error === undefined ? {} : { is_error: result.is_error }),
                 content,
             };
         });

package/dist/agent/runtime/command_jobs.d.ts

@@ -0,0 +1,47 @@
+import { type RunShellCommandOptions } from '../../utils/shell.js';
+export type CommandStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted';
+export interface CommandReceipt {
+    job_id: string;
+    status: CommandStatus;
+    command: string;
+    cwd: string;
+    started_at: string;
+    ended_at?: string;
+    exit_code?: number;
+    error?: string;
+    log_path: string;
+    owner_pid?: number;
+    output_truncated?: boolean;
+    dropped_bytes?: number;
+}
+export declare function subscribeCommandJobs(sessionId: string, listener: (jobs: CommandReceipt[]) => void): () => void;
+export declare function listCommandJobs(sessionId: string): CommandReceipt[];
+export declare function startCommandJob(options: {
+    sessionId: string;
+    command: string;
+    cwd: string;
+    timeoutMs?: number;
+    shell: RunShellCommandOptions;
+    maxJobs: number;
+    signal?: AbortSignal;
+}): Promise<CommandReceipt>;
+export declare function readCommandJob(sessionId: string, jobId: string, cursor?: number, waitMs?: number, signal?: AbortSignal): Promise<{
+    output: string;
+    cursor: number;
+    has_more: boolean;
+    job_id: string;
+    status: CommandStatus;
+    command: string;
+    cwd: string;
+    started_at: string;
+    ended_at?: string;
+    exit_code?: number;
+    error?: string;
+    log_path: string;
+    owner_pid?: number;
+    output_truncated?: boolean;
+    dropped_bytes?: number;
+}>;
+export declare function stopCommandJob(sessionId: string, jobId: string): Promise<CommandReceipt>;
+export declare function shutdownCommandJobs(sessionId?: string): Promise<void>;
+export declare function interruptCommandJobs(sessionId: string): Promise<void>;

package/dist/agent/runtime/command_jobs.js

@@ -0,0 +1,268 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runShellCommand } from '../../utils/shell.js';
+const MAX_LOG_BYTES = 16 * 1024 * 1024;
+const MAX_RETAINED_JOBS = 64;
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const sessions = new Map();
+const listeners = new Map();
+export function subscribeCommandJobs(sessionId, listener) {
+    let subscriptions = listeners.get(sessionId);
+    if (!subscriptions) {
+        subscriptions = new Set();
+        listeners.set(sessionId, subscriptions);
+    }
+    subscriptions.add(listener);
+    listener(listCommandJobs(sessionId));
+    return () => { subscriptions.delete(listener); if (!subscriptions.size)
+        listeners.delete(sessionId); };
+}
+function publish(sessionId) {
+    for (const listener of listeners.get(sessionId) ?? []) {
+        try {
+            listener(listCommandJobs(sessionId));
+        }
+        catch { /* a view cannot change command lifecycle */ }
+    }
+}
+/** Bound completed logs across all sessions; active processes keep their logs. */
+function pruneCommandLogs() {
+    const root = join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'command-jobs');
+    const terminal = [];
+    try {
+        for (const folder of readdirSync(root, { withFileTypes: true })) {
+            if (!folder.isDirectory() || !/^[0-9a-f]{32}$/.test(folder.name))
+                continue;
+            const path = join(root, folder.name);
+            for (const file of readdirSync(path, { withFileTypes: true })) {
+                if (!file.isFile() || !/^[0-9a-f-]{36}\.json$/.test(file.name))
+                    continue;
+                try {
+                    const receipt = JSON.parse(readFileSync(join(path, file.name), 'utf8'));
+                    const id = file.name.slice(0, -5);
+                    if (receipt.status === 'running') {
+                        if ([...sessions.values()].some(registry => registry.get(id)?.receipt.status === 'running'))
+                            continue;
+                        if (Number.isSafeInteger(receipt.owner_pid) && receipt.owner_pid > 0) {
+                            try {
+                                process.kill(receipt.owner_pid, 0);
+                                continue;
+                            }
+                            catch (error) {
+                                if (error.code !== 'ESRCH')
+                                    continue;
+                            }
+                        }
+                        else if (Date.now() - Date.parse(receipt.started_at) < RETENTION_MS)
+                            continue;
+                    }
+                    const ended = Date.parse(receipt.ended_at ?? receipt.started_at);
+                    if (Number.isFinite(ended))
+                        terminal.push({ directory: path, id, ended });
+                }
+                catch { /* An incomplete receipt may belong to another writer. */ }
+            }
+        }
+        terminal.sort((a, b) => b.ended - a.ended);
+        for (const [index, entry] of terminal.entries()) {
+            if (index < MAX_RETAINED_JOBS && Date.now() - entry.ended < RETENTION_MS)
+                continue;
+            // Derive both paths from validated filenames, never from receipt.log_path.
+            rmSync(join(entry.directory, `${entry.id}.log`), { force: true });
+            rmSync(join(entry.directory, `${entry.id}.json`), { force: true });
+            for (const registry of sessions.values())
+                registry.delete(entry.id);
+            try {
+                rmdirSync(entry.directory);
+            }
+            catch { /* other retained jobs remain */ }
+        }
+    }
+    catch { /* Retention must not change a command's outcome. Retry on next job. */ }
+}
+function appendCommandOutput(sessionId, job, text) {
+    const bytes = Buffer.from(text);
+    let count = job.receipt.output_truncated ? 0 : Math.min(bytes.length, MAX_LOG_BYTES - job.loggedBytes);
+    // Keep a complete UTF-8 prefix; once truncated, never append later fragments.
+    if (count < bytes.length)
+        while (count > 0 && (bytes[count] & 0xc0) === 0x80)
+            count--;
+    if (count > 0) {
+        appendFileSync(job.receipt.log_path, bytes.subarray(0, count));
+        job.loggedBytes += count;
+    }
+    if (count < bytes.length) {
+        const first = !job.receipt.output_truncated;
+        job.receipt.output_truncated = true;
+        job.receipt.dropped_bytes = (job.receipt.dropped_bytes ?? 0) + bytes.length - count;
+        if (first)
+            save(sessionId, job.receipt);
+    }
+}
+function directory(sessionId) {
+    return join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'command-jobs', createHash('sha256').update(sessionId).digest('hex').slice(0, 32));
+}
+function save(sessionId, receipt) {
+    writeFileSync(join(directory(sessionId), `${receipt.job_id}.json`), JSON.stringify(receipt), { mode: 0o600 });
+}
+function resolveJob(sessionId, jobId) {
+    if (!/^[0-9a-f-]{36}$/.test(jobId))
+        throw new Error('Command job not found in this session');
+    const live = sessions.get(sessionId)?.get(jobId);
+    if (live)
+        return live;
+    let receipt;
+    try {
+        receipt = JSON.parse(readFileSync(join(directory(sessionId), `${jobId}.json`), 'utf8'));
+    }
+    catch {
+        throw new Error('Command job not found in this session');
+    }
+    if (receipt.status === 'running') {
+        receipt = { ...receipt, status: 'interrupted', ended_at: new Date().toISOString(), error: 'Owning ZTC process ended; inspect output before retrying.' };
+        save(sessionId, receipt);
+    }
+    return { receipt, controller: new AbortController(), done: Promise.resolve(), loggedBytes: statSync(receipt.log_path).size };
+}
+export function listCommandJobs(sessionId) {
+    const jobs = [...(sessions.get(sessionId)?.values() ?? [])];
+    return [...jobs.filter(job => job.receipt.status === 'running'), ...jobs.filter(job => job.receipt.status !== 'running').slice(-28)].map(job => ({ ...job.receipt }));
+}
+export async function startCommandJob(options) {
+    const { sessionId } = options;
+    let registry = sessions.get(sessionId);
+    if (!registry) {
+        registry = new Map();
+        sessions.set(sessionId, registry);
+    }
+    if ([...registry.values()].filter(job => job.receipt.status === 'running').length >= options.maxJobs) {
+        throw new Error(`Background command limit (${options.maxJobs}) reached. Read or stop an existing job first.`);
+    }
+    if (options.signal?.aborted)
+        throw new Error('Command cancelled');
+    pruneCommandLogs();
+    mkdirSync(directory(sessionId), { recursive: true, mode: 0o700 });
+    const jobId = randomUUID();
+    const logPath = join(directory(sessionId), `${jobId}.log`);
+    writeFileSync(logPath, '', { mode: 0o600 });
+    const controller = new AbortController();
+    const job = { controller, done: Promise.resolve(), loggedBytes: 0, receipt: {
+            job_id: jobId, status: 'running', command: options.command, cwd: options.cwd,
+            started_at: new Date().toISOString(), log_path: logPath, owner_pid: process.pid,
+        } };
+    save(sessionId, job.receipt);
+    registry.set(jobId, job);
+    publish(sessionId);
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    job.done = runShellCommand(options.command, options.cwd, controller.signal, options.timeoutMs, {
+        ...options.shell, noTimeout: options.timeoutMs === undefined,
+        onOutput: (_stream, text) => appendCommandOutput(sessionId, job, text),
+    }).then(result => {
+        job.receipt.exit_code = result.exitCode;
+        job.receipt.status = result.exitCode === 124 ? 'timed_out' : result.exitCode === 0 ? 'completed' : 'failed';
+        if (result.exitCode !== 0)
+            job.receipt.error = result.stderr.slice(-4096) || `Command exited with code ${result.exitCode}`;
+    }, error => {
+        if (job.receipt.status !== 'interrupted')
+            job.receipt.status = controller.signal.aborted ? 'cancelled' : 'failed';
+        job.receipt.error = error.message;
+    }).finally(() => {
+        options.signal?.removeEventListener('abort', abort);
+        job.receipt.ended_at = new Date().toISOString();
+        try {
+            save(sessionId, job.receipt);
+        }
+        catch (error) {
+            job.receipt.status = 'failed';
+            job.receipt.error = `Could not persist final receipt: ${error.message}`;
+        }
+        pruneCommandLogs();
+        // Terminal receipts remain on disk; bound live metadata while preserving all running jobs.
+        const terminal = [...registry.entries()].filter(([, entry]) => entry.receipt.status !== 'running');
+        for (const [id] of terminal.slice(0, Math.max(0, terminal.length - 64)))
+            registry.delete(id);
+        publish(sessionId);
+    });
+    return { ...job.receipt };
+}
+export async function readCommandJob(sessionId, jobId, cursor = 0, waitMs = 0, signal) {
+    if (!Number.isSafeInteger(cursor) || cursor < 0)
+        throw new Error('cursor must be a non-negative byte offset');
+    if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 60000)
+        throw new Error('wait_ms must be an integer between 0 and 60000');
+    const job = resolveJob(sessionId, jobId);
+    const cancelled = () => new Error(`Command read cancelled; inspect job ${jobId} before retrying. The job may still be running.`);
+    if (signal?.aborted)
+        throw cancelled();
+    if (job.receipt.status === 'running' && waitMs > 0) {
+        let timer;
+        let onAbort;
+        try {
+            await Promise.race([job.done, new Promise((resolve, reject) => {
+                    timer = setTimeout(resolve, waitMs);
+                    onAbort = () => reject(cancelled());
+                    signal?.addEventListener('abort', onAbort, { once: true });
+                })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    const size = statSync(job.receipt.log_path).size;
+    if (cursor > size)
+        throw new Error('cursor is beyond the command output');
+    const buffer = Buffer.alloc(Math.min(16384, size - cursor));
+    const fd = openSync(job.receipt.log_path, 'r');
+    let count;
+    try {
+        count = readSync(fd, buffer, 0, buffer.length, cursor);
+    }
+    finally {
+        closeSync(fd);
+    }
+    // Cursor boundaries are byte offsets; never split an emitted UTF-8 character.
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    let output = '';
+    for (let trim = 0; trim <= Math.min(3, count); trim++) {
+        try {
+            output = decoder.decode(buffer.subarray(0, count - trim));
+            count -= trim;
+            break;
+        }
+        catch {
+            if (trim === Math.min(3, count))
+                throw new Error('cursor must be at a UTF-8 character boundary');
+        }
+    }
+    return { ...job.receipt, output, cursor: cursor + count, has_more: cursor + count < size };
+}
+export async function stopCommandJob(sessionId, jobId) {
+    const job = resolveJob(sessionId, jobId);
+    if (job.receipt.status === 'running') {
+        job.controller.abort();
+        await job.done;
+    }
+    return { ...job.receipt };
+}
+export async function shutdownCommandJobs(sessionId) {
+    const registries = sessionId ? [sessions.get(sessionId)] : [...sessions.values()];
+    const pending = [];
+    for (const registry of registries)
+        for (const job of registry?.values() ?? []) {
+            if (job.receipt.status !== 'running')
+                continue;
+            job.receipt.status = 'interrupted';
+            job.controller.abort();
+            pending.push(job.done);
+        }
+    await Promise.all(pending);
+}
+export async function interruptCommandJobs(sessionId) {
+    await Promise.all(listCommandJobs(sessionId).filter(job => job.status === 'running').map(job => stopCommandJob(sessionId, job.job_id)));
+}

package/dist/agent/runtime/execution_context.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionSettings } from '../../config/execution.js';
+import { resolveExecutionSettings } from '../../config/execution.js';
+import type { CommandReceipt } from './command_jobs.js';
+export interface ExecutionContext {
+    mode: string;
+    cwd: string;
+    tools: string[];
+    mux: boolean;
+    configScope: string;
+    maxTokens?: number;
+    outputLimitSource: string;
+    settings: Required<ExecutionSettings>;
+    jobs: CommandReceipt[];
+}
+export declare function describeExecutionContext(context: ExecutionContext): string;
+export { resolveExecutionSettings };

package/dist/agent/runtime/execution_context.js

@@ -0,0 +1,20 @@
+import { resolveExecutionSettings } from '../../config/execution.js';
+export function describeExecutionContext(context) {
+    const names = new Set(context.tools);
+    const shell = ['run_command', 'Bash', 'exec_command', 'shell_command'].filter(name => names.has(name));
+    const panes = ['create_terminal_pane', 'read_terminal_pane', 'write_terminal_pane'].filter(name => names.has(name));
+    return [
+        '## Current execution capabilities (host facts; refreshed each request)',
+        `Mode: ${context.mode}. Cwd: ${context.cwd}. Config write scope: ${context.configScope}.`,
+        `Output cap: ${context.maxTokens ?? 'provider default'} (source: ${context.outputLimitSource}). Use /config max-tokens <number|default> to change it.`,
+        `Shell: ${shell.length ? shell.join(', ') : 'unavailable in the current tool surface'}.`,
+        `Mux: ${context.mux ? 'connected' : 'unavailable'}. Pane tools: ${panes.join(', ') || 'unavailable in this mode'}.`,
+        `Shell-pane policy: ${context.settings.shellPanePolicy === 'on_request' ? 'create a shell pane only when the user explicitly requests a visible or interactive shell; otherwise use run_command' : 'may create shell panes automatically when useful'}.`,
+        `Registered tools: ${context.tools.slice(0, 80).join(', ')}. Deferred schemas can be discovered with tool_search when available.`,
+        `Batch limit: ${context.settings.maxCallsPerResponse}. Read concurrency: ${context.settings.readConcurrency}. Inspect a failed or running command before submitting dependent work.`,
+        'For multiline scripts use run_command stdin or write_file and execute the file. Pane text supports multiline submission; raw Ctrl+C (U+0003, submit=false) cancels stuck shell input. A write acknowledgement does not prove command success.',
+        `Managed commands: ${context.jobs.length ? JSON.stringify(context.jobs.map(({ job_id, status, cwd, exit_code }) => ({ job_id, status, cwd, exit_code }))) : 'none'}. Background commands ${context.settings.interruptBackgroundJobs ? 'are cancelled' : 'survive'} on turn interruption; application shutdown stops owned local jobs. Remote cleanup belongs to the launched command.`,
+        'If a tool is unavailable, inspect these current facts and mode restrictions. Do not infer that the session never had shell access from a previous mode or a failed invocation.',
+    ].join('\n');
+}
+export { resolveExecutionSettings };

package/dist/agent/runtime/recovery.d.ts

@@ -0,0 +1,9 @@
+import { type ExecutionSettings } from '../../config/execution.js';
+/** Group failures by cause rather than command spelling, paths, or changing IDs. */
+export declare function normalizeFailure(content: string): string;
+/** One budget per run; a new, substantive successful observation resets it. */
+export declare function createRecoveryGuard(settings: ExecutionSettings): (results: readonly {
+    name: string;
+    content: string;
+    isError: boolean;
+}[]) => "continue" | "recover" | "stop";

package/dist/agent/runtime/recovery.js

@@ -0,0 +1,71 @@
+import { resolveExecutionSettings } from '../../config/execution.js';
+/** Group failures by cause rather than command spelling, paths, or changing IDs. */
+export function normalizeFailure(content) {
+    const text = content.toLowerCase();
+    if (/not_executed/.test(text))
+        return '';
+    for (const [pattern, cause] of [
+        [/heredoc|unexpected end of file|unterminated/, 'unfinished shell input'],
+        [/permission denied|eacces/, 'permission denied'],
+        [/not found|enoent|unknown tool|unavailable/, 'capability or file unavailable'],
+        [/timeout|timed out/, 'timeout'],
+        [/syntaxerror|syntax error|invalid.*syntax/, 'syntax error'],
+    ])
+        if (pattern.test(text))
+            return cause;
+    const exit = text.match(/command failed \(exit (\d+)\)/);
+    if (exit)
+        return `command exit ${exit[1]}`;
+    return text.split('\n')[0].replace(/['"`][^'"`]*['"`]/g, '<value>').replace(/\d+/g, '#').trim().slice(0, 240);
+}
+/** One budget per run; a new, substantive successful observation resets it. */
+export function createRecoveryGuard(settings) {
+    const limits = resolveExecutionSettings(settings);
+    let cause = '';
+    let failures = 0;
+    let attempts = 0;
+    let neutralSteps = 0;
+    const observations = new Set();
+    return (results) => {
+        let failed = false;
+        let progress = false;
+        let neutral = false;
+        for (const result of results) {
+            if (result.isError) {
+                const next = normalizeFailure(result.content);
+                if (!next)
+                    continue;
+                failed = true;
+                failures = next === cause ? failures + 1 : 1;
+                cause = next;
+            }
+            else {
+                const signature = `${result.name}\0${result.content}`;
+                // Acknowledgements and unchanged polling are delivery facts, not progress.
+                const acknowledgement = /^(Input (?:delivered|queued|sent)|Sent input|\(Terminal buffer is empty\))/.test(result.content)
+                    || /"status":"running"/.test(result.content) && /"output":""/.test(result.content);
+                neutral ||= acknowledgement;
+                if (result.content.trim() && !acknowledgement && !observations.has(signature))
+                    progress = true;
+                observations.add(signature);
+            }
+        }
+        if (progress && !failed) {
+            failures = 0;
+            cause = '';
+            attempts = 0;
+            neutralSteps = 0;
+        }
+        if (failures < limits.repeatedFailureLimit)
+            return 'continue';
+        // One neutral response may deliver an interrupt or wait for a job, then
+        // the model must inspect new output. This never renews the recovery budget.
+        if (!failed && neutral && attempts > 0 && neutralSteps++ < 1)
+            return 'continue';
+        if (limits.recovery === 'pause' || attempts >= limits.recoveryAttempts)
+            return 'stop';
+        attempts++;
+        neutralSteps = 0;
+        return 'recover';
+    };
+}

package/dist/agent/runtime/tool_runtime.js

@@ -27,7 +27,7 @@ function isHostControlPlaneWrite(tool, args, cwd) {
 async function executeTool(name, args, tools, context) {
     const tool = getTool(name, tools);
     if (!tool)
-        throw new Error('Unknown tool: ' + name);
+        throw new Error(`Unknown tool: ${name}. It is unavailable in the current mode or provider surface. Inspect current execution capabilities and use an available tool; shell execution requires run_command or a registered alias.`);
     return tool.execute(args, context);
 }
 function buildHookText(messages) {
@@ -319,6 +319,8 @@ export async function executeToolWithRuntime(name, args, options) {
             ]).finally(() => { if (timer)
                 clearTimeout(timer); });
         }
+        if (tool?.isErrorResult?.(output))
+            throw new Error(output);
         // Global output cap: prevent any single tool result from dominating the
         // context window. Claude Code caps at ~100K chars; we use 80K (~20K tokens).
         // The model gets the head + tail of large outputs to preserve both the

package/dist/agent/runtime/tool_scheduler.d.ts

@@ -0,0 +1,6 @@
+import type { ExecutionSettings } from '../../config/execution.js';
+import type { ToolUseBlock } from '../backends/types.js';
+import type { Tool } from '../tools/types.js';
+/** Only explicitly declared reads may overlap. Writes and unknown tools are barriers. */
+export declare function scheduleToolBatch<T>(calls: readonly ToolUseBlock[], tools: readonly Tool[], settings: ExecutionSettings, execute: (call: ToolUseBlock, skipReason?: string) => Promise<T>, blocksFollowing: (result: T) => boolean, signal?: AbortSignal, exclusiveId?: string | null): Promise<T[]>;
+export declare function commandStillRunning(content: string): boolean;

package/dist/agent/runtime/tool_scheduler.js

@@ -0,0 +1,57 @@
+import { resolveExecutionSettings } from '../../config/execution.js';
+import { resolveToolEffect } from './tool_effects.js';
+/** Only explicitly declared reads may overlap. Writes and unknown tools are barriers. */
+export async function scheduleToolBatch(calls, tools, settings, execute, blocksFollowing, signal, exclusiveId) {
+    const limits = resolveExecutionSettings(settings);
+    const registered = new Map(tools.map(tool => [tool.definition.name, tool]));
+    const parallel = (call) => {
+        const tool = registered.get(call.name);
+        return tool?.parallelSafe === true && resolveToolEffect(tool) === 'read';
+    };
+    const results = [];
+    let effectsBlocked = false;
+    let stopped = calls.length > limits.maxCallsPerResponse
+        ? `batch_limit: ${calls.length} calls exceeds ${limits.maxCallsPerResponse}; submit a smaller batch after inspecting results.`
+        : '';
+    for (let index = 0; index < calls.length;) {
+        const call = calls[index];
+        if (signal?.aborted)
+            stopped = 'cancelled: the turn was interrupted.';
+        if (stopped) {
+            results.push(await execute(call, `not_executed: ${stopped}`));
+            index++;
+            continue;
+        }
+        if (effectsBlocked && !parallel(call)) {
+            results.push(await execute(call, 'not_executed: a previous call failed or is still running; inspect its result before continuing effects.'));
+            index++;
+            continue;
+        }
+        if (exclusiveId && call.id !== exclusiveId) {
+            results.push(await execute(call, 'not_executed: exclusive safety transition must run alone.'));
+            index++;
+            continue;
+        }
+        let end = index + 1;
+        if (!exclusiveId && parallel(call)) {
+            while (end < calls.length && end - index < limits.readConcurrency && parallel(calls[end]))
+                end++;
+        }
+        const batch = await Promise.all(calls.slice(index, end).map(item => execute(item)));
+        results.push(...batch);
+        if (batch.some(blocksFollowing)) {
+            effectsBlocked = true;
+        }
+        index = end;
+    }
+    return results;
+}
+export function commandStillRunning(content) {
+    try {
+        const result = JSON.parse(content);
+        return result.status === 'running' && typeof result.job_id === 'string';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/agent/subagent.js

@@ -14,6 +14,9 @@ import { debugLog } from '../utils/debug_log.js';
 import { createBackendForProvider } from './backends/index.js';
 import { accountBackendOptions, resolveRotation } from './backends/account_pool.js';
 import { buildAccountRotation, subagentShouldRotate } from './backends/rotation_factory.js';
+import { describeExecutionContext, resolveExecutionSettings } from './runtime/execution_context.js';
+import { createRecoveryGuard } from './runtime/recovery.js';
+import { scheduleToolBatch, commandStillRunning } from './runtime/tool_scheduler.js';
 import { configStore } from '../config.js';
 import { ToolResponseStore } from './tool_response_store.js';
 import { RESEARCH_TOOLS } from '../worker/toolsets.js';
@@ -118,6 +121,7 @@ export class SubAgent {
         let completedCleanly = false;
         // R5 parity: same progress-delta guard as the main loop (shared loop_policy).
         const applyRepeatGuard = createRepeatGuard();
+        const recovery = createRecoveryGuard(configStore.get().execution ?? {});
         debug('Starting task: %s', task.slice(0, 100) + (task.length > 100 ? '...' : ''));
         const systemPrompt = opts?.systemPrompt ?? renderPrompt('subagent_research', {
             max_iterations: maxIterations,
@@ -153,7 +157,11 @@ export class SubAgent {
                     maxTokens: 2048,
                     // R7 parity: pin the task in request.system so a long subagent run
                     // can't lose the task framing the same way the main loop could (F9).
-                    system: pinnedTaskSystem(systemPrompt, task),
+                    system: pinnedTaskSystem(systemPrompt, task) + '\n\n' + describeExecutionContext({
+                        mode: 'delegated worker', cwd: this.cwd, tools: tools.map(tool => tool.definition.name),
+                        mux: false, configScope: configStore.getConfigScope(), maxTokens: 2048,
+                        outputLimitSource: 'delegated worker budget', settings: resolveExecutionSettings(configStore.get().execution), jobs: [],
+                    }),
                     messages: this.formatMessages(messages),
                     tools: tools.map(t => t.definition),
                     // The inherited backend is pinned to the parent conversation; this is
@@ -194,12 +202,11 @@ export class SubAgent {
                 }
                 debug('Executing %d tool(s): %s', toolUseBlocks.length, toolUseBlocks.map(tb => tb.name).join(', '));
                 // Execute tools and track what was accessed
-                const toolResults = [];
-                for (const toolBlock of toolUseBlocks) {
-                    if (signal?.aborted)
-                        throw new Error('Sub-agent cancelled');
-                    checkTimeout();
+                const toolResults = await scheduleToolBatch(toolUseBlocks, tools, configStore.get().execution ?? {}, async (toolBlock, skipReason) => {
                     try {
+                        if (skipReason)
+                            throw new Error(skipReason);
+                        checkTimeout();
                         const toolStart = Date.now();
                         const result = await executeToolWithRuntime(toolBlock.name, toolBlock.input, {
                             tools,
@@ -222,19 +229,21 @@ export class SubAgent {
                         if (!result.isError) {
                             this.trackToolUsage(toolBlock.name, result.effectiveArgs, result.content);
                         }
-                        toolResults.push({
+                        return {
+                            is_error: result.isError,
                             tool_use_id: toolBlock.id,
                             content: applyRepeatGuard(toolBlock.name, toolBlock.input, result.isError ? `Error: ${result.content}` : result.content),
-                        });
+                        };
                     }
                     catch (err) {
                         debug('Tool %s failed: %s', toolBlock.name, err.message);
-                        toolResults.push({
+                        return {
+                            is_error: true,
                             tool_use_id: toolBlock.id,
                             content: `Error: ${err.message}`
-                        });
+                        };
                     }
-                }
+                }, result => result.is_error || commandStillRunning(result.content), signal);
                 opts?.onIteration?.({
                     iteration: iterations,
                     max: maxIterations,
@@ -268,6 +277,14 @@ export class SubAgent {
                     content: JSON.stringify(toolResults),
                     timestamp: new Date()
                 });
+                const recoveryAction = recovery(toolResults.map((result, index) => ({
+                    name: toolUseBlocks[index].name, content: result.content, isError: result.is_error,
+                })));
+                if (recoveryAction === 'stop')
+                    throw new Error('Automatic recovery budget exhausted after repeated tool failures.');
+                if (recoveryAction === 'recover')
+                    messages.push({ id: `recovery_${iterations}`, role: 'user',
+                        content: 'Repeated failures: inspect current capabilities, then try one changed recovery approach. Do not repeat the failing sequence.', timestamp: new Date() });
             }
             const durationMs = Date.now() - startTime;
             // Exhausted maxIterations while still requesting tools = did NOT finish.
@@ -375,7 +392,8 @@ export class SubAgent {
                             content: toolResults.map(tr => ({
                                 type: 'tool_result',
                                 tool_use_id: tr.tool_use_id,
-                                content: tr.content
+                                content: tr.content,
+                                is_error: tr.is_error,
                             }))
                         };
                     }

package/dist/agent/tool_response_store.d.ts

@@ -24,6 +24,7 @@ export interface ToolResponseMeta {
     timestamp: string;
     turn: number;
     partial?: boolean;
+    is_error?: boolean;
     source_path?: string;
     content_hash?: string;
     recalledAtTurn?: number;
@@ -98,6 +99,7 @@ export declare class ToolResponseStore {
     put(toolUseId: string, toolName: string, content: string, partial?: boolean, context?: {
         sourcePath?: string | null;
         dedupable?: boolean;
+        isError?: boolean;
     }): {
         meta: ToolResponseMeta;
         rendered: string;