@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/tools/shell.js

@@ -1,10 +1,13 @@
 import { resolve } from 'path';
 import { ToolCapability } from '../runtime/capabilities.js';
 import { runShellCommand } from '../../utils/shell.js';
-import { startCommandJob, readCommandJob, stopCommandJob } from '../runtime/command_jobs.js';
+import { startCommandJob, readCommandJob, stopCommandJob, waitForCommandProgress } from '../runtime/command_jobs.js';
 import { resolveExecutionSettings } from '../../config/execution.js';
 import { configStore } from '../../config.js';
 import { assertTemporaryRootSafe, isPathWithinRoot } from '../../utils/temporary_write_root.js';
+import { parseCheckedCommandPlan } from '../runtime/checked_commands.js';
+import { parseVerificationRequest } from '../runtime/source_verification_contract.js';
+import { createCommandVerification, finishCommandVerification, projectCurrentVerification } from '../runtime/source_verification.js';
 export const FAILURE_OUTPUT_LIMIT = 2000;
 /**
  * Bound failure output without losing the tail: build and test summaries and
@@ -20,31 +23,29 @@ export function summarizeCommandFailure(output, limit = FAILURE_OUTPUT_LIMIT) {
     return `${output.slice(0, headLength)}\n… [${omitted} characters omitted] …\n${output.slice(-tailLength)}`;
 }
 /**
- * R6/F7: actionable hint for a failed shell command, keyed on exit code and
- * stderr pattern. Returns null when nothing useful can be said. Pure + exported
+ * R6/F7: actionable hints require observed diagnostics or executor evidence.
+ * A nonzero predicate outcome alone establishes neither cause nor completeness.
+ * Returns null when nothing useful can be said. Pure + exported
  * so it can be unit-tested without spawning a process.
  */
