klyro 1.0.0 → 1.0.2

package/dist/agent/runtime.js

@@ -23,10 +23,17 @@ 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, isAnthropicModel } 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';
+import { loadHooks, runHook } from '../cli/hooks.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,21 +43,30 @@ 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 },
-];
+// Model-aware cost estimation, single-sourced from the
+// providers/model-info.ts rate table (local/unknown models are $0).
+// Cache-aware: for Anthropic-family models (isAnthropicModel), cacheRead
+// bills at 0.1× the input rate and cacheWrite at 1.25×; all other
+// families ignore cache counters (discounted billing, unmodeled).
 /** 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 };
-    return (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
+    const { input: inRate, output: outRate } = ratesFor(model);
+    const base = (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
+    if (!isAnthropicModel(model))
+        return base;
+    const read = ((usage.cacheRead ?? 0) / 1000) * inRate * 0.1;
+    const write = ((usage.cacheWrite ?? 0) / 1000) * inRate * 1.25;
+    return base + read + write;
 }
+/**
+ * Parallel fan-out cap: approved concurrencySafe tool calls execute in
+ * sequential chunks of at most this size. Commit order stays identical
+ * (commits run sequentially after execution), so the transcript reads as
+ * if the calls ran in order.
+ */
+export const MAX_PARALLEL_TOOLS = 8;
+/** Progressive budget-warning thresholds (fraction of maxCost), fired once each per run. */
+export const BUDGET_WARNING_THRESHOLDS = [0.4, 0.7, 0.9];
 // PERF-002: Memoized token counting cache.
 let tokenCache = {
     lastRef: null,
@@ -87,15 +103,69 @@ export async function run(opts, deps) {
         return [{ role: 'user', content: [text(opts.task)] }];
     })();
     const usage = { input: 0, output: 0 };
+    /** Emit one `budget_warning` per threshold the cost ratio has crossed. */
+    const checkBudgetWarnings = () => {
+        if (maxCost === undefined || maxCost <= 0)
+            return;
+        const ratio = estimateCost(opts.model, usage) / maxCost;
+        for (const threshold of BUDGET_WARNING_THRESHOLDS) {
+            if (ratio >= threshold && !firedBudgetWarnings.has(threshold)) {
+                firedBudgetWarnings.add(threshold);
+                emit?.({ kind: 'budget_warning', ratio, threshold });
+            }
+        }
+    };
     let steps = 0;
     let toolCallCount = 0;
     let finalText = '';
     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);
+    // Model-override surfacing (informational): when a parent/orchestrator
+    // context carries a model override, emit it once so UIs can show which
+    // model actually serves this run.
+    if (opts.parentContext?.model) {
+        emit?.({ kind: 'model_override', requested: opts.model, effective: opts.parentContext.model });
+    }
+    // Hooks engine: loaded once per run. Zero-cost fast path — when no hooks
+    // file exists, both lists are empty and every hook call site is skipped.
+    let runHooks = [];
+    try {
+        runHooks = loadHooks(opts.cwd);
+    }
+    catch {
+        runHooks = [];
+    }
+    const preHooks = runHooks.filter((h) => h.event === 'preToolUse');
+    const postHooks = runHooks.filter((h) => h.event === 'postToolUse');
+    // L15 failover chain: the active adapter starts as deps.adapter; each
+    // terminal provider error consumes one fallback. Bounded — never loops.
+    let activeAdapter = deps.adapter;
+    const failoverQueue = [...(deps.failoverAdapters ?? [])];
     // 3.1 — Event bus + TraceWriter
     const bus = deps.bus ?? globalBus;
     let tracer;
@@ -116,6 +186,10 @@ export async function run(opts, deps) {
     // 5.1 — phases and limits
     const maxCost = opts.maxCost;
     const maxTimeMs = opts.maxTimeMs;
+    // Progressive budget warnings: fire once per threshold per run when the
+    // cost ratio crosses 0.4 / 0.7 / 0.9 of maxCost (checker defined after
+    // `usage` is declared below).
+    const firedBudgetWarnings = new Set();
     const startTime = Date.now();
     let phase = 'understanding';
     const setPhase = (p) => {
@@ -200,7 +274,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 +290,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,19 +313,28 @@ 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 } : {}),
             ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
             ...(opts.signal ? { signal: opts.signal } : {}),
         };
