klyro 1.0.0 → 1.0.1

package/dist/agent/runtime.d.ts

@@ -19,6 +19,16 @@ import type { Message } from './message.js';
 import type { ToolRegistry } from '../tools/registry.js';
 import type { PolicyEngine } from '../policy/engine.js';
 import type { ApprovalPrompt } from '../policy/approval.js';
+/**
+ * Verification mode. The canonical definition lives in verification/engine.ts
+ * (sibling-owned: `export type VerifyMode = 'strict'|'advisory'|'off'`). It is
+ * resolved conditionally here so this file typechecks regardless of sibling
+ * landing order — and converges to the sibling type automatically once the
+ * sibling export exists.
+ */
+export type VerifyMode = typeof import('../verification/engine.js') extends {
+    VerifyMode: infer V;
+} ? V : 'strict' | 'advisory' | 'off';
 export interface RuntimeDeps {
     adapter: ProviderAdapter;
     registry: ToolRegistry;
@@ -26,15 +36,34 @@ export interface RuntimeDeps {
     approval: ApprovalPrompt;
     /**
      * Build a system prompt given cwd + the current Level-7 runtime telemetry.
-     * The telemetry block is a compact, in-memory summary of the run so far
-     * (step count, last tool calls, recent errors). Injected as part of the
-     * system prompt so the model can see its own state mid-run.
+     *
+     * TELEMETRY SPLIT: the fn may return either a plain string (legacy —
+     * telemetry already concatenated, cache-unfriendly) or
+     * `{system, suffix}` where `suffix` is the volatile telemetry block.
+     * The runtime forwards both halves via CallRequest (`system` +
+     * `systemSuffix`) so adapters can keep the suffix out of the cacheable
+     * prefix (Anthropic array form) or concatenate it (OpenAI — unchanged).
+     * Both shapes are accepted so custom fns keep compiling.
      */
-    systemPrompt: (ctx: {
-        cwd: string;
-        telemetry?: string;
-    }) => string;
+    systemPrompt: SystemPromptFn;
 }
+/** Split system-prompt result: stable prefix + volatile telemetry suffix. */
+export interface SystemPromptResult {
+    system: string;
+    suffix?: string;
+}
+export type SystemPromptFn = (ctx: {
+    cwd: string;
+    telemetry?: string;
+}) => string | SystemPromptResult;
+/** Normalize either systemPrompt shape into {system, suffix}. */
+export declare function resolveSystemPrompt(fn: SystemPromptFn, ctx: {
+    cwd: string;
+    telemetry?: string;
+}): {
+    system: string;
+    suffix?: string;
+};
 export type Phase = 'understanding' | 'exploring' | 'planning' | 'implementing' | 'verifying' | 'done' | 'blocked' | 'limit';
 export interface RunOptions {
     task: string;
@@ -77,6 +106,9 @@ export interface RunOptions {
         maxRepairAttempts?: number;
         timeoutMs?: number;
         requireVerify?: boolean;
+        /** Verification mode (default 'strict'). 'off' skips the pipeline;
+         * 'advisory' runs verify once on completion without repair turns. */
+        mode?: VerifyMode;
     };
     /**
      * Level 9 — persistence. When a SessionStore is provided, every message
@@ -99,6 +131,8 @@ export interface RunOptions {
         depth: number;
         maxDepth: number;
         allowedTools?: ReadonlySet<string>;
+        /** Path allow-set inherited from the parent (sibling C contract). */
+        allowedPaths?: readonly string[];
         model?: string;
     };
     /**
@@ -160,6 +194,8 @@ export type RuntimeEvent = {
     input: number;
     output: number;
     estimated?: boolean;
+    cacheRead?: number;
+    cacheWrite?: number;
 } | {
     kind: 'final_text';
     text: string;
@@ -203,6 +239,8 @@ export interface RunResult {
         input: number;
         output: number;
         estimated?: boolean;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
     /** Number of policy-driven user prompts the user accepted. */
     repairs?: number;
@@ -212,6 +250,10 @@ export interface RunResult {
         command?: string;
         attempts: number;
         failureType?: string;
+        repairTokens?: {
+            input: number;
+            output: number;
+        };
     };
     /** 5.1 phase */
     phase?: Phase;
@@ -228,4 +270,4 @@ export declare function run(opts: RunOptions, deps: RuntimeDeps): Promise<RunRes
 export declare function defaultSystemPrompt(ctx: {
     cwd: string;
     telemetry?: string;
-}): string;
+}): SystemPromptResult;

