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

package/dist/agent/runtime/tool_runtime.js

@@ -1,10 +1,20 @@
 import { basename, dirname, join, relative, resolve } from 'path';
 import { realpathSync } from 'node:fs';
 import { appendFile } from 'node:fs/promises';
+import { getRuntimeCapabilities } from '../tools/helper_requirements.js';
 import { ToolCapability } from './capabilities.js';
 import { configStore } from '../../config.js';
 import { loadIntentsContext, maybeAutoUpdateIntents } from '../../context/intents_loader.js';
 import { resolveToolEffect } from './tool_effects.js';
+import { isManagedRemoteResourceTool } from './remote_resources.js';
+import { askUserTool } from '../tools/ask_user.js';
+import { recallToolResponseTool } from '../tools/recall_tool_response.js';
+import { sessionEvidenceTool } from '../tools/session_evidence.js';
+import { parseVerificationRequest } from './source_verification_contract.js';
+import { readCommandTool, runCommandTool, stopCommandTool } from '../tools/shell.js';
+import { verifyArtifactTool } from '../tools/verify_artifact.js';
+import { benchmarkCPUTool } from '../tools/benchmark_cpu.js';
+import { compareBenchmarksTool } from '../tools/compare_benchmarks.js';
 function getTool(name, tools) {
     return tools.find(t => t.definition.name === name);
 }
@@ -24,6 +34,49 @@ function isHostControlPlaneWrite(tool, args, cwd) {
         return false;
     }
 }
