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

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

@@ -0,0 +1,110 @@
+/** Comparability of reported measurement data; neither source verification nor benchmark admission. */
+export declare const MEASUREMENT_MAX_METRICS = 64;
+export declare const MEASUREMENT_MAX_SELECTION = 16;
+export declare const MEASUREMENT_MAX_REASONS = 32;
+export declare const MEASUREMENT_MAX_ENVELOPE_BYTES: number;
+export declare const MEASUREMENT_MAX_REPORT_BYTES: number;
+export interface MeasurementSource {
+    revision: string;
+    artifactSha256: string;
+}
+export interface MeasurementWorkload {
+    id: string;
+    stage: string;
+    inputShape: Record<string, string | number>;
+}
+export interface MeasurementInstrumentation {
+    mode: string;
+    version: string;
+    synchronization: 'production' | 'diagnostic';
+    runtimePath: string;
+}
+export interface ReportedMetric {
+    id: string;
+    value: number;
+    unit: string;
+    timingDomain: string;
+    scope: string;
+    rank: number;
+    worldSize: number;
+    coverage: 'inclusive' | 'exclusive';
+    parentId?: string;
+}
+export interface MeasurementEnvelope {
+    schemaVersion: 1;
+    runId: string;
+    source: MeasurementSource;
+    workload: MeasurementWorkload;
+    instrumentation: MeasurementInstrumentation;
+    completion: {
+        status: 'running' | 'completed' | 'failed';
+        passed: boolean | null;
+    };
+    smoke: {
+        mode: string;
+        runtimePath: string;
+        fields: string[];
+        passed: boolean;
+    };
+    metrics: ReportedMetric[];
+}
+export interface MeasurementRequirements {
+    workload: MeasurementWorkload;
+    instrumentation: MeasurementInstrumentation;
+    metricIds: string[];
+    unit: string;
+    timingDomain: string;
+    scope: string;
+    worldSize: number;
+    expectedRanks: number[];
+    /** Requested metric IDs must exist both in smoke.fields and in the metrics array. */
+    smokeFields: string[];
+    aggregation: 'none' | 'sum_exclusive';
+    totalMetricId?: string;
+}
+export interface MeasurementReason {
+    code: string;
+    message: string;
+}
+export type MeasurementCompatibility = 'compatible' | 'incompatible' | 'unknown';
+export type MeasurementCompletion = 'incomplete' | 'reported_pass' | 'reported_fail' | 'unknown';
+export type MeasurementValue = Pick<ReportedMetric, 'id' | 'value' | 'unit' | 'timingDomain' | 'scope' | 'rank' | 'worldSize'>;
+export interface MeasurementReport {
+    compatibility: MeasurementCompatibility;
+    verification: 'unknown';
+    benchmarkEligibility: 'unknown';
+    completion: MeasurementCompletion;
+    runId: string | null;
+    source: MeasurementSource | null;
+    reasons: MeasurementReason[];
+    values: MeasurementValue[];
+    aggregate: number | null;
+    residual: {
+        value: number;
+        attribution: 'unattributed';
+        removableWin: false;
+    } | null;
+}
+export interface MeasurementDelta {
+    id: string;
+    baseline: number;
+    candidate: number;
+    delta: number;
+    relativeChangePercent: number | null;
+}
+export interface MeasurementComparison {
+    compatibility: MeasurementCompatibility;
+    verification: 'unknown';
+    benchmarkEligibility: 'unknown';
+    baseline: MeasurementReport;
+    candidate: MeasurementReport;
+    reasons: MeasurementReason[];
+    deltas: MeasurementDelta[];
+}
+/** Parse only the producer's bounded declaration. A well-formed declaration is not verified evidence. */
+export declare function parseMeasurementEnvelope(value: unknown): MeasurementEnvelope | null;
+export declare function parseMeasurementRequirements(value: unknown): MeasurementRequirements | null;
+/** Check comparability against visible caller requirements, without trusting the producer's scientific or source claims. */
+export declare function assessMeasurements(value: unknown, requirements: unknown): MeasurementReport;
+/** Compare matching reported identities. Positive/negative deltas have no inferred optimization direction. */
+export declare function compareMeasurements(base: unknown, candidate: unknown, requirements: unknown): MeasurementComparison;