package/dist/agent/runtime.js

@@ -23,10 +23,16 @@ import { verify, diagnosticForModel } from '../verification/engine.js';
 import { detectVerifyCommand } from '../verification/auto.js';
 import { ensureBaseline, getBaseline } from '../verification/baseline.js';
 import { compressTranscript, totalTokens } from '../context/tokenizer.js';
+import { ratesFor } from '../providers/model-info.js';
 import { classifyFailure, rerunOnce, gatherRepairContext, guardRepair } from '../verification/classify.js';
 import { findRelatedTests, buildScopedCommand, runScopedVerify, syntaxCheck, checkImports } from '../verification/scoped.js';
 import { globalBus } from '../events/bus.js';
 import { TraceWriter } from '../trace/writer.js';
+/** Normalize either systemPrompt shape into {system, suffix}. */
+export function resolveSystemPrompt(fn, ctx) {
+    const r = fn(ctx);
+    return typeof r === 'string' ? { system: r } : { system: r.system, suffix: r.suffix };
+}
 const DEFAULT_MAX_STEPS = 30;
 /** Convert a registry of tools into ToolDefinitions for the provider. */
 export function toolDefinitions(registry) {
@@ -36,19 +42,16 @@ export function toolDefinitions(registry) {
         inputSchema: t.function.parameters,
     }));
 }
-// BUG-005: Model-aware cost estimation with sensible defaults.
-// Rates are per-1K tokens (input / output). Local models are $0.
-const MODEL_RATES = [
-    { test: (m) => /gpt-4/i.test(m), input: 0.003, output: 0.015 },
-    { test: (m) => /gpt-3\.5/i.test(m), input: 0.0005, output: 0.0015 },
-    { test: (m) => /claude|anthropic/i.test(m), input: 0.003, output: 0.015 },
-    { test: (m) => /gemini/i.test(m), input: 0.00075, output: 0.003 },
-    { test: (m) => /o1/i.test(m), input: 0.015, output: 0.06 },
-];
+// BUG-005: Model-aware cost estimation, single-sourced from the
+// providers/model-info.ts rate table (local/unknown models are $0).
+// Cost is computed on input/output ONLY: cacheRead/cacheWrite are tracked
+// for observability but excluded because cached tokens bill at
+// provider-specific discounted rates we don't model — charging them at
+// full input rates would overstate spend, silently dropping them
+// understates it, so we keep them visible and out of the math.
 /** Estimate USD cost of a usage block given the model name. */
 export function estimateCost(model, usage) {
-    const match = MODEL_RATES.find((r) => r.test(model));
-    const { input: inRate, output: outRate } = match ?? { input: 0.003, output: 0.015 };
+    const { input: inRate, output: outRate } = ratesFor(model);
     return (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
 }
 // PERF-002: Memoized token counting cache.
@@ -93,6 +96,27 @@ export async function run(opts, deps) {
     let repairs = 0;
     let verificationAttempts = 0;
     let hasEdits = false;
+    // Overflow recovery: at most one compress-and-retry per run.
+    let overflowRetried = false;
+    // Repair ledger + guard: set from the first verification failure until a
+    // verification passes. repairUsageStart snapshots usage at failure time so
+    // every verification payload can attribute its repairTokens delta.
+    let inRepairTurn = false;
+    let repairUsageStart;
+    const verifyMode = opts.verify?.mode ?? 'strict';
+    const markRepairStarted = () => {
+        if (!repairUsageStart)
+            repairUsageStart = { input: usage.input, output: usage.output };
+        inRepairTurn = true;
+    };
+    const repairTokensNow = () => repairUsageStart
+        ? { input: usage.input - repairUsageStart.input, output: usage.output - repairUsageStart.output }
+        : undefined;
+    /** Attach repairTokens to a verification payload when a repair ledger exists. */
+    const withRepairTokens = (v) => {
+        const rt = repairTokensNow();
+        return rt ? { ...v, repairTokens: rt } : v;
+    };
     const emit = opts.onEvent;
     const telemetry = new RuntimeTelemetry();
     telemetry.setMaxSteps(maxSteps);
@@ -200,7 +224,7 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined, phase: 'blocked' };
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined, phase: 'blocked' };
         }
         steps++;
         // 5.1 phase transitions (model-narrated)