-        const events = deps.adapter.stream(req);
+        const events = activeAdapter.stream(req);
         let textBuf = '';
         // Thinking is ephemeral: streamed to the UI live, never stored in the
         // transcript, and cleared when the turn's answer completes.
         let thinkingBuf = '';
         const pendingToolCalls = new Map();
         let lastFinishReason;
+        // Set when this step's request must be re-issued after overflow recovery.
+        let overflowRetryPending = false;
+        // Set when a terminal provider error consumed a failover adapter — the
+        // step is re-issued against the next adapter without consuming budget.
+        let failoverPending = false;
+        let failoverFrom = '';
+        let failoverTo = '';
+        let failoverReason = '';
         for await (const ev of events) {
             if (opts.signal?.aborted)
                 break outer;
@@ -273,22 +364,75 @@ 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 } : {}),
+                    });
+                    checkBudgetWarnings();
                 }
                 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;
                     telemetry.recordUsage(est.input, est.output);
                     emit?.({ kind: 'usage', input: usage.input, output: usage.output, estimated: true });
+                    checkBudgetWarnings();
                 }
             }
             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;
+                }
+                // L15 failover: a terminal provider error swaps to the next chained
+                // adapter and re-issues the step (bounded by chain length). Context
+                // overflow is excluded — it owns its own recovery above. By the time
+                // an error reaches the runtime, per-adapter retries are exhausted,
+                // so any provider error here is terminal for the active adapter.
+                if (failoverQueue.length > 0) {
+                    const next = failoverQueue.shift();
+                    failoverPending = true;
+                    failoverFrom = activeAdapter.id;
+                    failoverTo = next.id;
+                    failoverReason = `${ev.code}: ${ev.message}`.slice(0, 300);
+                    activeAdapter = next;
+                    telemetry.recordError(`failover: ${ev.code}`);
+                    emit?.({ kind: 'provider_failover', from: failoverFrom, to: failoverTo, reason: failoverReason });
+                    emit?.({ kind: 'status', message: `provider ${failoverFrom} failed (${ev.code}) — failing over to ${failoverTo}` });
+                    emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: ev.code, message: `failing over ${failoverFrom} → ${failoverTo}: ${ev.message.slice(0, 200)}` });
+                    break;
+                }
                 telemetry.recordError(`stream_error: ${ev.code}`);
                 if (store && sessionId) {
                     try {
@@ -306,10 +450,31 @@ 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;
+        }
+        // Failover lands here via `break`: discard the failed attempt's partial
+        // output and re-issue the same step against the next adapter, again
+        // without consuming the step budget.
+        if (failoverPending) {
+            failoverPending = false;
+            textBuf = '';
+            thinkingBuf = '';
+            pendingToolCalls.clear();
+            lastFinishReason = undefined;
+            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 +533,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 +545,67 @@ 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 {
+                        // CONTRACT (a): sessionId passthrough to the verify engine.
+                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
+                    }
+                    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);
@@ -421,7 +647,7 @@ export async function run(opts, deps) {
                             vResult = { ok: sr.ok, exitCode: sr.exitCode, stdout: sr.stdout, stderr: sr.stderr, ...(det ? { failure: det } : {}) };
                         }
                         else {
-                            vResult = await verify({ cwd: opts.cwd, command: cmdToRun, timeoutMs: opts.verify?.timeoutMs });
+                            vResult = await verify({ cwd: opts.cwd, command: cmdToRun, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
                         }
                     }
                     catch (e) {
@@ -432,13 +658,14 @@ export async function run(opts, deps) {
                 // If scoped passed but full may still fail, run full before declaring success
                 if (vResult.ok && isScoped) {
                     try {
-                        const full = await verify({ cwd: opts.cwd, command: verifyCmd, timeoutMs: opts.verify?.timeoutMs });
+                        const full = await verify({ cwd: opts.cwd, command: verifyCmd, timeoutMs: opts.verify?.timeoutMs, ...(sessionId ? { sessionId } : {}) });
                         if (!full.ok)
                             vResult = full;
                     }
                     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 +676,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 +684,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 +695,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 +703,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 +723,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 +734,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 +779,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 +793,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 +810,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 +823,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',
@@ -640,6 +877,32 @@ export async function run(opts, deps) {
         const execTool = async (call) => {
             const t0 = Date.now();
             emitKlyro({ type: 'tool.call', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, input: call.input });
+            // Hooks: every preToolUse hook runs before execution. A non-zero exit
+            // denies the tool with POLICY_DENIED — the real tool never runs.
+            if (preHooks.length > 0) {
+                for (const hook of preHooks) {
+                    let exitCode = -1;
+                    let detail = '';
+                    try {
+                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        exitCode = r.exitCode;
+                        detail = (r.stderr || r.stdout || '').slice(0, 300);
+                    }
+                    catch (err) {
+                        detail = String(err instanceof Error ? err.message : err).slice(0, 300);
+                    }
+                    if (exitCode !== 0) {
+                        const reason = `hook ${hook.name} denied: ${detail || 'hook failed'}`;
+                        emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: 'deny', reason });
+                        emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: 'deny', reason });
+                        const latencyMs = Date.now() - t0;
+                        return {
+                            obs: { ok: false, error: { code: 'POLICY_DENIED', message: reason } },
+                            latencyMs,
+                        };
+                    }
+                }
+            }
             let obs;
             try {
                 obs = await deps.registry.execute(call.name, call.input, toolCtx);
@@ -727,6 +990,31 @@ export async function run(opts, deps) {
             if (last3.length === 3 && last3[0] === last3[1] && last3[1] === last3[2]) {
                 await markStuck(`identical call ×3: ${sig}`);
             }
+            // Hooks: postToolUse hooks are best-effort — failures warn on stderr
+            // plus a bus event, and never fail the turn.
+            if (postHooks.length > 0) {
+                for (const hook of postHooks) {
+                    try {
+                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        if (!r.ok || r.exitCode !== 0) {
+                            const msg = `klyro: hooks: postToolUse ${hook.name} failed (exit ${String(r.exitCode)}): ${(r.stderr || r.stdout || '').slice(0, 200)}\n`;
+                            try {
+                                process.stderr.write(msg);
+                            }
+                            catch { /* ignore */ }
+                            emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'hook_failed', message: msg.slice(0, 300) });
+                        }
+                    }
+                    catch (err) {
+                        const msg = `klyro: hooks: postToolUse ${hook.name} error: ${String(err instanceof Error ? err.message : err).slice(0, 200)}\n`;
+                        try {
+                            process.stderr.write(msg);
+                        }
+                        catch { /* ignore */ }
+                        emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'hook_failed', message: msg.slice(0, 300) });
+                    }
+                }
+            }
         };
         // Sequential path: gate → execute → commit per call, in order.
         const runOne = async (call) => {
@@ -750,8 +1038,17 @@ export async function run(opts, deps) {
                     break;
             }
             if (approved.length > 0 && !opts.signal?.aborted) {
-                const settled = await Promise.allSettled(approved.map((c) => execTool(c)));
-                for (let i = 0; i < approved.length; i++) {
+                // Fan-out cap: execute in sequential chunks of MAX_PARALLEL_TOOLS.
+                // Commits below stay in original call order, so the transcript is
+                // unaffected by the chunking.
+                const settled = [];
+                for (let off = 0; off < approved.length; off += MAX_PARALLEL_TOOLS) {
+                    if (opts.signal?.aborted)
+                        break;
+                    const chunk = approved.slice(off, off + MAX_PARALLEL_TOOLS);
+                    settled.push(...await Promise.allSettled(chunk.map((c) => execTool(c))));
+                }
+                for (let i = 0; i < settled.length; i++) {
                     const s = settled[i];
                     if (s.status === 'fulfilled') {
                         await commitResult(approved[i], s.value.obs, s.value.latencyMs);
@@ -770,6 +1067,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 +1102,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 +1114,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 +1124,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 +1260,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 };
 }