-export function shellErrorHint(exitCode, stderr, hasStdout) {
-    // 124 is the timeout kill path (utils/shell.ts). Checked first: a timed-out
-    // command may have printed partial output, and the partial-output branch
-    // below would diagnose it as a permission problem.
-    if (exitCode === 124) {
-        return 'The command hit its timeout and was killed — its output is incomplete. Retry with a larger timeout (maximum 600000 ms), or narrow the command so it finishes sooner.';
+export function shellErrorHint(exitCode, stderr, hasStdout, timedOut = false) {
+    // A program can exit 124 without a timer firing. Only the executor knows the cause.
+    if (timedOut) {
+        return 'The command hit its timeout and local cleanup was requested; its output is incomplete. Retry with a larger timeout, use a managed background command for longer work, or narrow the command so it finishes sooner. Remote cleanup is unknown.';
     }
     if (/unrecognized option|invalid option|illegal option/i.test(stderr)) {
         return "The command rejected an option it does not recognize. If it looks like a ZTC concept (e.g. '--pane'), that is not a shell flag — pane targeting uses the pane tools (create_ztc_pane / ask_ztc_pane). Otherwise re-run with valid flags only.";
     }
-    if (exitCode === 127) {
+    if (exitCode === 127 && /not found/i.test(stderr)) {
         return 'Command not found — the binary is not installed or not on PATH. Check the name or install it.';
     }
-    // Partial-output wins over permission-denied: a command that printed results yet
-    // exited non-zero (e.g. `find` hitting a permission-denied subtree) is the F7
-    // "treated partial output as authoritative" trap — warn about completeness first.
-    if (hasStdout) {
-        return 'This command produced output but exited non-zero — the output is PARTIAL, not authoritative. Some entries were likely skipped (e.g. permission-denied subtrees). Do not treat it as complete; narrow the path or read specific files directly.';
+    if (/permission denied|EACCES/i.test(stderr)) {
+        return hasStdout
+            ? 'Permission denied — the command reported an access failure while producing output. Do not treat the output as complete for the inaccessible resources; inspect the reported paths and correct access or narrow the command.'
+            : 'Permission denied — the command reported an access failure. Inspect the reported path and permissions or use a different command.';
     }
-    if (exitCode === 126 || /permission denied|EACCES/i.test(stderr)) {
-        return 'Permission denied — the file is not executable or you lack access. Check permissions or use a different command.';
+    if (hasStdout) {
+        return 'This command produced output and exited non-zero. Output completeness and the failure cause are unknown; inspect the captured diagnostics and the program’s exit-status contract before retrying.';
     }
     return null;
 }
@@ -56,14 +57,27 @@ function failedCommandReceipt(content) {
         return false;
     }
 }
+function executionObservation(policy) {
+    if (!policy)
+        return {};
+    const observed = Date.now();
+    const elapsed = observed - Date.parse(policy.started_at);
+    return { execution_policy: policy, ...(Number.isSafeInteger(elapsed) && elapsed >= 0
+            ? { observed_at: new Date(observed).toISOString(), elapsed_ms: elapsed } : {}) };
+}
 // --- Shell Tool ---
+function resolveRunCommandCwd(args, context) {
+    const baseCwd = context?.cwd || process.cwd();
+    return args.cwd ? resolve(baseCwd, String(args.cwd)) : baseCwd;
+}
 export const runCommandTool = {
     isErrorResult: failedCommandReceipt,
+    resolveExecutionCwd: resolveRunCommandCwd,
     capabilities: [ToolCapability.SHELL_EXEC],
     definition: {
         name: 'run_command',
         overlapsProviderHarness: true,
-        description: 'Run a shell command in the workspace and return stdout/stderr. Use for inspection, builds, servers, or scripts that are better expressed as commands than file tools.',
+        description: 'Run either ordinary shell text or an explicit checked literal-argv plan. For builds/tests prefer checked steps and bounded managed logs instead of piping shell text into tail. Checked pipelines report every declared stage and gate later steps; they do not certify source/build correctness or child-script internals. Local macOS/Linux Bash only.',
         parameters: {
             type: 'object',
             properties: {
@@ -71,34 +85,74 @@ export const runCommandTool = {
                     type: 'string',
                     description: 'Shell command to execute'
                 },
+                checked: {
+                    type: 'object', description: 'Mutually exclusive with command. Up to 8 ordered steps, each with up to 8 concurrent pipeline stages. Literal executable/args only; default acceptable_exit_codes [0]. A later step runs only after every prior declared stage is accepted. Explicit predicates may accept 1 or 141; exit 141 is not proven SIGPIPE. Total normalized plan ≤16KiB.',
+                    properties: { steps: { type: 'array', minItems: 1, maxItems: 8, items: {
+                                type: 'object', required: ['id', 'pipeline'], additionalProperties: false,
+                                properties: { id: { type: 'string', maxLength: 64 }, pipeline: {
+                                        type: 'array', minItems: 1, maxItems: 8, items: {
+                                            type: 'object', required: ['executable', 'args'], additionalProperties: false,
+                                            properties: { executable: { type: 'string', maxLength: 512 }, args: {
+                                                    type: 'array', maxItems: 64, items: { type: 'string', maxLength: 4096 }
+                                                },
+                                                acceptable_exit_codes: { type: 'array', minItems: 1, maxItems: 8,
+                                                    items: { type: 'integer', minimum: 0, maximum: 255 } } },
+                                        },
+                                    } },
+                            } } }, required: ['steps'], additionalProperties: false,
+                },
                 cwd: {
                     type: 'string',
                     description: 'Working directory for the command'
                 },
+                verification: {
+                    type: 'object', description: 'Optional scoped source observations. Declared purpose is separate from actual process outcome and never certifies semantic qualification. Capture up to64 relative files (2MiB each,8MiB total), with source digests and Git metadata; current/stale/unknown applicability is checked separately. Local execution only.',
+                    required: ['purpose', 'scope', 'source_paths'], additionalProperties: false,
+                    properties: {
+                        purpose: { type: 'string', enum: ['compile', 'test', 'benchmark', 'qualification'] },
+                        scope: { type: 'string', maxLength: 512 },
+                        source_paths: { type: 'array', minItems: 1, maxItems: 64, items: { type: 'string', maxLength: 512 } },
+                        environment_id: { type: 'string', maxLength: 256 }, build_identity: { type: 'string', maxLength: 256 },
+                        instrumentation: { type: 'string', enum: ['production', 'diagnostic', 'unknown'] },
+                    },
+                },
                 timeout: {
-                    type: 'string',
-                    description: 'Timeout in milliseconds (default: 30000)'
+                    type: 'integer', minimum: 1, maximum: 86400000,
+                    description: 'Process lifetime in milliseconds. Foreground: 1–600000, omitted uses local 30000 or Docker 120000. Native background: 1–86400000 (24 hours), omitted is unlimited. Independent of initial yield and read waits. Outer owner deadlines still apply; local wrapper cleanup does not prove remote cleanup.'
                 },
                 background: { type: 'boolean', description: 'Start a managed background job. Use read_command and stop_command with its job_id; survives a turn interrupt by default.' },
-                yield_time_ms: { type: 'number', description: 'Initial background wait, 0–60000ms (default 1000).' },
+                yield_time_ms: { type: 'integer', minimum: 0, maximum: 60000, description: 'Initial background observation wait, 0–60000ms (default 1000). Expiry returns a running receipt and does not stop the process.' },
                 stdin: {
                     type: 'string',
                     description: 'Optional text written to the command stdin. Prefer this over heredocs or nested quoting for multi-line payloads (e.g. git commit -F -).'
                 }
             },
-            required: ['command']
+            oneOf: [{ required: ['command'] }, { required: ['checked'] }],
         }
     },
     execute: async (args, context) => {
-        if (args.command === undefined || args.command === null) {
+        const hasChecked = Object.hasOwn(args, 'checked');
+        const hasVerification = Object.hasOwn(args, 'verification');
+        const verificationRequest = hasVerification ? parseVerificationRequest(args.verification) : undefined;
+        if (hasVerification && !verificationRequest)
+            throw new Error('run_command: invalid source verification request');
+        if (hasVerification && process.env.ZTC_DOCKER_CONTAINER) {
+            throw new Error('Source verification supports local execution only; Docker source inputs cannot be captured from this host.');
+        }
+        if (hasChecked && Object.hasOwn(args, 'command')) {
+            throw new Error('run_command: provide exactly one of command or checked; they are mutually exclusive');
+        }
+        const checked = hasChecked ? parseCheckedCommandPlan(args.checked) : undefined;
+        if (hasChecked && !checked)
+            throw new Error('run_command: invalid checked plan');
+        if (!hasChecked && (args.command === undefined || args.command === null)) {
             throw new Error('run_command: command argument is required but was not provided');
         }
-        const command = String(args.command);
+        const command = checked ? JSON.stringify(checked) : String(args.command);
         if (command === 'undefined' || command.trim() === '') {
             throw new Error(`run_command: command argument is invalid: "${command}"`);
         }
-        const baseCwd = context?.cwd || process.cwd();
-        const cwd = args.cwd ? resolve(baseCwd, String(args.cwd)) : baseCwd;
+        const cwd = resolveRunCommandCwd(args, context);
         const temporaryWriteRoot = context?.temporaryWriteRoot === undefined
             ? undefined
             : resolve(context.temporaryWriteRoot);
@@ -117,17 +171,23 @@ export const runCommandTool = {
             if (parsed <= 0) {
                 throw new Error('run_command: timeout must be greater than 0 milliseconds');
             }
-            if (parsed > 600000) {
-                throw new Error('run_command: timeout must be less than or equal to 600000 milliseconds');
+            if (typeof args.timeout === 'boolean' || !Number.isSafeInteger(parsed)) {
+                throw new Error('run_command: timeout must be an integer number of milliseconds');
+            }
+            const maximum = args.background === true ? 86400000 : 600000;
+            if (parsed > maximum) {
+                throw new Error(`run_command: timeout must be less than or equal to ${maximum} milliseconds`);
             }
-            timeoutMs = Math.floor(parsed);
+            timeoutMs = parsed;
         }
         // Use runShellCommand which handles docker routing via ZTC_DOCKER_CONTAINER
         const config = configStore.get();
-        const profileId = config.permissionProfile || 'trusted';
-        const baseProfile = config.permissionProfiles?.[profileId];
+        const admitted = context?.commandPolicy;
+        const profileId = admitted?.profileId ?? config.permissionProfile ?? 'trusted';
+        const baseProfile = admitted === undefined ? config.permissionProfiles?.[profileId] : admitted.profile;
+        const baseSandbox = admitted === undefined ? config.sandbox : admitted.sandbox;
         const profile = temporaryWriteRoot === undefined
-            ? config.permissionProfiles?.[profileId]
+            ? baseProfile
             : {
                 ...(baseProfile || {}),
                 allowedPaths: [temporaryWriteRoot],
@@ -137,9 +197,9 @@ export const runCommandTool = {
                 },
             };
         const sandbox = temporaryWriteRoot === undefined
-            ? config.sandbox
+            ? baseSandbox
             : {
-                ...(config.sandbox || {}),
+                ...(baseSandbox || {}),
                 requireOsEnforcement: true,
             };
         const stdin = typeof args.stdin === 'string'
@@ -153,6 +213,7 @@ export const runCommandTool = {
             temporaryWriteRoot,
             stdin,
             env: context?.subprocessEnv,
+            ...(checked ? { checked } : {}),
         };
         if (args.background === true) {
             if (temporaryWriteRoot)
@@ -163,44 +224,107 @@ export const runCommandTool = {
             if (!Number.isSafeInteger(wait) || wait < 0 || wait > 60000)
                 throw new Error('yield_time_ms must be between 0 and 60000');
             const settings = resolveExecutionSettings(config.execution);
+            const verification = verificationRequest ? await createCommandVerification(verificationRequest, cwd, command, checked ? 'checked' : 'shell') : undefined;
             const receipt = await startCommandJob({ sessionId: context.sessionId, command, cwd, timeoutMs,
                 shell: shellOptions, maxJobs: settings.maxBackgroundJobs,
-                signal: settings.interruptBackgroundJobs ? context.signal : undefined });
-            return JSON.stringify(await readCommandJob(context.sessionId, receipt.job_id, 0, wait, context.signal));
+                signal: settings.interruptBackgroundJobs ? context.signal : undefined, verification,
+                canInspectVerificationSource: context.canInspectVerificationSource });
+            const result = await readCommandJob(context.sessionId, receipt.job_id, 0, wait, context.signal, context.canInspectVerificationSource);
+            context.onManagedCommand?.({ sessionId: context.sessionId, result, requestedWaitMs: wait, kind: 'launch' });
+            return JSON.stringify(result);
+        }
+        const initialVerification = verificationRequest ? await createCommandVerification(verificationRequest, cwd, command, checked ? 'checked' : 'shell') : undefined;
+        let launchPolicy;
+        let result;
+        try {
+            result = await runShellCommand(command, cwd, context?.signal, timeoutMs, { ...shellOptions,
+                onExecutionPolicy: policy => { launchPolicy = policy; },
+                onOutput: (stream, chunk) => {
+                    try {
+                        context?.onOutput?.(stream, chunk);
+                    }
+                    catch { /* informational observer only */ }
+                } });
+        }
+        catch (error) {
+            if (!initialVerification)
+                throw error;
+            const observation = executionObservation(launchPolicy);
+            const cancelled = Boolean(context?.signal?.aborted);
+            const verification = await finishCommandVerification(initialVerification, cancelled ? 'cancelled' : 'unknown', context?.canInspectVerificationSource);
+            context?.onVerificationReceipt?.(verification);
+            return JSON.stringify({ command, cwd, stdout: '', stderr: error.message,
+                ...observation,
+                status: cancelled ? 'cancelled' : 'failed', verification,
+                verification_current: await projectCurrentVerification(verification, context?.canInspectVerificationSource) });
+        }
+        const observation = executionObservation(result.execution_policy);
+        if (initialVerification) {
+            const outcome = result.checked ? result.checked.status === 'passed' ? 'passed'
+                : result.checked.status === 'timed_out' ? 'timed_out' : result.checked.status === 'cancelled' ? 'cancelled' : 'failed'
+                : result.timedOut === true ? 'timed_out' : result.exitCode === 0 ? 'passed' : 'failed';
+            const verification = await finishCommandVerification(initialVerification, outcome, context?.canInspectVerificationSource);
+            context?.onVerificationReceipt?.(verification);
+            return JSON.stringify({ command: result.command, cwd: result.cwd, stdout: result.stdout, stderr: result.stderr,
+                truncated: result.truncated, exit_code: result.exitCode,
+                ...observation,
+                status: outcome === 'passed' ? 'completed' : outcome === 'timed_out' ? 'timed_out' : outcome === 'cancelled' ? 'cancelled' : 'failed',
+                ...(result.checked ? { checked: result.checked } : {}), verification,
+                verification_current: await projectCurrentVerification(verification, context?.canInspectVerificationSource) });
+        }
+        if (result.checked) {
+            return JSON.stringify({ command: result.command, cwd: result.cwd, stdout: result.stdout,
+                stderr: result.stderr, truncated: result.truncated, exit_code: result.exitCode,
+                ...observation,
+                status: result.checked.status === 'passed' ? 'completed' : result.checked.status === 'timed_out'
+                    ? 'timed_out' : result.checked.status === 'cancelled' ? 'cancelled' : 'failed', checked: result.checked });
         }
-        const result = await runShellCommand(command, cwd, context?.signal, timeoutMs, shellOptions);
         // Handle non-zero exit codes
         if (result.exitCode !== 0) {
             const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
             const outputSnippet = summarizeCommandFailure(output) || '(no output)';
-            // R6/F7: an exit code alone is not actionable — add a cause+fix hint so the
-            // model self-corrects instead of re-running the mistake or trusting partial
-            // output as authoritative.
-            const hint = shellErrorHint(result.exitCode, result.stderr ?? '', Boolean(result.stdout?.trim()));
-            throw new Error(`Command failed (exit ${result.exitCode}):\n${outputSnippet}${hint ? `\n\nhint: ${hint}` : ''}`);
+            // R6/F7: retain the failed status; hints distinguish observed causes from
+            // unknown completeness without guessing which compound stage failed.
+            const hint = shellErrorHint(result.exitCode, result.stderr ?? '', Boolean(result.stdout?.trim()), result.timedOut === true);
+            throw new Error(`Command failed (exit ${result.exitCode}):\n${outputSnippet}${result.execution_policy ? `\nexecution: ${JSON.stringify(observation)}` : ''}${hint ? `\n\nhint: ${hint}` : ''}`);
         }
         return JSON.stringify({
             command: result.command,
             cwd: result.cwd,
             stdout: result.stdout,
             stderr: result.stderr,
-            truncated: result.truncated
+            truncated: result.truncated,
+            ...observation
         });
     }
 };
 export const readCommandTool = {
+    parallelSafe: true,
     isErrorResult: failedCommandReceipt,
     capabilities: [ToolCapability.FILE_READ],
     definition: {
-        name: 'read_command', description: 'Read a managed command receipt and up to 16KB of incremental output. Cursor is a byte offset returned by the previous receipt. Wait is bounded; status running does not mean success.',
+        name: 'read_command', description: 'Read a managed command receipt and up to 16KB of incremental output. Cursor is a byte offset returned by the previous receipt. Zero wait is nonblocking. A positive wait wakes on output or terminal state; the host may keep waiting on a healthy silent job between model requests. Running does not mean success.',
         parameters: { type: 'object', properties: {
-                job_id: { type: 'string', description: 'Session-owned job ID from run_command.' }, cursor: { type: 'number', description: 'Byte cursor from the previous read (default 0).' }, wait_ms: { type: 'number', description: '0–60000ms; waits for completion or deadline.' },
+                job_id: { type: 'string', description: 'Session-owned job ID from run_command.' }, cursor: { type: 'number', description: 'Byte cursor from the previous read (default 0).' }, wait_ms: { type: 'number', description: '0–60000ms; wakes for output, terminal state or this read deadline. Zero requests an immediate inspection.' },
             }, required: ['job_id'] },
     },
     execute: async (args, context) => {
         if (!context?.sessionId)
             throw new Error('Managed commands require a session ID.');
-        return JSON.stringify(await readCommandJob(context.sessionId, String(args.job_id), Number(args.cursor ?? 0), Number(args.wait_ms ?? 0), context.signal));
+        const requestedWaitMs = Number(args.wait_ms ?? 0);
+        if (!Number.isSafeInteger(requestedWaitMs) || requestedWaitMs < 0 || requestedWaitMs > 60000) {
+            throw new Error('wait_ms must be an integer between 0 and 60000.');
+        }
+        const slice = context.managedCommandWaitSliceMs;
+        if (slice !== undefined && (!Number.isSafeInteger(slice) || slice < 0 || slice > 60000)) {
+            throw new Error('managedCommandWaitSliceMs must be an integer between 0 and 60000.');
+        }
+        const maxWaitMs = slice === undefined ? requestedWaitMs : Math.min(requestedWaitMs, slice);
+        const result = requestedWaitMs === 0
+            ? await readCommandJob(context.sessionId, String(args.job_id), Number(args.cursor ?? 0), 0, context.signal, context.canInspectVerificationSource)
+            : (await waitForCommandProgress(context.sessionId, String(args.job_id), { cursor: Number(args.cursor ?? 0), maxWaitMs, signal: context.signal, canInspectVerificationSource: context.canInspectVerificationSource })).result;
+        context.onManagedCommand?.({ sessionId: context.sessionId, result, requestedWaitMs, kind: 'read' });
+        return JSON.stringify(result);
     },
 };
 export const stopCommandTool = {
@@ -212,6 +336,9 @@ export const stopCommandTool = {
     execute: async (args, context) => {
         if (!context?.sessionId)
             throw new Error('Managed commands require a session ID.');
-        return JSON.stringify(await stopCommandJob(context.sessionId, String(args.job_id)));
+        const result = await stopCommandJob(context.sessionId, String(args.job_id), context.canInspectVerificationSource);
+        if (result.verification)
+            context.onVerificationReceipt?.(result.verification);
+        return JSON.stringify(result);
     },
 };

package/dist/agent/tools/tool_search.js

@@ -4,6 +4,7 @@
  * ranking tokens), or `foo bar` (ranked keyword search).
  */
 import { ToolCapability } from '../runtime/capabilities.js';
+import { captureHelperRequirements } from './helper_requirements.js';
 import { defaultTools } from './registry.js';
 import { getDeferredDefinitions } from './deferred.js';
 import { getToolBundle, listToolBundles } from './bundle_registry.js';
@@ -112,7 +113,7 @@ function searchToolSpecs(query, deferred, maxResults) {
         schemas,
     };
 }
-export const toolSearchTool = {
+export const toolSearchTool = captureHelperRequirements({
     capabilities: [ToolCapability.FILE_READ],
     definition: {
         name: 'tool_search',
@@ -181,4 +182,4 @@ export const toolSearchTool = {
         }
         return JSON.stringify(result);
     },
-};
+});

package/dist/agent/tools/types.d.ts

@@ -1,23 +1,51 @@
 import { ToolDefinition } from '../../types.js';
+import type { ModelUsageObserver } from '../../types.js';
 import { ToolCapability } from '../runtime/capabilities.js';
 import type { ToolEffectKind } from '../runtime/tool_effects.js';
 import type { ToolResponseStore } from '../tool_response_store.js';
+import type { ManagedCommandObservation } from '../runtime/command_jobs.js';
+import type { CommandVerificationReceipt, SourceSnapshot } from '../runtime/source_verification_contract.js';
+import type { HostVerifierDecision } from '../runtime/verifier_contract.js';
+import type { BenchmarkComparisonDecision } from '../runtime/benchmark_comparison.js';
 export interface ToolContext {
+    /** Host-owned command launch policy; never accepted from tool arguments. */
+    commandPolicy?: import('../../utils/sandbox.js').SandboxCommandOptions;
     cwd: string;
     /** The model-provided tool-use id that originated this execution. */
     toolCallId?: string;
+    /** Captured owner of the request which dispatched this tool. */
+    onUsage?: ModelUsageObserver;
     sessionId?: string;
     signal?: AbortSignal;
     temporaryWriteRoot?: string;
     /** Exact environment for shell-tool subprocesses; undefined inherits legacy ambient env. */
     subprocessEnv?: NodeJS.ProcessEnv;
+    /** Host-owned informational output channel for trusted built-in commands. */
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: string) => void;
     toolResponseStore: ToolResponseStore;
     discoveredTools: Set<string>;
     availableTools?: Tool[];
     workflowTimeoutMs?: number;
+    /** Host-owned initial read slice; the agent waits after recording the tool pair. */
+    managedCommandWaitSliceMs?: number;
+    /** Runtime-owned observation channel; exposed only to the built-in managed command tools. */
+    onManagedCommand?: (observation: ManagedCommandObservation) => void;
+    /** Genuine built-in command observation; custom tool output cannot populate this channel. */
+    onVerificationReceipt?: (receipt: CommandVerificationReceipt) => void;
+    /** Runtime-owned admission for fresh source reads; never supplied to custom tools. */
+    canInspectVerificationSource?: (source: SourceSnapshot) => boolean | Promise<boolean>;
+    /** Trusted registered adapter admission; stripped from all custom tools. */
+    onHostVerifier?: (receipt: CommandVerificationReceipt, decision: HostVerifierDecision) => void;
+    /** Trusted registered comparison; original measurements remain in the canonical evidence store. */
+    onHostBenchmarkComparison?: (decision: BenchmarkComparisonDecision) => void;
 }
 export interface Tool {
     definition: ToolDefinition;
+    /** Host-created adapter reference to the canonical command output source. */
+    outputSource?: Tool;
+    /** Host-created structured directory mapping, shared with execution. This
+     * describes invocation arguments, not directories inferred from shell text. */
+    resolveExecutionCwd?: (args: Record<string, unknown>, context?: ToolContext) => string;
     /** Explicit scheduling opt-in; only read effects may run concurrently. */
     parallelSafe?: boolean;
     isErrorResult?: (content: string) => boolean;

package/dist/agent/tools/verify_artifact.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const verifyArtifactTool: Tool;

package/dist/agent/tools/verify_artifact.js

@@ -0,0 +1,60 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { ToolCapability } from '../runtime/capabilities.js';
+import { jsonAssertionsRecipe } from '../runtime/json_verifier_recipe.js';
+import { captureVerifierInputs } from '../runtime/verifier_capture.js';
+import { parseCommandVerificationReceipt, parseVerificationRequest } from '../runtime/source_verification_contract.js';
+import { parseVerifierDecision } from '../runtime/verifier_contract.js';
+const recipeText = jsonAssertionsRecipe.toString();
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+export const verifyArtifactTool = Object.freeze({
+    capabilities: [ToolCapability.FILE_READ], effect: 'read', parallelSafe: true,
+    definition: {
+        name: 'verify_artifact',
+        description: 'Run the registered host json_assertions verifier against bounded immutable captures of a JSON input artifact and assertion configuration. Configuration: {schema_version:1,checks:[{path:JSON_pointer,op:"equals",value:scalar} or {path:JSON_pointer,op:"number_close",value:number,absolute_tolerance:number}]}. Proves only these configured artifact assertions, not producer correctness, whole-program verification or benchmark eligibility. Each file must be a regular local file of at most 65536 bytes. Changed captures remain unknown; later edits stale applicability. Never supplies a custom recipe or a claimed outcome.',
+        parameters: { type: 'object', additionalProperties: false, properties: {
+                adapter_id: { type: 'string', enum: ['json_assertions'] },
+                input_path: { type: 'string', description: 'Relative JSON artifact path under the current admitted working directory.' },
+                config_path: { type: 'string', description: 'Relative assertion configuration path; distinct from input_path.' },
+            }, required: ['adapter_id', 'input_path', 'config_path'] },
+    },
+    execute: async (args, context) => {
+        if (!context)
+            throw new Error('verify_artifact requires a host execution context');
+        if (Object.keys(args).some(key => !['adapter_id', 'input_path', 'config_path'].includes(key)) || args.adapter_id !== 'json_assertions') {
+            throw new TypeError('verify_artifact accepts only a registered adapter and input/config paths');
+        }
+        const request = parseVerificationRequest({ purpose: 'test', scope: 'artifact:json_assertions',
+            source_paths: [args.input_path, args.config_path], instrumentation: 'unknown' });
+        if (!request)
+            throw new TypeError('verify_artifact requires two distinct bounded relative input/config paths');
+        const captured = await captureVerifierInputs(context, request.source_paths);
+        const receipt = { schema_version: 1, receipt_id: randomUUID(), source: captured.source,
+            end_source: null, purpose: 'test', scope: 'artifact:json_assertions', command_sha256: hash(recipeText), command_kind: 'host_verifier',
+            environment: { platform: process.platform, arch: process.arch, node_version: process.version, declared_id: null },
+            build_identity: null, instrumentation: 'unknown', process_outcome: 'running', source_binding: 'unknown', qualification: 'unverified', artifact_refs: [] };
+        const input = captured.documents.get(String(args.input_path));
+        const config = captured.documents.get(String(args.config_path));
+        const binding = input !== undefined && config !== undefined && !context.signal?.aborted
+            ? 'immutable_bytes' : 'unknown';
+        const result = binding === 'immutable_bytes'
+            ? jsonAssertionsRecipe(input, config) : { outcome: 'unknown', checks_total: 0, checks_passed: 0,
+            reason: 'The complete immutable UTF-8 input capture was unavailable, changed, denied or cancelled.' };
+        const end = (await captureVerifierInputs(context, request.source_paths)).source;
+        const finished = { ...receipt, end_source: end, process_outcome: result.outcome,
+            source_binding: receipt.source.coverage === 'complete' && end.coverage === 'complete'
+                && receipt.source.source_id === end.source_id ? 'observed_endpoints' : 'unknown' };
+        finished.artifact_refs = receipt.source.files.filter(file => file.kind === 'file').map(file => ({
+            origin: 'local', path: join(receipt.source.cwd, file.path), sha256: file.sha256,
+        }));
+        const verifier = parseVerifierDecision({ schema_version: 1, adapter_id: 'json_assertions', recipe_version: 1, execution: 'host_in_process',
+            recipe_sha256: hash(recipeText), receipt_id: receipt.receipt_id, source_id: receipt.source.source_id,
+            scope: 'artifact:json_assertions', input_path: args.input_path, config_path: args.config_path,
+            input_binding: binding, ...result, benchmark_eligibility: 'unknown' }, finished);
+        if (!parseCommandVerificationReceipt(finished) || !verifier)
+            throw new Error('The host adapter produced an invalid bounded decision');
+        if (!context.signal?.aborted)
+            context.onHostVerifier?.(finished, verifier);
+        return JSON.stringify({ verification: finished, verifier });
+    },
+});

package/dist/agent/tools/workflow.js

@@ -39,6 +39,7 @@ export const workflowTool = {
                 args: args.args,
                 budgetTokens: readBudgetTokens(args.budgetTokens),
                 workflowTimeoutMs: context?.workflowTimeoutMs,
+                onUsage: context?.onUsage,
             });
             if (args.background === true) {
                 return `Workflow started in background: ${runId}`;

package/dist/app/activity.d.ts

@@ -1,9 +1,11 @@
-import { type AgentEvent, type AgentState } from '../types.js';
+import { type AgentEvent, type AgentState, type CommandWaitingState } from '../types.js';
 export type ActivityWireStatus = 'idle' | 'thinking' | 'tool_executing' | 'streaming' | 'error';
 export interface ActivityDisplayState {
     wireStatus: ActivityWireStatus;
     verb?: string;
     label: string | null;
+    waiting?: CommandWaitingState;
+    toolProgress?: AgentState['toolProgress'];
 }
 export declare function applyAgentEventToState(previous: AgentState, event: AgentEvent): AgentState;
 export declare function buildActivityDisplayState(state: AgentState, thinkingLabel: string | null): ActivityDisplayState;
@@ -14,6 +16,9 @@ export declare function buildActivityDisplayState(state: AgentState, thinkingLab
  * Returns null for idle/error.
  */
 export declare function getAgentActionLabel(state: AgentState): string | null;
+export declare function formatApiRetryNotice(event: Extract<AgentEvent, {
+    type: 'api_retry';
+}>): string;
 /**
  * Placeholder text for the composer while the agent is active.
  * Shared by every renderer so Ink and Ratatui show the same prompt.