@@ -216,13 +240,21 @@ export async function run(opts, deps) {
             setPhase('verifying');
         emit?.({ kind: 'step_start', step: steps });
         telemetry.recordStepStart(steps);
-        const systemPrompt = deps.systemPrompt({ cwd: opts.cwd, telemetry: steps === 1 ? emptyTelemetryBlock() : telemetry.format() });
+        const { system: stableSystem, suffix: telemetrySuffix } = resolveSystemPrompt(deps.systemPrompt, {
+            cwd: opts.cwd,
+            telemetry: steps === 1 ? emptyTelemetryBlock() : telemetry.format(),
+        });
+        // Budget accounting sees what the model sees (prefix + suffix); the
+        // request itself keeps the halves split for cache-friendly adapters.
+        const systemForBudget = telemetrySuffix ? `${stableSystem}\n\n${telemetrySuffix}` : stableSystem;
         const BUDGET = { total: 120_000, reservedOutput: 4000 };
         let reqMessages = transcript;
-        let reqSystem = systemPrompt;
-        if (cachedTotalTokens(systemPrompt, transcript) > BUDGET.total) {
-            const c = compressTranscript(systemPrompt, transcript, BUDGET);
+        let reqSystem = stableSystem;
+        let reqSuffix = telemetrySuffix;
+        if (cachedTotalTokens(systemForBudget, transcript) > BUDGET.total) {
+            const c = compressTranscript(systemForBudget, transcript, BUDGET);
             reqSystem = c.system;
+            reqSuffix = undefined; // telemetry is regenerable — drop it under pressure
             reqMessages = c.messages;
             tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
             if (c.dropped > 0)
@@ -231,6 +263,7 @@ export async function run(opts, deps) {
         const req = {
             model: opts.parentContext?.model ?? opts.model,
             system: reqSystem,
+            ...(reqSuffix ? { systemSuffix: reqSuffix } : {}),
             messages: reqMessages,
             tools: toolDefinitions(deps.registry),
             ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
@@ -244,6 +277,8 @@ export async function run(opts, deps) {
         let thinkingBuf = '';
         const pendingToolCalls = new Map();
         let lastFinishReason;
+        // Set when this step's request must be re-issued after overflow recovery.
+        let overflowRetryPending = false;
         for await (const ev of events) {
             if (opts.signal?.aborted)
                 break outer;
@@ -273,14 +308,22 @@ export async function run(opts, deps) {
                 if (ev.usage) {
                     usage.input += ev.usage.input;
                     usage.output += ev.usage.output;
+                    if (ev.usage.cacheRead !== undefined)
+                        usage.cacheRead = (usage.cacheRead ?? 0) + ev.usage.cacheRead;
+                    if (ev.usage.cacheWrite !== undefined)
+                        usage.cacheWrite = (usage.cacheWrite ?? 0) + ev.usage.cacheWrite;
                     telemetry.recordUsage(ev.usage.input, ev.usage.output);
-                    emit?.({ kind: 'usage', input: usage.input, output: usage.output });
+                    emit?.({
+                        kind: 'usage', input: usage.input, output: usage.output,
+                        ...(usage.cacheRead !== undefined ? { cacheRead: usage.cacheRead } : {}),
+                        ...(usage.cacheWrite !== undefined ? { cacheWrite: usage.cacheWrite } : {}),
+                    });
                 }
                 else {
                     // Providers that omit usage (Ollama, vLLM, proxies): estimate from
                     // the actual request + generated output so cost accounting never
                     // silently records zero. Marked estimated for the UI/debugging.
-                    const est = estimateTurnUsage(reqSystem, reqMessages, textBuf, pendingToolCalls);
+                    const est = estimateTurnUsage(systemForBudget, reqMessages, textBuf, pendingToolCalls);
                     usage.input += est.input;
                     usage.output += est.output;
                     usage.estimated = true;
@@ -289,6 +332,31 @@ export async function run(opts, deps) {
                 }
             }
             else if (ev.kind === 'error') {
+                // Overflow recovery: on the first REQUEST_TOO_LARGE of a run,
+                // aggressively compact the transcript and re-issue the request once.
+                // A second occurrence fails normally (returned as no_final below).
+                if (ev.code === 'REQUEST_TOO_LARGE' && !overflowRetried) {
+                    overflowRetried = true;
+                    overflowRetryPending = true;
+                    telemetry.recordError('overflow_retry');
+                    emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'REQUEST_TOO_LARGE', message: 'context overflow — aggressively compacting transcript and retrying the request once' });
+                    try {
+                        const compacted = compressTranscript(reqSystem, transcript, { total: 30_000, reservedOutput: 4000 });
+                        if (compacted.messages.length < transcript.length || compacted.dropped > 0) {
+                            transcript.splice(0, transcript.length, ...compacted.messages);
+                        }
+                        else {
+                            // Transcript already fits the aggressive budget — force it
+                            // strictly smaller so the retry cannot repeat the overflow.
+                            const halved = Math.max(4000, Math.floor(totalTokens(reqSystem, transcript) / 2));
+                            const smaller = compressTranscript(reqSystem, transcript, { total: halved, reservedOutput: 4000 });
+                            transcript.splice(0, transcript.length, ...smaller.messages);
+                        }
+                        tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
+                    }
+                    catch { /* ignore — retry with the transcript as-is */ }
+                    break;
+                }
                 telemetry.recordError(`stream_error: ${ev.code}`);
                 if (store && sessionId) {
                     try {
@@ -306,10 +374,18 @@ export async function run(opts, deps) {
                     hasEdits,
                     usage,
                     repairs,
-                    verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined,
+                    verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined,
                 };
             }
         }
+        // Overflow recovery lands here via `break`: re-issue the same step
+        // without consuming the step budget.
+        if (overflowRetryPending) {
+            overflowRetryPending = false;
+            steps--;
+            emit?.({ kind: 'step_end', step: steps + 1 });
+            continue outer;
+        }
         // Build the assistant message. Tool calls are finalized here: JSON is
         // parsed and schema-validated BEFORE policy/execution. Malformed calls
         // become structured MALFORMED_TOOL_CALL results — garbage arguments must
@@ -368,7 +444,7 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
             if (hadInvalidTool) {
@@ -380,6 +456,66 @@ export async function run(opts, deps) {
                 continue;
             }
             finalText = textBuf;
+            // Verify modes: 'off' skips the pipeline entirely (verification stays
+            // undefined, no repair turns). 'advisory' runs verify once on
+            // completion and reports the outcome without repair turns. 'strict'
+            // (default) runs the full pipeline with autonomous repair below.
+            if (verifyMode === 'off') {
+                emit?.({ kind: 'final_text', text: finalText });
+                emit?.({ kind: 'step_end', step: steps });
+                if (store && sessionId) {
+                    try {
+                        await store.setStatus(sessionId, 'complete', finalText);
+                    }
+                    catch { /* ignore */ }
+                }
+                await closeTracer();
+                return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: undefined };
+            }
+            if (verifyMode === 'advisory') {
+                const advisoryCmd = opts.verify?.command ?? detectVerifyCommand(opts.cwd);
+                if (opts.verify?.enabled !== false && hasEdits && advisoryCmd) {
+                    emit?.({ kind: 'verification_started', command: advisoryCmd });
+                    let advisoryResult;
+                    try {
+                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs });
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        advisoryResult = { ok: false, exitCode: -1, stdout: '', stderr: msg, failure: { type: 'unknown', files: [], raw: msg, exitCode: -1 } };
+                    }
+                    verificationAttempts++;
+                    if (advisoryResult.ok) {
+                        inRepairTurn = false;
+                        emit?.({ kind: 'verification_succeeded', command: advisoryCmd });
+                        emit?.({ kind: 'final_text', text: finalText });
+                        emit?.({ kind: 'step_end', step: steps });
+                        if (store && sessionId) {
+                            try {
+                                await store.setStatus(sessionId, 'complete', finalText);
+                            }
+                            catch { /* ignore */ }
+                        }
+                        await closeTracer();
+                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: advisoryCmd, attempts: verificationAttempts }) };
+                    }
+                    const advisoryFailure = advisoryResult.failure?.type ?? 'unknown';
+                    markRepairStarted();
+                    emit?.({ kind: 'verification_failed', step: String(steps), reason: diagnosticForModel(advisoryResult).slice(0, 800) });
+                    emit?.({ kind: 'final_text', text: finalText });
+                    emit?.({ kind: 'step_end', step: steps });
+                    if (store && sessionId) {
+                        try {
+                            await store.setStatus(sessionId, 'complete', finalText);
+                        }
+                        catch { /* ignore */ }
+                    }
+                    await closeTracer();
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: advisoryCmd, attempts: verificationAttempts, failureType: advisoryFailure }) };
+                }
+                // No verify applicable (disabled, no edits, or no command) — fall
+                // through to the normal completion return below.
+            }
             // Level 8 — Verification + Autonomous Repair (gated on hasEdits below — pure analysis skips verify)
             const verifyEnabled = opts.verify?.enabled !== false;
             const verifyCmd = opts.verify?.command ?? detectVerifyCommand(opts.cwd);