+/** Missing sources still require permission for the resolved parent and leaf. */
+function canonicalSourcePath(path) {
+    let probe = path;
+    const missing = [];
+    while (true) {
+        try {
+            return join(realpathSync(probe), ...missing);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+            const parent = dirname(probe);
+            if (parent === probe)
+                throw error;
+            missing.unshift(basename(probe));
+            probe = parent;
+        }
+    }
+}
+function sourceReadDecision(cwd, paths, policy) {
+    let approvalRequired = false;
+    for (const path of paths) {
+        const lexical = resolve(cwd, path);
+        const check = (target) => policy?.evaluateTool({
+            name: 'read_file', args: { path: target }, capabilities: [ToolCapability.FILE_READ],
+        }) ?? { allowed: true };
+        const lexicalDecision = check(lexical);
+        if (!lexicalDecision.allowed)
+            return lexicalDecision;
+        approvalRequired ||= lexicalDecision.approvalRequired === true;
+        try {
+            const canonicalDecision = check(canonicalSourcePath(lexical));
+            if (!canonicalDecision.allowed)
+                return canonicalDecision;
+            approvalRequired ||= canonicalDecision.approvalRequired === true;
+        }
+        catch {
+            return { allowed: false, reason: 'Permission denied: source verification path cannot be resolved for read admission.' };
+        }
+    }
+    return { allowed: true, ...(approvalRequired ? { approvalRequired } : {}) };
+}
 async function executeTool(name, args, tools, context) {
     const tool = getTool(name, tools);
     if (!tool)
@@ -43,11 +96,11 @@ function normalizeChangedPath(path, cwd) {
     const rel = relative(cwd, resolve(cwd, path));
     return rel.startsWith('..') ? path : rel || '.';
 }
-function extractChangedPaths(tool, output, cwd) {
+function extractChangedPaths(capabilities, output, cwd) {
     // Only tools that declare FILE_WRITE can produce file-change events.
     // Inspecting capabilities (rather than tool name) lets new write tools opt
     // in without changing this file — they just need `.path` or `.paths`.
-    if (!tool || !tool.capabilities?.includes(ToolCapability.FILE_WRITE))
+    if (!capabilities.includes(ToolCapability.FILE_WRITE))
         return [];
     try {
         const parsed = JSON.parse(output);
@@ -109,9 +162,28 @@ async function recordToolTrace(entry) {
 export async function executeToolWithRuntime(name, args, options) {
     const tool = getTool(name, options.tools);
     const traceStartedAt = Date.now();
-    const capabilities = tool?.capabilities || [];
+    const ordinaryCapabilities = getRuntimeCapabilities(tool);
+    const requiredCapabilities = (input) => (tool === runCommandTool && Object.hasOwn(input, 'verification')
+        ? [...new Set([...ordinaryCapabilities, ToolCapability.FILE_READ])]
+        : ordinaryCapabilities);
+    let capabilities = requiredCapabilities(args);
     let effectiveArgs = args;
     let approvalGranted = false;
+    let managedCommand;
+    let verificationReceipt;
+    let verifierDecision;
+    let benchmarkComparisonDecision;
+    let policyExecutionCwd;
+    // A guarded remote session has a closed host-owned tool surface. This must
+    // precede hooks/approval: neither a model, plugin name nor permission update
+    // can turn a generic command into the verified remote broker.
+    if (options.remoteResourceSession && (!tool || (!isManagedRemoteResourceTool(tool, options.remoteResourceSession)
+        && tool !== askUserTool && tool !== recallToolResponseTool && tool !== sessionEvidenceTool))) {
+        return {
+            content: 'Guarded remote session: use the host-managed remote_resource tool under a required lease. Unrestricted shell, network and plugin execution is blocked.',
+            isError: true, effectiveArgs,
+        };
+    }
     // R6/F7: the model sometimes passes a shell flag (e.g. `--pane`) as a tool
     // ARGUMENT KEY rather than inside the command string (`grep: unrecognized
     // option '--pane'`). A flag-style key the tool does NOT declare is never a
@@ -150,6 +222,7 @@ export async function executeToolWithRuntime(name, args, options) {
             // drop fields by omitting them. The old replace-semantics turned
             // `{path: '/tmp/safe'}` into a write of empty content.
             effectiveArgs = { ...effectiveArgs, ...preHook.updatedArgs };
+            capabilities = requiredCapabilities(effectiveArgs);
         }
         if (preHook.failed || preHook.decision === 'deny') {
             return {
@@ -238,14 +311,23 @@ export async function executeToolWithRuntime(name, args, options) {
         }
         approvalGranted = true;
     }
+    let profileApprovalRequired = false;
     if (options.policy
         && tool
         && !hostControlPlaneWrite) {
+        try {
+            policyExecutionCwd = tool.resolveExecutionCwd?.(effectiveArgs, options.context);
+        }
+        catch (error) {
+            return handleToolFailure(error);
+        }
         const decision = options.policy.evaluateTool({
             name,
             args: effectiveArgs,
-            capabilities,
+            capabilities: ordinaryCapabilities,
+            ...(policyExecutionCwd === undefined ? {} : { executionCwd: policyExecutionCwd }),
         });
+        profileApprovalRequired = decision.approvalRequired === true;
         if (!decision.allowed) {
             return {
                 content: decision.reason || `Permission denied: ${name}`,
@@ -254,7 +336,33 @@ export async function executeToolWithRuntime(name, args, options) {
             };
         }
     }
-    const directlyGated = options.approvalRequiredCapabilities?.some(capability => capabilities.includes(capability)) === true;
+    const verificationAdmission = () => {
+        const adapter = tool === verifyArtifactTool || tool === benchmarkCPUTool;
+        const measured = tool === benchmarkCPUTool;
+        if (!adapter && (tool !== runCommandTool || !Object.hasOwn(effectiveArgs, 'verification')))
+            return undefined;
+        if (!options.context)
+            return {
+                content: 'Source verification requires a host execution context.', isError: true, effectiveArgs,
+            };
+        const request = parseVerificationRequest(adapter ? { purpose: measured ? 'benchmark' : 'test', scope: measured ? 'benchmark:cpu_integer_sum' : 'artifact:json_assertions',
+            source_paths: [effectiveArgs.input_path, effectiveArgs.config_path], instrumentation: measured ? 'production' : 'unknown' } : effectiveArgs.verification);
+        if (!request)
+            return { content: `${name}: invalid source verification request`, isError: true, effectiveArgs };
+        const cwd = !adapter && effectiveArgs.cwd ? resolve(options.context.cwd, String(effectiveArgs.cwd)) : options.context.cwd;
+        const decision = sourceReadDecision(cwd, request.source_paths, options.policy);
+        if (!decision.allowed)
+            return {
+                content: decision.reason || 'Permission denied: source verification requires file_read.',
+                isError: true, effectiveArgs,
+            };
+        profileApprovalRequired ||= decision.approvalRequired === true;
+        return undefined;
+    };
+    const preflight = verificationAdmission();
+    if (preflight)
+        return preflight;
+    const directlyGated = options.approvalRequiredCapabilities?.some(capability => capabilities.includes(capability)) === true || profileApprovalRequired;
     if (directlyGated && !approvalGranted) {
         if (!options.approvalRequester) {
             return {
@@ -283,6 +391,19 @@ export async function executeToolWithRuntime(name, args, options) {
         }
         approvalGranted = true;
     }
+    const canInspectVerificationSource = (source) => {
+        if (source.origin !== 'local')
+            return false;
+        // A shell approval for stop_command grants cancellation, not a new read.
+        if (options.approvalRequiredCapabilities?.includes(ToolCapability.FILE_READ)
+            && !(approvalGranted && capabilities.includes(ToolCapability.FILE_READ)))
+            return false;
+        const decision = sourceReadDecision(source.cwd, source.files.map(file => file.path), options.policy);
+        if (decision.approvalRequired && !(approvalGranted && capabilities.includes(ToolCapability.FILE_READ)))
+            return false;
+        return decision.allowed;
+    };
+    let checkpointRejected = false;
     try {
         // Systemic tool timeout: read-only tools get a 2-minute timeout to
         // prevent the agent from hanging indefinitely on stuck searches,
@@ -290,21 +411,69 @@ export async function executeToolWithRuntime(name, args, options) {
         // are NOT timed out because a write completing after the runtime
         // returned an error would produce invisible disk mutations.
         const TOOL_TIMEOUT_MS = 120_000;
+        const cwd = options.context?.cwd || options.hooks?.getBaseContext().cwd || process.cwd();
+        // Built-in commands and host-created adapters share their actual structured
+        // invocation mapping; tools without a declaration retain the base context.
+        const effectCwd = policyExecutionCwd ?? tool?.resolveExecutionCwd?.(effectiveArgs, options.context) ?? cwd;
         const isWriteTool = capabilities.includes(ToolCapability.FILE_WRITE)
             || capabilities.includes(ToolCapability.SHELL_EXEC);
         if (tool && options.onToolEffect) {
             await options.onToolEffect({
                 phase: 'before_execute',
                 toolName: name,
-                effect: resolveToolEffect(tool),
+                effect: resolveToolEffect({ ...tool, capabilities: ordinaryCapabilities }),
                 args: effectiveArgs,
+                cwd: effectCwd,
+                signal: options.context?.signal,
                 ...(options.context?.toolCallId
                     ? { toolCallId: options.context.toolCallId }
                     : {}),
             });
         }
-        const toolPromise = executeTool(name, effectiveArgs, options.tools, options.context);
-        const cwd = options.context?.cwd || options.hooks?.getBaseContext().cwd || process.cwd();
+        if (options.context?.signal?.aborted)
+            return {
+                content: 'not_executed: the turn was cancelled before tool dispatch.', isError: true, effectiveArgs,
+            };
+        if (tool && options.beforeExecute) {
+            try {
+                await options.beforeExecute(effectiveArgs);
+            }
+            catch (error) {
+                checkpointRejected = true;
+                throw error;
+            }
+        }
+        // Approval, observers and checkpoint writes may yield. Recheck the actual
+        // dispatch paths and cancellation immediately before invoking the tool.
+        if (options.context?.signal?.aborted)
+            return {
+                content: 'not_executed: the turn was cancelled before tool dispatch.', isError: true, effectiveArgs,
+            };
+        const dispatchAdmission = verificationAdmission();
+        if (dispatchAdmission)
+            return dispatchAdmission;
+        const toolContext = options.context ? { ...options.context,
+            onOutput: tool === runCommandTool || tool?.outputSource === runCommandTool
+                ? options.context.onOutput : undefined,
+            canInspectVerificationSource: tool === runCommandTool || tool === readCommandTool || tool === stopCommandTool || tool === verifyArtifactTool || tool === benchmarkCPUTool
+                ? canInspectVerificationSource : undefined,
+            managedCommandWaitSliceMs: tool === readCommandTool || tool === runCommandTool
+                ? options.context.managedCommandWaitSliceMs : undefined,
+            onManagedCommand: tool === readCommandTool || tool === runCommandTool
+                ? (observation) => { managedCommand = observation; }
+                : undefined,
+            onVerificationReceipt: tool === runCommandTool || tool === stopCommandTool || tool === benchmarkCPUTool
+                ? (receipt) => { verificationReceipt = structuredClone(receipt); }
+                : undefined,
+            onHostVerifier: tool === verifyArtifactTool || tool === benchmarkCPUTool ? (receipt, decision) => {
+                verificationReceipt = structuredClone(receipt);
+                verifierDecision = structuredClone(decision);
+            } : undefined,
+            onHostBenchmarkComparison: tool === compareBenchmarksTool ? (decision) => {
+                benchmarkComparisonDecision = structuredClone(decision);
+            } : undefined,
+        } : undefined;
+        const toolPromise = executeTool(name, effectiveArgs, options.tools, toolContext);
         let output;
         if (isWriteTool) {
             output = await toolPromise;
@@ -328,6 +497,7 @@ export async function executeToolWithRuntime(name, args, options) {
         const TOOL_OUTPUT_CAP = 80_000;
         output = augmentReadResultWithIntent(name, effectiveArgs, output, cwd);
         let resultContent = output;
+        const contentTruncated = resultContent.length > TOOL_OUTPUT_CAP;
         if (resultContent.length > TOOL_OUTPUT_CAP) {
             const HEAD = Math.floor(TOOL_OUTPUT_CAP * 0.8);
             const TAIL = TOOL_OUTPUT_CAP - HEAD;
@@ -336,7 +506,7 @@ export async function executeToolWithRuntime(name, args, options) {
                 + `\n\n[output truncated: ${resultContent.length.toLocaleString()} chars / ~${totalLines.toLocaleString()} lines — showing first ${HEAD.toLocaleString()} and last ${TAIL.toLocaleString()} chars]\n\n`
                 + resultContent.slice(-TAIL);
         }
-        const changedPaths = extractChangedPaths(tool, output, cwd);
+        const changedPaths = extractChangedPaths(ordinaryCapabilities, output, cwd);
         // The plan artifact is host control-plane state outside the workspace.
         // Auto-intents would turn this exact-one-file exception into a second
         // workspace write, violating plan mode's safety boundary.
@@ -348,12 +518,22 @@ export async function executeToolWithRuntime(name, args, options) {
                 toolName: name,
                 settings: configStore.get().intents,
             });
+        const allChangedPaths = [...new Set([...changedPaths, ...intentChangedPaths])];
+        if (allChangedPaths.length > 0 && options.onLocalFileChange) {
+            try {
+                await options.onLocalFileChange(allChangedPaths, cwd);
+            }
+            catch {
+                // The write has committed. An observation-store error must not invite
+                // replay of the successful mutation by presenting it as a tool failure.
+                resultContent += '\nLocal workspace evidence unavailable; the file write already completed.';
+            }
+        }
         if (options.hooks) {
             // FileChanged fires before PostToolUse: the write has already committed
             // to disk, so watchers must observe it regardless of a later PostToolUse
             // deny. PostToolUse itself is observational — deny surfaces as text,
             // never isError:true, otherwise the model retries a call that succeeded.
-            const allChangedPaths = [...new Set([...changedPaths, ...intentChangedPaths])];
             if (allChangedPaths.length > 0) {
                 await options.hooks.dispatch('FileChanged', {
                     paths: allChangedPaths,
@@ -379,10 +559,22 @@ export async function executeToolWithRuntime(name, args, options) {
         return {
             content: resultContent,
             isError: false,
+            contentTruncated,
             effectiveArgs,
+            ...(managedCommand ? { managedCommand } : {}),
+            ...(verificationReceipt ? { verificationReceipt } : {}),
+            ...(!contentTruncated && verifierDecision ? { verifierDecision } : {}),
+            ...(!contentTruncated && benchmarkComparisonDecision ? { benchmarkComparisonDecision } : {}),
         };
     }
     catch (error) {
+        // Losing the host's required invocation checkpoint is a fatal persistence
+        // failure, never a normal tool error that invites inference to continue.
+        if (checkpointRejected)
+            throw error;
+        return handleToolFailure(error);
+    }
+    async function handleToolFailure(error) {
         let message = error instanceof Error ? error.message : String(error);
         if (options.hooks) {
             const failureHook = await options.hooks.dispatch('PostToolUseFailure', {
@@ -401,6 +593,8 @@ export async function executeToolWithRuntime(name, args, options) {
             content: message,
             isError: true,
             effectiveArgs,
+            ...(managedCommand ? { managedCommand } : {}),
+            ...(verificationReceipt ? { verificationReceipt } : {}),
         };
     }
 }

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

@@ -1,4 +1,4 @@
-export type TraceEventType = 'api_request' | 'api_response' | 'request_metrics' | 'prompt_echo' | 'tool_start' | 'tool_end' | 'tool_error' | 'policy_denied' | 'max_iterations';
+export type TraceEventType = 'api_request' | 'api_response' | 'request_metrics' | 'prompt_echo' | 'tool_start' | 'tool_end' | 'tool_error' | 'policy_denied' | 'max_iterations' | 'turn_end';
 export interface TraceEvent {
     type: TraceEventType;
     timestamp: Date;

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

@@ -0,0 +1,9 @@
+import { type SourceSnapshot } from './source_verification_contract.js';
+import type { ToolContext } from '../tools/types.js';
+export declare const VERIFIER_INPUT_MAX_BYTES = 65536;
+/** The recipe consumes these detached strings, not paths it could reopen.
+ * File reads are sequential observations; no atomic filesystem snapshot is claimed. */
+export declare function captureVerifierInputs(context: Pick<ToolContext, 'cwd' | 'signal' | 'canInspectVerificationSource'>, paths: readonly string[]): Promise<{
+    source: SourceSnapshot;
+    documents: ReadonlyMap<string, string>;
+}>;

package/dist/agent/runtime/verifier_capture.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { canonicalSourceContent, canonicalSourceIdentity, parseSourceSnapshot, parseVerificationRequest } from './source_verification_contract.js';
+export const VERIFIER_INPUT_MAX_BYTES = 65536;
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function seal(source) {
+    const content = canonicalSourceContent(source);
+    if (content === null)
+        throw new Error('Invalid verifier input capture');
+    source.content_sha256 = hash(content);
+    const identity = canonicalSourceIdentity(source);
+    if (identity === null)
+        throw new Error('Invalid verifier source identity');
+    source.source_id = hash(identity);
+    const parsed = parseSourceSnapshot(source);
+    if (!parsed)
+        throw new Error('Verifier input metadata exceeds its bound');
+    return parsed;
+}
+/** The recipe consumes these detached strings, not paths it could reopen.
+ * File reads are sequential observations; no atomic filesystem snapshot is claimed. */
+export async function captureVerifierInputs(context, paths) {
+    const request = parseVerificationRequest({ purpose: 'test', scope: 'artifact:json_assertions',
+        source_paths: [...paths], instrumentation: 'unknown' });
+    if (!request || paths.length !== 2)
+        throw new TypeError('Verifier capture requires two distinct scoped relative paths');
+    const cwd = await realpath(resolve(context.cwd));
+    const source = { schema_version: 1, source_id: '0'.repeat(64), content_sha256: '0'.repeat(64),
+        cwd, origin: 'local', captured_at: new Date().toISOString(), git: { commit: null, dirty: null }, coverage: 'incomplete',
+        files: [...paths].sort().map(path => ({ path, kind: 'unavailable', sha256: null, bytes: 0, mode: 0 })) };
+    const documents = new Map();
+    for (const row of source.files) {
+        const absolute = resolve(cwd, row.path);
+        try {
+            if (context.signal?.aborted || (context.canInspectVerificationSource
+                && !await context.canInspectVerificationSource(seal(structuredClone(source)))))
+                continue;
+            // Reject linked parents and leaves, and nonregular files before opening (including FIFOs).
+            if (await realpath(dirname(absolute)) !== dirname(absolute))
+                continue;
+            const location = await lstat(absolute);
+            row.bytes = Number.isSafeInteger(location.size) && location.size >= 0 ? location.size : 0;
+            row.mode = location.mode & 0o7777;
+            if (!location.isFile() || location.size > VERIFIER_INPUT_MAX_BYTES || context.signal?.aborted)
+                continue;
+            const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            try {
+                const before = await handle.stat();
+                if (!before.isFile() || before.size > VERIFIER_INPUT_MAX_BYTES || before.dev !== location.dev || before.ino !== location.ino)
+                    continue;
+                // One extra byte detects growth without exceeding the capture budget.
+                const bytes = Buffer.alloc(before.size + 1);
+                let used = 0;
+                while (used < bytes.length) {
+                    if (context.signal?.aborted)
+                        break;
+                    const read = await handle.read(bytes, used, bytes.length - used, used);
+                    if (!read.bytesRead)
+                        break;
+                    used += read.bytesRead;
+                }
+                const after = await handle.stat();
+                const current = await lstat(absolute);
+                if (context.signal?.aborted || used !== before.size || before.dev !== after.dev || before.ino !== after.ino
+                    || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+                    || current.dev !== before.dev || current.ino !== before.ino
+                    || await realpath(dirname(absolute)) !== dirname(absolute))
+                    continue;
+                if (context.canInspectVerificationSource && !await context.canInspectVerificationSource(seal(structuredClone(source))))
+                    continue;
+                if (context.signal?.aborted)
+                    continue;
+                const captured = bytes.subarray(0, used);
+                row.kind = 'file';
+                row.sha256 = hash(captured);
+                row.bytes = used;
+                row.mode = before.mode & 0o7777;
+                // Preserve the exact byte digest even if the document is not valid UTF-8.
+                try {
+                    documents.set(row.path, new TextDecoder('utf-8', { fatal: true }).decode(captured));
+                }
+                catch { /* An undecodable input cannot enter the JSON recipe. */ }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                row.kind = 'missing';
+            // Missing, changed, denied and nonregular inputs remain explicitly incomplete.
+        }
+    }
+    source.coverage = source.files.every(row => row.kind === 'file') ? 'complete' : 'incomplete';
+    if (source.coverage === 'incomplete')
+        source.reason = 'Some verifier inputs were missing, changed, denied, nonregular or exceeded 65536 bytes.';
+    return { source: seal(source), documents };
+}

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

@@ -0,0 +1,24 @@
+import type { CommandVerificationReceipt } from './source_verification_contract.js';
+import { type BenchmarkVerifierDecision } from './benchmark_contract.js';
+/** A registered recipe proves only its configured artifact property, never a whole program or benchmark. */
+export interface VerifierDecision {
+    schema_version: 1;
+    adapter_id: 'json_assertions';
+    recipe_version: 1;
+    execution: 'host_in_process';
+    recipe_sha256: string;
+    receipt_id: string;
+    source_id: string;
+    scope: 'artifact:json_assertions';
+    input_path: string;
+    config_path: string;
+    input_binding: 'immutable_bytes' | 'unknown';
+    outcome: 'passed' | 'failed' | 'unknown';
+    checks_total: number;
+    checks_passed: number;
+    reason: string;
+    benchmark_eligibility: 'unknown';
+}
+export type HostVerifierDecision = VerifierDecision | BenchmarkVerifierDecision;
+export declare function parseHostVerifierDecision(value: unknown, receipt: CommandVerificationReceipt): HostVerifierDecision | null;
+export declare function parseVerifierDecision(value: unknown, receipt: CommandVerificationReceipt): VerifierDecision | null;

package/dist/agent/runtime/verifier_contract.js

@@ -0,0 +1,41 @@
+import { parseBenchmarkVerifierDecision } from './benchmark_contract.js';
+export function parseHostVerifierDecision(value, receipt) {
+    return parseVerifierDecision(value, receipt) ?? parseBenchmarkVerifierDecision(value, receipt);
+}
+export function parseVerifierDecision(value, receipt) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const row = value;
+    const allowed = ['schema_version', 'adapter_id', 'recipe_version', 'execution', 'recipe_sha256', 'receipt_id', 'source_id', 'scope',
+        'input_path', 'config_path', 'input_binding', 'outcome', 'checks_total', 'checks_passed', 'reason', 'benchmark_eligibility'];
+    if (Object.keys(row).length !== allowed.length || Object.keys(row).some(key => !allowed.includes(key)))
+        return null;
+    if (row.schema_version !== 1 || row.adapter_id !== 'json_assertions' || row.recipe_version !== 1 || row.execution !== 'host_in_process'
+        || row.scope !== 'artifact:json_assertions' || row.benchmark_eligibility !== 'unknown'
+        || row.receipt_id !== receipt.receipt_id || row.source_id !== receipt.source.source_id
+        || row.recipe_sha256 !== receipt.command_sha256 || receipt.command_kind !== 'host_verifier'
+        || receipt.scope !== row.scope || receipt.purpose !== 'test' || receipt.source.origin !== 'local'
+        || typeof row.reason !== 'string' || !row.reason.trim() || Buffer.byteLength(row.reason) > 512
+        || /[\u0000-\u001f\u007f]/u.test(row.reason))
+        return null;
+    if (!['passed', 'failed', 'unknown'].includes(String(row.outcome))
+        || !['immutable_bytes', 'unknown'].includes(String(row.input_binding))
+        || typeof row.checks_total !== 'number' || !Number.isSafeInteger(row.checks_total) || row.checks_total < 0 || row.checks_total > 32
+        || typeof row.checks_passed !== 'number' || !Number.isSafeInteger(row.checks_passed) || row.checks_passed < 0
+        || row.checks_passed > row.checks_total || receipt.process_outcome !== row.outcome)
+        return null;
+    const input = receipt.source.files.find(file => file.path === row.input_path);
+    const config = receipt.source.files.find(file => file.path === row.config_path);
+    if (!input || !config || input.path === config.path || receipt.source.files.length !== 2)
+        return null;
+    if (row.outcome !== 'unknown' && (row.input_binding !== 'immutable_bytes' || receipt.source.coverage !== 'complete'
+        || input.kind !== 'file' || config.kind !== 'file' || input.bytes > 65536 || config.bytes > 65536 || row.checks_total === 0))
+        return null;
+    if (row.outcome === 'passed' && row.checks_passed !== row.checks_total)
+        return null;
+    if (row.outcome === 'failed' && row.checks_passed === row.checks_total)
+        return null;
+    if (row.outcome === 'unknown' && (row.checks_total !== 0 || row.checks_passed !== 0))
+        return null;
+    return structuredClone(row);
+}

package/dist/agent/subagent.d.ts

@@ -1,19 +1,17 @@
-/**
- * SubAgent - Isolated agent for context-heavy operations
- *
- * Spawns a separate agent with its own context to handle tasks like:
- * - Exploring codebases
- * - Searching for patterns
- * - Reading multiple files
- *
- * Only the final summary is returned to the main agent, keeping the main context clean.
- */
+import { Message, type AgentEvent } from '../types.js';
+import type { ModelUsageObserver } from '../types.js';
 import { AgentBackend } from './backends/index.js';
 import type { Tool } from './tools/types.js';
+import { type EvidenceSnapshot } from './runtime/evidence.js';
+import { type DelegatedEvidenceHandoff } from './runtime/delegated_evidence.js';
 import type { Policy } from './runtime/policy.js';
 import { HookDispatcher } from '../hooks/dispatcher.js';
 import type { HookApprovalRequester } from '../hooks/types.js';
 export interface SubAgentConfig {
+    /** Host-owned resume handle; checked against the original parent and cwd. */
+    resumeSessionId?: string;
+    parentSessionId?: string;
+    commandPolicy?: import('../utils/sandbox.js').SandboxCommandOptions;
     provider: string;
     apiKey: string;
     model?: string;
@@ -27,6 +25,7 @@ export interface SubAgentConfig {
     temporaryWriteRoot?: string;
 }
 export interface SubAgentResult {
+    evidence: DelegatedEvidenceHandoff;
     summary: string;
     filesRead: string[];
     commandsRun: string[];
@@ -63,10 +62,14 @@ export declare class SubAgent {
     private inputTokens;
     private outputTokens;
     private readonly toolResponseStore;
+    private readonly sessionId;
     private readonly discoveredTools;
     private hooks?;
     private approvalRequester?;
     constructor(config: SubAgentConfig);
+    getSessionId(): string;
+    getEvidenceSnapshot(): EvidenceSnapshot;
+    getEvidenceHandoff(summary?: string): DelegatedEvidenceHandoff;
     /**
      * Run a task and return a summary.
      *
@@ -77,12 +80,19 @@ export declare class SubAgent {
         signal?: AbortSignal;
         systemPrompt?: string;
         tools?: Tool[];
+        /** Compacted history supplies context, never new source observations. */
+        messages?: Message[];
         onIteration?: (info: {
             iteration: number;
             max: number;
             toolsCalled: string[];
         }) => void;
+        onUsage?: ModelUsageObserver;
+        onEvent?: (event: AgentEvent) => void;
     }): Promise<SubAgentResult>;
+    private hasStoredToolIdentity;
+    private persistEvidenceCheckpoint;
+    private evidenceSource;
     /**
      * Track what the sub-agent accessed
      */