package/dist/agent/runtime/measurements.js

@@ -0,0 +1,317 @@
+/** Comparability of reported measurement data; neither source verification nor benchmark admission. */
+export const MEASUREMENT_MAX_METRICS = 64;
+export const MEASUREMENT_MAX_SELECTION = 16;
+export const MEASUREMENT_MAX_REASONS = 32;
+export const MEASUREMENT_MAX_ENVELOPE_BYTES = 128 * 1024;
+export const MEASUREMENT_MAX_REPORT_BYTES = 64 * 1024;
+const encoder = new TextEncoder();
+const byteLength = (value) => encoder.encode(value).length;
+const serializedBytes = (value) => byteLength(JSON.stringify(value));
+function object(value, required, optional = []) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Expected an object');
+    const record = value;
+    if (required.some(key => !Object.hasOwn(record, key))
+        || Object.keys(record).some(key => !required.includes(key) && !optional.includes(key)))
+        throw new TypeError('Invalid fields');
+    return record;
+}
+function text(value, maxBytes = 256) {
+    if (typeof value !== 'string' || !value.trim() || byteLength(value) > maxBytes
+        || /[\u0000-\u001f\u007f]/u.test(value))
+        throw new TypeError('Invalid bounded text');
+    return value;
+}
+function integer(value, minimum = 0) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum)
+        throw new TypeError('Invalid integer');
+    return value;
+}
+function number(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new TypeError('Invalid finite number');
+    return value;
+}
+function strings(value, minimum = 0) {
+    if (!Array.isArray(value) || value.length < minimum || value.length > MEASUREMENT_MAX_SELECTION)
+        throw new TypeError('Invalid bounded list');
+    const result = value.map(item => text(item));
+    if (new Set(result).size !== result.length)
+        throw new TypeError('Duplicate identity');
+    return result;
+}
+function workload(value) {
+    const record = object(value, ['id', 'stage', 'inputShape']);
+    if (!record.inputShape || typeof record.inputShape !== 'object' || Array.isArray(record.inputShape))
+        throw new TypeError('Invalid input shape');
+    const entries = Object.entries(record.inputShape);
+    if (entries.length > MEASUREMENT_MAX_SELECTION)
+        throw new TypeError('Input shape exceeds its bound');
+    return { id: text(record.id), stage: text(record.stage, 128), inputShape: Object.fromEntries(entries.map(([key, item]) => [text(key, 128), typeof item === 'string' ? text(item) : number(item)])) };
+}
+function instrumentation(value) {
+    const record = object(value, ['mode', 'version', 'synchronization', 'runtimePath']);
+    if (record.synchronization !== 'production' && record.synchronization !== 'diagnostic')
+        throw new TypeError('Invalid synchronization');
+    return { mode: text(record.mode, 128), version: text(record.version, 128), synchronization: record.synchronization,
+        runtimePath: text(record.runtimePath, 4096) };
+}
+function metric(value) {
+    const record = object(value, ['id', 'value', 'unit', 'timingDomain', 'scope', 'rank', 'worldSize', 'coverage'], ['parentId']);
+    const measured = number(record.value), rank = integer(record.rank), worldSize = integer(record.worldSize, 1);
+    if (measured < 0 || rank >= worldSize || (record.coverage !== 'inclusive' && record.coverage !== 'exclusive'))
+        throw new TypeError('Invalid metric scope');
+    return { id: text(record.id), value: measured, unit: text(record.unit, 128), timingDomain: text(record.timingDomain, 128),
+        scope: text(record.scope, 128), rank, worldSize, coverage: record.coverage,
+        ...(record.parentId === undefined ? {} : { parentId: text(record.parentId) }) };
+}
+/** Parse only the producer's bounded declaration. A well-formed declaration is not verified evidence. */
+export function parseMeasurementEnvelope(value) {
+    try {
+        const record = object(value, ['schemaVersion', 'runId', 'source', 'workload', 'instrumentation', 'completion', 'smoke', 'metrics']);
+        if (record.schemaVersion !== 1)
+            return null;
+        const source = object(record.source, ['revision', 'artifactSha256']);
+        if (typeof source.artifactSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(source.artifactSha256))
+            return null;
+        const completion = object(record.completion, ['status', 'passed']);
+        if (completion.status !== 'running' && completion.status !== 'completed' && completion.status !== 'failed')
+            return null;
+        if (completion.passed !== null && typeof completion.passed !== 'boolean')
+            return null;
+        const smoke = object(record.smoke, ['mode', 'runtimePath', 'fields', 'passed']);
+        if (typeof smoke.passed !== 'boolean' || !Array.isArray(record.metrics) || record.metrics.length > MEASUREMENT_MAX_METRICS)
+            return null;
+        const metrics = record.metrics.map(metric), byId = new Map(metrics.map(item => [item.id, item]));
+        if (byId.size !== metrics.length)
+            return null;
+        for (const item of metrics) {
+            const visited = new Set([item.id]);
+            let parent = item.parentId;
+            while (parent !== undefined) {
+                if (!byId.has(parent) || visited.has(parent))
+                    return null;
+                visited.add(parent);
+                parent = byId.get(parent).parentId;
+            }
+        }
+        const parsed = { schemaVersion: 1, runId: text(record.runId),
+            source: { revision: text(source.revision), artifactSha256: source.artifactSha256 },
+            workload: workload(record.workload), instrumentation: instrumentation(record.instrumentation),
+            completion: { status: completion.status, passed: completion.passed },
+            smoke: { mode: text(smoke.mode, 128), runtimePath: text(smoke.runtimePath, 4096), fields: strings(smoke.fields), passed: smoke.passed }, metrics };
+        return serializedBytes(parsed) <= MEASUREMENT_MAX_ENVELOPE_BYTES ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseMeasurementRequirements(value) {
+    try {
+        const record = object(value, ['workload', 'instrumentation', 'metricIds', 'unit', 'timingDomain', 'scope', 'worldSize',
+            'expectedRanks', 'smokeFields', 'aggregation'], ['totalMetricId']);
+        const worldSize = integer(record.worldSize, 1);
+        if (!Array.isArray(record.expectedRanks) || record.expectedRanks.length < 1 || record.expectedRanks.length > MEASUREMENT_MAX_SELECTION)
+            return null;
+        const ranks = record.expectedRanks.map(item => integer(item));
+        if (new Set(ranks).size !== ranks.length || ranks.some(rank => rank >= worldSize))
+            return null;
+        if (record.aggregation !== 'none' && record.aggregation !== 'sum_exclusive')
+            return null;
+        return { workload: workload(record.workload), instrumentation: instrumentation(record.instrumentation),
+            metricIds: strings(record.metricIds, 1), unit: text(record.unit, 128), timingDomain: text(record.timingDomain, 128),
+            scope: text(record.scope, 128), worldSize, expectedRanks: ranks, smokeFields: strings(record.smokeFields, 1), aggregation: record.aggregation,
+            ...(record.totalMetricId === undefined ? {} : { totalMetricId: text(record.totalMetricId) }) };
+    }
+    catch {
+        return null;
+    }
+}
+function emptyReport(envelope) {
+    return { compatibility: 'unknown', verification: 'unknown', benchmarkEligibility: 'unknown', completion: 'unknown',
+        runId: envelope?.runId ?? null, source: envelope?.source ?? null, reasons: [], values: [], aggregate: null, residual: null };
+}
+function compactReport(report) {
+    return { ...report, compatibility: 'unknown', reasons: [{ code: 'report_limit', message: 'The report exceeds its bounded representation; narrow the selection.' }],
+        values: [], aggregate: null, residual: null };
+}
+function sameShape(left, right) {
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && left[key] === right[key]);
+}
+function sameScope(item, required) {
+    return item.unit === required.unit && item.timingDomain === required.timingDomain && item.scope === required.scope
+        && item.worldSize === required.worldSize;
+}
+/** Check comparability against visible caller requirements, without trusting the producer's scientific or source claims. */
+export function assessMeasurements(value, requirements) {
+    const envelope = parseMeasurementEnvelope(value), required = parseMeasurementRequirements(requirements);
+    const report = emptyReport(envelope);
+    if (!envelope || !required) {
+        if (!envelope)
+            report.reasons.push({ code: 'invalid_envelope', message: 'The reported measurement envelope is missing, malformed, or exceeds its bounds.' });
+        if (!required)
+            report.reasons.push({ code: 'invalid_requirements', message: 'Explicit bounded measurement requirements are missing or malformed.' });
+        return report;
+    }
+    let incompatible = false, unknown = false;
+    const issue = (compatibility, code, message) => {
+        if (compatibility === 'incompatible')
+            incompatible = true;
+        else
+            unknown = true;
+        if (report.reasons.length < MEASUREMENT_MAX_REASONS)
+            report.reasons.push({ code, message });
+    };
+    if (envelope.workload.id !== required.workload.id || envelope.workload.stage !== required.workload.stage
+        || !sameShape(envelope.workload.inputShape, required.workload.inputShape)) {
+        issue('incompatible', 'workload_mismatch', 'Reported workload, stage and input shape must match the declared comparison.');
+    }
+    if (envelope.instrumentation.mode !== required.instrumentation.mode || envelope.instrumentation.version !== required.instrumentation.version
+        || envelope.instrumentation.synchronization !== required.instrumentation.synchronization
+        || envelope.instrumentation.runtimePath !== required.instrumentation.runtimePath) {
+        issue('incompatible', 'instrumentation_mismatch', 'Reported instrumentation mode, version, synchronization and runtime path must match.');
+    }
+    if (envelope.completion.status === 'running') {
+        report.completion = 'incomplete';
+        issue('unknown', 'incomplete', 'A running producer has not reported a completed measurement.');
+    }
+    else if (envelope.completion.status === 'failed' || envelope.completion.passed === false) {
+        report.completion = 'reported_fail';
+        issue('incompatible', 'reported_failure', 'The producer reports a failed run.');
+    }
+    else if (envelope.completion.passed === null) {
+        issue('unknown', 'missing_pass', 'The completed producer has not reported a pass outcome.');
+    }
+    else
+        report.completion = 'reported_pass';
+    if (envelope.smoke.mode !== required.instrumentation.mode || envelope.smoke.runtimePath !== required.instrumentation.runtimePath) {
+        issue('incompatible', 'smoke_path_mismatch', 'Smoke observations must name the requested mode and runtime path.');
+    }
+    if (!envelope.smoke.passed)
+        issue('incompatible', 'smoke_failed', 'The producer reports a failed smoke check.');
+    const byId = new Map(envelope.metrics.map(item => [item.id, item]));
+    for (const id of required.smokeFields) {
+        const item = byId.get(id);
+        if (!envelope.smoke.fields.includes(id) || !item)
+            issue('unknown', 'missing_smoke_metric', `Requested smoke metric is missing: ${id}`);
+        else if (!sameScope(item, required) || !required.expectedRanks.includes(item.rank)) {
+            issue('incompatible', 'smoke_scope_mismatch', `Requested smoke metric has a different timing or execution scope: ${id}`);
+        }
+    }
+    const selected = [];
+    for (const id of required.metricIds) {
+        const item = byId.get(id);
+        if (!item) {
+            issue('unknown', 'missing_metric', `Requested measurement is missing: ${id}`);
+            continue;
+        }
+        selected.push(item);
+        const { value: measured, unit, timingDomain, scope, rank, worldSize } = item;
+        report.values.push({ id, value: measured, unit, timingDomain, scope, rank, worldSize });
+        if (!sameScope(item, required))
+            issue('incompatible', 'metric_scope_mismatch', `Measurement unit, timing domain, scope or world size differs: ${id}`);
+        if (!required.expectedRanks.includes(rank))
+            issue('incompatible', 'unexpected_rank', `Measurement has an undeclared rank: ${id}`);
+    }
+    const ranks = new Set(selected.map(item => item.rank));
+    for (const rank of required.expectedRanks)
+        if (!ranks.has(rank))
+            issue('unknown', 'missing_rank', `Requested rank has no selected measurement: ${rank}`);
+    let aggregate = null;
+    if (required.aggregation === 'sum_exclusive') {
+        const selectedIds = new Set(required.metricIds);
+        for (const item of selected) {
+            if (item.coverage !== 'exclusive')
+                issue('incompatible', 'inclusive_sum', `An inclusive measurement cannot enter an exclusive sum: ${item.id}`);
+            let parent = item.parentId;
+            while (parent !== undefined) {
+                if (selectedIds.has(parent)) {
+                    issue('incompatible', 'nested_sum', 'A selected ancestor and descendant cannot be summed together.');
+                    break;
+                }
+                parent = byId.get(parent).parentId;
+            }
+        }
+        if (ranks.size > 1)
+            issue('incompatible', 'cross_rank_sum', 'Measurements from different ranks cannot be added as one exclusive duration.');
+        aggregate = selected.reduce((total, item) => total + item.value, 0);
+        if (!Number.isFinite(aggregate)) {
+            aggregate = null;
+            issue('incompatible', 'arithmetic_overflow', 'The selected sum is not representable as a finite number.');
+        }
+    }
+    let residual = null;
+    if (required.totalMetricId !== undefined) {
+        const total = byId.get(required.totalMetricId);
+        if (!total)
+            issue('unknown', 'missing_total', 'The requested denominator measurement is absent.');
+        else if (required.metricIds.includes(total.id))
+            issue('incompatible', 'selected_total', 'The denominator cannot also be selected as a summed component.');
+        else if (total.coverage !== 'inclusive')
+            issue('incompatible', 'exclusive_total', 'A residual denominator must report inclusive coverage.');
+        else if (!sameScope(total, required)) {
+            issue('incompatible', 'total_scope_mismatch', 'The denominator must match selected units, timing domain, scope, world size and rank.');
+        }
+        else if (ranks.size === 0)
+            issue('unknown', 'missing_selected_scope', 'No selected component establishes a rank for the denominator.');
+        else if (ranks.size !== 1 || !ranks.has(total.rank)) {
+            issue('incompatible', 'total_scope_mismatch', 'The denominator must match selected units, timing domain, scope, world size and rank.');
+        }
+        else if (aggregate === null)
+            issue('unknown', 'missing_aggregate', 'A residual requires an explicit finite exclusive sum.');
+        else if (total.value < aggregate)
+            issue('incompatible', 'over_accounted', 'Selected components exceed the reported denominator.');
+        else
+            residual = { value: total.value - aggregate, attribution: 'unattributed', removableWin: false };
+    }
+    report.compatibility = incompatible ? 'incompatible' : unknown ? 'unknown' : 'compatible';
+    if (report.compatibility === 'compatible') {
+        report.aggregate = aggregate;
+        report.residual = residual;
+    }
+    return serializedBytes(report) <= MEASUREMENT_MAX_REPORT_BYTES ? report : compactReport(report);
+}
+/** Compare matching reported identities. Positive/negative deltas have no inferred optimization direction. */
+export function compareMeasurements(base, candidate, requirements) {
+    const baseEnvelope = parseMeasurementEnvelope(base), nextEnvelope = parseMeasurementEnvelope(candidate);
+    const baseline = assessMeasurements(baseEnvelope, requirements), next = assessMeasurements(nextEnvelope, requirements);
+    const comparison = { compatibility: 'compatible', verification: 'unknown', benchmarkEligibility: 'unknown',
+        baseline, candidate: next, reasons: [], deltas: [] };
+    if (baseline.compatibility !== 'compatible' || next.compatibility !== 'compatible') {
+        comparison.compatibility = baseline.compatibility === 'incompatible' || next.compatibility === 'incompatible' ? 'incompatible' : 'unknown';
+        for (const [label, report] of [['baseline', baseline], ['candidate', next]]) {
+            if (report.compatibility !== 'compatible')
+                comparison.reasons.push({ code: `${label}_${report.compatibility}`, message: `Inspect the ${label} report for unmet measurement requirements.` });
+        }
+    }
+    else {
+        const candidates = new Map(next.values.map(item => [item.id, item]));
+        const previousCoverage = new Map(baseEnvelope.metrics.map(item => [item.id, item.coverage]));
+        const nextCoverage = new Map(nextEnvelope.metrics.map(item => [item.id, item.coverage]));
+        for (const previous of baseline.values) {
+            const measured = candidates.get(previous.id);
+            if (measured.rank !== previous.rank || measured.scope !== previous.scope || previousCoverage.get(previous.id) !== nextCoverage.get(previous.id)) {
+                comparison.compatibility = 'incompatible';
+                comparison.reasons.push({ code: 'identity_scope_changed', message: `A selected identity changed rank, scope or coverage: ${previous.id}` });
+            }
+        }
+        if (comparison.compatibility === 'compatible') {
+            for (const previous of baseline.values) {
+                const measured = candidates.get(previous.id);
+                const delta = measured.value - previous.value;
+                const relative = previous.value === 0 ? null : delta / previous.value * 100;
+                comparison.deltas.push({ id: previous.id, baseline: previous.value, candidate: measured.value, delta,
+                    relativeChangePercent: relative !== null && Number.isFinite(relative) ? relative : null });
+            }
+        }
+    }
+    if (serializedBytes(comparison) > MEASUREMENT_MAX_REPORT_BYTES) {
+        comparison.compatibility = 'unknown';
+        comparison.baseline = compactReport(baseline);
+        comparison.candidate = compactReport(next);
+        comparison.deltas = [];
+        comparison.reasons = [{ code: 'report_limit', message: 'Narrow the selection to fit the bounded comparison report.' }];
+    }
+    return comparison;
+}

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

@@ -4,10 +4,14 @@ export interface ToolPolicyRequest {
     name: string;
     args: Record<string, unknown>;
     capabilities: ToolCapability[];
+    /** Host-declared effective directory, after hooks and adapter mapping. */
+    executionCwd?: string;
 }
 export interface ToolPolicyDecision {
     allowed: boolean;
     reason?: string;
+    /** Reuse the host approval boundary before this admitted effect. */
+    approvalRequired?: boolean;
 }
 export interface Policy {
     evaluateTool(request: ToolPolicyRequest): ToolPolicyDecision;

package/dist/agent/runtime/policy.js

@@ -1,6 +1,8 @@
 import { ToolCapability } from './capabilities.js';
 import { homedir } from 'os';
 import { resolve, isAbsolute, sep } from 'path';
+import { parseCheckedCommandPlan } from './checked_commands.js';
+import { formatCheckedStageCommand } from '../../utils/checked_shell.js';
 export class AllowAllPolicy {
     evaluateTool() {
         return { allowed: true };
@@ -46,13 +48,14 @@ export class CapabilityPolicy {
         if (!networkDecision.allowed) {
             return networkDecision;
         }
-        return { allowed: true };
+        const approvalRequired = this.profile?.approvalRequiredCapabilities?.some(cap => request.capabilities.includes(cap)) === true;
+        return { allowed: true, ...(approvalRequired ? { approvalRequired } : {}) };
     }
     evaluatePathPolicy(request) {
         if (!this.profile || !request.capabilities.some(capability => (capability === ToolCapability.FILE_READ || capability === ToolCapability.FILE_WRITE))) {
             return { allowed: true };
         }
-        const paths = extractPathArgs(request.args);
+        const paths = extractPathArgs(request.args, request.executionCwd);
         if (paths.length === 0) {
             return { allowed: true };
         }
@@ -79,23 +82,28 @@ export class CapabilityPolicy {
         if (!this.profile || !request.capabilities.includes(ToolCapability.SHELL_EXEC)) {
             return { allowed: true };
         }
-        const command = typeof request.args.command === 'string' ? request.args.command.trim() : '';
-        if (!command) {
-            return { allowed: true };
-        }
+        const checked = Object.hasOwn(request.args, 'checked') ? parseCheckedCommandPlan(request.args.checked) : undefined;
+        if (checked === null)
+            return { allowed: false, reason: 'Permission denied: invalid checked command plan' };
+        const commands = checked ? checked.steps.flatMap(step => step.pipeline.map(formatCheckedStageCommand))
+            : [typeof request.args.command === 'string' ? request.args.command.trim() : ''];
         const denied = this.profile.deniedShellCommands || [];
-        if (denied.some(prefix => command.startsWith(prefix))) {
-            return {
-                allowed: false,
-                reason: `Permission denied: shell command blocked by profile (${command})`,
-            };
-        }
         const allowed = this.profile.allowedShellCommands || [];
-        if (allowed.length > 0 && !allowed.some(prefix => command.startsWith(prefix))) {
-            return {
-                allowed: false,
-                reason: `Permission denied: shell command is outside allowed profile commands (${command})`,
-            };
+        for (const command of commands) {
+            if (!command)
+                continue;
+            if (denied.some(prefix => command.startsWith(prefix))) {
+                return {
+                    allowed: false,
+                    reason: `Permission denied: shell command blocked by profile (${command})`,
+                };
+            }
+            if (allowed.length > 0 && !allowed.some(prefix => command.startsWith(prefix))) {
+                return {
+                    allowed: false,
+                    reason: `Permission denied: shell command is outside allowed profile commands (${command})`,
+                };
+            }
         }
         return { allowed: true };
     }
@@ -126,9 +134,12 @@ export class CapabilityPolicy {
         return { allowed: true };
     }
 }
-function extractPathArgs(args) {
-    const candidates = ['path', 'file_path', 'filepath', 'directory', 'cwd', 'repo_path', 'artifact_path'];
-    const paths = [];
+function extractPathArgs(args, executionCwd) {
+    // Declared execution mapping owns cwd/workdir precedence. Undeclared tools
+    // retain conservative checks of both raw fields and all other file paths.
+    const candidates = ['path', 'file_path', 'filepath', 'directory',
+        ...(executionCwd === undefined ? ['cwd', 'workdir'] : []), 'repo_path', 'artifact_path'];
+    const paths = executionCwd === undefined ? [] : [executionCwd];
     for (const key of candidates) {
         const value = args[key];
         if (typeof value === 'string' && value.trim().length > 0) {

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

@@ -0,0 +1,20 @@
+import type { BackendObservation } from '../backends/types.js';
+import type { EvidenceSource } from './evidence.js';
+export declare const NATIVE_REPORT_OUTPUT_BYTES: number;
+export declare const NATIVE_REPORT_INPUT_OUTPUT_BYTES: number;
+export declare const NATIVE_REPORT_MAX_ARTIFACTS = 16;
+export declare class NativeObservationLimitError extends Error {
+    constructor(maximum: number);
+}
+export interface NativeEvidenceCapture {
+    handle: string;
+    content: string;
+    source: EvidenceSource;
+    partial: boolean;
+    isError: boolean;
+}
+/** Only explicit command/action fields are retained; reasoning and opaque detail are display-only. */
+export declare function captureNativeReport(observation: BackendObservation, fallback: {
+    provider: string;
+    turnId: string;
+}): NativeEvidenceCapture | null;

package/dist/agent/runtime/provider_native_evidence.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+export const NATIVE_REPORT_OUTPUT_BYTES = 64 * 1024;
+export const NATIVE_REPORT_INPUT_OUTPUT_BYTES = 1024 * 1024;
+export const NATIVE_REPORT_MAX_ARTIFACTS = 16;
+export class NativeObservationLimitError extends Error {
+    constructor(maximum) {
+        super(`Native observation limit exceeded (${maximum}); inspect retained reports before repeating work.`);
+        this.name = 'NativeObservationLimitError';
+    }
+}
+function identity(value) {
+    return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value) <= 256
+        && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function path(value) {
+    return typeof value === 'string' && value.length > 0 && Buffer.byteLength(value) <= 4096
+        && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function prefix(value, maximum) {
+    const encoded = Buffer.from(value);
+    let end = Math.min(encoded.length, maximum);
+    while (end > 0 && end < encoded.length && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return encoded.subarray(0, end).toString('utf8');
+}
+/** Only explicit command/action fields are retained; reasoning and opaque detail are display-only. */
+export function captureNativeReport(observation, fallback) {
+    if (observation.kind === 'reasoning')
+        return null;
+    const native = observation.native;
+    const provider = native?.provider ?? fallback.provider;
+    const turnId = native?.turnId ?? fallback.turnId;
+    const threadId = native?.threadId;
+    if (!identity(observation.id) || !identity(provider) || !identity(turnId)
+        || (threadId !== undefined && !identity(threadId)))
+        return null;
+    if (observation.kind === 'command' && !path(observation.command))
+        return null;
+    if (observation.kind === 'action' && (!identity(observation.label) || /reasoning|thinking|analysis/i.test(observation.label)))
+        return null;
+    if (observation.kind === 'command' && observation.cwd !== undefined && !path(observation.cwd))
+        return null;
+    const status = observation.status ?? 'unknown';
+    if (!identity(status))
+        return null;
+    const exitCode = observation.kind === 'command' ? observation.exitCode ?? null : null;
+    if (exitCode !== null && (!Number.isSafeInteger(exitCode) || typeof exitCode !== 'number'))
+        return null;
+    const durationMs = observation.kind === 'command' ? observation.durationMs : undefined;
+    if (durationMs !== undefined && (!Number.isSafeInteger(durationMs) || durationMs < 0))
+        return null;
+    const output = observation.output;
+    if (output !== undefined && (typeof output !== 'string' || Buffer.byteLength(output) > NATIVE_REPORT_INPUT_OUTPUT_BYTES))
+        return null;
+    const keptOutput = output === undefined ? undefined : prefix(output, NATIVE_REPORT_OUTPUT_BYTES);
+    const outputBytes = output === undefined ? 0 : Buffer.byteLength(output);
+    const omittedOutputBytes = outputBytes - (keptOutput === undefined ? 0 : Buffer.byteLength(keptOutput));
+    const artifacts = [];
+    const rawArtifacts = observation.kind === 'action' ? observation.artifacts ?? [] : [];
+    if (!Array.isArray(rawArtifacts) || rawArtifacts.length > 1024)
+        return null;
+    for (const artifact of rawArtifacts.slice(0, NATIVE_REPORT_MAX_ARTIFACTS)) {
+        if (!artifact || !path(artifact.path) || (artifact.sha256 !== undefined && !/^[a-f0-9]{64}$/.test(artifact.sha256)))
+            return null;
+        artifacts.push({ path: artifact.path, ...(artifact.sha256 === undefined ? {} : { sha256: artifact.sha256 }) });
+    }
+    const omittedArtifacts = rawArtifacts.length - artifacts.length;
+    const partial = output === undefined || status === 'unknown' || omittedOutputBytes > 0 || omittedArtifacts > 0
+        || (observation.kind === 'action' && observation.partial === true)
+        || (observation.kind === 'command' && exitCode === null);
+    const scope = { provider, ...(threadId === undefined ? {} : { threadId }), turnId, itemId: observation.id };
+    // Filesystem-safe names preserve the full source identity without provider-ID path/name limits.
+    const handle = `native_${createHash('sha256').update(JSON.stringify(scope)).digest('hex')}`;
+    const content = JSON.stringify({ schemaVersion: 1, kind: observation.kind, ...scope, status, exitCode,
+        ...(durationMs === undefined ? {} : { durationMs }),
+        ...(observation.kind === 'command' ? { command: observation.command, ...(observation.cwd === undefined ? {} : { cwd: observation.cwd }) }
+            : { label: observation.label, detailRetained: false }),
+        ...(keptOutput === undefined ? {} : { output: keptOutput, outputSha256: createHash('sha256').update(output).digest('hex') }),
+        outputBytes, omittedOutputBytes, artifacts, omittedArtifacts, partial, verification: 'unknown' });
+    return { handle, content, partial, isError: (exitCode !== null && exitCode !== 0) || status === 'failed'
+            || (observation.kind === 'action' && observation.isError === true),
+        source: { origin: 'provider_reported', originToolCallId: observation.id,
+            native: { ...scope, status, exitCode, ...(durationMs === undefined ? {} : { durationMs }) },
+            ...(observation.kind === 'command' && observation.cwd !== undefined ? { cwd: observation.cwd } : {}),
+            ...(artifacts.length ? { artifact: artifacts[0] } : {}) } };
+}

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

@@ -1,4 +1,5 @@
 import { type ExecutionSettings } from '../../config/execution.js';
+import type { ManagedCommandObservation } from './command_jobs.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. */
@@ -6,4 +7,5 @@ export declare function createRecoveryGuard(settings: ExecutionSettings): (resul
     name: string;
     content: string;
     isError: boolean;
+    managedCommand?: ManagedCommandObservation;
 }[]) => "continue" | "recover" | "stop";