@@ -439,6 +575,7 @@ export async function run(opts, deps) {
                     catch { /* scoped success is enough */ }
                 }
                 if (vResult.ok) {
+                    inRepairTurn = false;
                     emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
@@ -449,7 +586,7 @@ export async function run(opts, deps) {
                         catch { /* ignore */ }
                     }
                     await closeTracer();
-                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                 }
                 // 6.4 — classify
                 const baseline = await getBaseline(opts.cwd, verifyCmd);
@@ -457,6 +594,7 @@ export async function run(opts, deps) {
                 const cls = classifyFailure({ failure: vResult.failure, stdout: vResult.stdout, stderr: vResult.stderr }, baseline, isFlaky);
                 if (cls === 'flaky') {
                     // rerun succeeded on second try — treat as flaky, don't count as repair
+                    inRepairTurn = false;
                     emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
@@ -467,7 +605,7 @@ export async function run(opts, deps) {
                         catch { /* ignore */ }
                     }
                     await closeTracer();
-                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                 }
                 if (cls === 'env') {
                     // don't try to repair env failures with code edits
@@ -475,10 +613,11 @@ export async function run(opts, deps) {
                     transcript.push(envMsg);
                     await checkpoint(envMsg);
                     verificationAttempts++;
+                    markRepairStarted();
                     emit?.({ kind: 'verification_failed', step: String(steps), reason: `env: ${diagnosticForModel(vResult).slice(0, 600)}` });
                     if (verificationAttempts >= maxRepairs) {
                         await closeTracer();
-                        return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: false, command: verifyCmd, attempts: verificationAttempts, failureType: 'env' } };
+                        return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: verifyCmd, attempts: verificationAttempts, failureType: 'env' }) };
                     }
                     emit?.({ kind: 'step_end', step: steps });
                     continue;
@@ -494,6 +633,7 @@ export async function run(opts, deps) {
                     const failurePaths = new Set(vResult.failure?.files.map((f) => f.path).filter(Boolean) ?? []);
                     const overlaps = [...failurePaths].some((p) => introducedPaths.has(p) || introducedPaths.has(path.basename(p)));
                     if (!overlaps) {
+                        inRepairTurn = false;
                         emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                         emit?.({ kind: 'final_text', text: finalText });
                         emit?.({ kind: 'step_end', step: steps });
@@ -504,11 +644,12 @@ export async function run(opts, deps) {
                             catch { /* ignore */ }
                         }
                         await closeTracer();
-                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                     }
                 }
                 // Failure → repair loop (introduced)
                 verificationAttempts++;
+                markRepairStarted();
                 const diagnostic = diagnosticForModel(vResult);
                 const failureType = vResult.failure?.type ?? 'unknown';
                 // 6.4 — gather context
@@ -548,7 +689,7 @@ export async function run(opts, deps) {
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
                     await closeTracer();
-                    return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: false, command: verifyCmd, attempts: verificationAttempts, failureType } };
+                    return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: verifyCmd, attempts: verificationAttempts, failureType }) };
                 }
                 emit?.({ kind: 'step_end', step: steps });
                 continue; // -> next iteration lets model repair
@@ -562,11 +703,10 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: true, attempts: verificationAttempts } : undefined };
+            return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: true, attempts: verificationAttempts }) : undefined };
         }
         // 3.1 — emit turn events
         emitKlyro({ type: 'turn.start', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', turn: steps, model: opts.model });
-        // Execute each tool call (after policy) — 3.5 parallel if all concurrencySafe
         const toolCtx = {
             cwd: opts.cwd,
             env: process.env,
@@ -580,7 +720,9 @@ export async function run(opts, deps) {
             agentDepth: opts.parentContext?.depth ?? 0,
             agentMaxDepth: opts.parentContext?.maxDepth ?? 1,
             ...(opts.parentContext?.allowedTools ? { agentAllowedTools: opts.parentContext.allowedTools } : {}),
+            ...(opts.parentContext?.allowedPaths ? { agentAllowedPaths: opts.parentContext.allowedPaths } : {}),
             ...(opts.parentContext?.model ?? opts.model ? { agentModel: opts.parentContext?.model ?? opts.model } : {}),
+            repairGuard: { denyTestEdits: inRepairTurn },
         };
         const allSafe = finalizedCalls.length > 1 && finalizedCalls.every((c) => deps.registry.get(c.name)?.isConcurrencySafe !== false);
         // Gate phase: policy decision + approval prompt for one call. Runs
@@ -591,7 +733,12 @@ export async function run(opts, deps) {
             const decision = await deps.policy.evaluate({ name: call.name, input: call.input }, { cwd: opts.cwd, nonInteractive: opts.nonInteractive });
             emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: decision.action, ...(decision.action !== 'allow' ? { reason: decision.reason } : {}) });
             // Mirror to KlyroEvent bus
-            emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: decision.action, ...(decision.action !== 'allow' ? { reason: decision.reason } : {}) });
+            if (decision.action === 'allow') {
+                emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: 'allow' });
+            }
+            else {
+                emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: decision.action, reason: decision.reason });
+            }
             if (decision.action === 'deny') {
                 const denyMsg = {
                     role: 'tool',
@@ -770,6 +917,19 @@ export async function run(opts, deps) {
                     break;
             }
         }
+        // P0 — drain finished sub-agent completions into parent visibility.
+        // drainCompletions is OPTIONAL on the bridge — guarded with `?.` so
+        // older bridges without it simply yield nothing.
+        try {
+            const completions = opts.agentBridge?.drainCompletions?.() ?? [];
+            for (const c of completions) {
+                const body = c.finalText ?? c.error?.message ?? '';
+                const msg = { role: 'user', content: [text(`Subtask ${c.taskId} (${c.agentName}) ${c.status}: ${body.slice(0, 500)}`)] };
+                transcript.push(msg);
+                await checkpoint(msg);
+            }
+        }
+        catch { /* ignore — completions are best-effort visibility */ }
         emit?.({ kind: 'step_end', step: steps });
         emitKlyro({ type: 'turn.end', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', turn: steps });
         // Level 9 — checkpoint status after each step
@@ -792,7 +952,7 @@ export async function run(opts, deps) {
             catch { /* ignore */ }
         }
         await closeTracer();
-        return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+        return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
     }
     // 5.2 — stuck termination (P0-3): bounded stop instead of unbounded token burn.
     if (stuckAbort) {
@@ -804,7 +964,7 @@ export async function run(opts, deps) {
             catch { /* ignore */ }
         }
         await closeTracer();
-        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
     }
     emit?.({ kind: 'final_text', text: finalText });
     if (store && sessionId) {
@@ -814,7 +974,7 @@ export async function run(opts, deps) {
         catch { /* ignore */ }
     }
     await closeTracer();
-    return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+    return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
 }
 /**
  * Estimate usage for a turn whose provider omitted it (Ollama, vLLM,
@@ -950,7 +1110,10 @@ export function defaultSystemPrompt(ctx) {
         'Do not invent file paths. Do not call tools outside the working directory.',
     ].join(' ');
     if (ctx.telemetry) {
-        return base + '\n\n' + ctx.telemetry + '\n\nUse the telemetry above to avoid repeating the same failing call and to keep within the step budget.';
+        return {
+            system: base,
+            suffix: ctx.telemetry + '\n\nUse the telemetry above to avoid repeating the same failing call and to keep within the step budget.',
+        };
     }
-    return base;
+    return { system: base };
 }

package/dist/agent/worktree-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Git worktree isolation for parallel write-capable child agents.
+ *
+ * Each write-capable child gets its own worktree on a branch
+ * `klyro/<taskId>` so concurrent children never clobber each other's files.
+ * `task_apply` merges the branch back into the parent tree; failures,
+ * cancellations, and timeouts remove the worktree best-effort.
+ *
+ * Semantics worth knowing:
+ *   - Dirty parent: the merge runs in the parent checkout, so uncommitted
+ *     parent edits can conflict. On conflict the merge is ABORTED (no
+ *     commit), the branch is kept, and the caller gets MERGE_CONFLICT with
+ *     the file list — resolve and re-apply.
+ *   - Stale branch: a leftover `klyro/<taskId>` branch (e.g. from a crashed
+ *     session) makes `createWorktree` fail. Delete the stale branch
+ *     (`deleteBranch`) or sweep orphaned worktrees (`pruneStaleWorktrees`)
+ *     before retrying.
+ *   - No-apply: tasks that never reach `succeeded` are NEVER merged — their
+ *     worktrees are removed best-effort and `task_apply` reports NOT_READY.
+ *
+ * All git invocations go through `execFile` argv (no shell) with a ~30s
+ * timeout, so this is safe on Windows.
+ */
+/** Per-command timeout for every git invocation. */
+export declare const GIT_TIMEOUT_MS = 30000;
+export interface WorktreeInfo {
+    worktreePath: string;
+    branch: string;
+}
+export interface MergeResult {
+    merged: boolean;
+    conflictFiles: string[];
+}
+/** True when `cwd` is inside a git working tree. Never throws — false on any failure. */
+export declare function ensureGitRepo(cwd: string): Promise<boolean>;
+/** Resolve the repo top-level for any path inside it. Throws when not in a repo. */
+export declare function repoTopLevel(cwd: string): Promise<string>;
+/**
+ * Create an isolated worktree for a task on branch `klyro/<taskId>`,
+ * rooted at `<repo>/.klyro/worktrees/<taskId>` from HEAD.
+ */
+export declare function createWorktree(opts: {
+    repoCwd: string;
+    taskId: string;
+}): Promise<WorktreeInfo>;
+/**
+ * Merge a task branch into the current checkout (`repoCwd`) with
+ * `git merge --no-ff --no-edit`. On conflict, parses `git status
+ * --porcelain` for unmerged paths (UU/AA/DD), aborts the merge WITHOUT
+ * committing, and returns `{ merged: false, conflictFiles }`.
+ */
+export declare function mergeWorktree(opts: {
+    repoCwd: string;
+    branch: string;
+}): Promise<MergeResult>;
+/** Remove a worktree and prune its metadata. Throws with context on failure. */
+export declare function removeWorktree(opts: {
+    repoCwd: string;
+    worktreePath: string;
+    force?: boolean;
+}): Promise<void>;
+/** Delete a task branch (best-effort cleanup after a successful merge). Never throws. */
+export declare function deleteBranch(opts: {
+    repoCwd: string;
+    branch: string;
+}): Promise<void>;
+/**
+ * Remove worktrees under `.klyro/worktrees` whose task id is NOT in
+ * `activeTaskIds` (orphans from crashed/timed-out sessions). Lists
+ * `git worktree list --porcelain`, force-removes each stale entry, and
+ * returns the removed paths. Never throws — per-worktree failures are
+ * skipped and a failing `git` itself yields `[]`.
+ */
+export declare function pruneStaleWorktrees(repoCwd: string, activeTaskIds: readonly string[]): Promise<string[]>;