klyro 1.0.1 → 1.0.2

package/dist/agent/anthropic-adapter.d.ts

@@ -72,6 +72,9 @@ interface AnthropicRequest {
         name: string;
         description: string;
         input_schema: unknown;
+        cache_control?: {
+            type: 'ephemeral';
+        };
     }>;
     max_tokens: number;
     temperature?: number;
@@ -94,6 +97,14 @@ export declare function anthropicAdapter(opts: AnthropicAdapterOptions): Provide
  * Exported via _internal for testing.
  */
 export declare function buildAnthropicSystem(system: string | undefined, suffix: string | undefined, promptCache: boolean): AnthropicRequest['system'];
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export declare function buildAnthropicTools(tools: ToolDefinition[], promptCache: boolean): AnthropicRequest['tools'];
 /**
  * Mutable per-stream assembly state. Blocks are keyed by content_block
  * index; the tool id is carried inside the block entry. There is no global
@@ -118,15 +129,12 @@ interface AnthropicStreamState {
 }
 declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
 declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
-declare function toAnthropicTool(t: ToolDefinition): {
-    name: string;
-    description: string;
-    input_schema: unknown;
-};
+declare function toAnthropicTool(t: ToolDefinition): NonNullable<AnthropicRequest['tools']>[number];
 export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
     translateSse: typeof translateSse;
     buildAnthropicSystem: typeof buildAnthropicSystem;
+    buildAnthropicTools: typeof buildAnthropicTools;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -75,12 +75,29 @@ export function buildAnthropicSystem(system, suffix, promptCache) {
         return undefined;
     return promptCache ? [{ type: 'text', text: system, ...breakpoint }] : system;
 }
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export function buildAnthropicTools(tools, promptCache) {
+    if (tools.length === 0)
+        return undefined;
+    const out = tools.map(toAnthropicTool);
+    if (promptCache) {
+        const last = out[out.length - 1];
+        last.cache_control = { type: 'ephemeral' };
+    }
+    return out;
+}
 async function* streamAnthropic(req, opts) {
     const body = {
         model: req.model,
         system: buildAnthropicSystem(req.system, req.systemSuffix, opts.promptCache),
         messages: toAnthropicMessages(req.messages),
-        tools: req.tools.length > 0 ? req.tools.map(toAnthropicTool) : undefined,
+        tools: buildAnthropicTools(req.tools, opts.promptCache),
         max_tokens: req.maxTokens ?? 4096,
         temperature: req.temperature,
         stream: true,
@@ -430,4 +447,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem, buildAnthropicTools };

package/dist/agent/capabilities.js

@@ -187,5 +187,11 @@ export const DEFAULT_SPAWN_TOOLS = new Set([
 ]);
 /** Default deny-list — these are NEVER allowed, even if explicitly requested. */
 export const DEFAULT_DENIED_TOOLS = new Set([
-// Add dangerous tools here. Empty by default — extend as policy matures.
+// Intentionally empty. Deny happens per-pattern (shellDenyRule /
+// DANGEROUS_PATTERNS, .env guards, repair-guard), not per-tool: a
+// tool-granularity deny-all entry (e.g. banning `shell_exec` outright)
+// would break legitimate flows that rely on the allowlist + approval
+// path. Seed candidates considered and rejected: `shell_exec` (needed
+// for tests/builds via approval), `run_verify` (needed by tester/
+// implementer agents), `write_file`/`edit_file` (core agent function).
 ]);

package/dist/agent/orchestrator.d.ts

@@ -12,7 +12,7 @@
  * The compact result is a `ChildSummary` — a `ToolResult` the parent model
  * can act on — never the full child transcript.
  */
-import type { RuntimeDeps } from './runtime.js';
+import type { RuntimeDeps, RuntimeEvent } from './runtime.js';
 import type { ToolResult } from '../tools/types.js';
 import { TaskManager, type TaskRecord, type TaskStatus, type TaskSummary } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
@@ -157,6 +157,23 @@ export interface OrchestratorOpts {
      */
     isTui?: boolean;
 }
+/**
+ * Build a `subtask.progress` note for one finished tool call.
+ * Pure — unit-tested directly (see agent-tools.test.ts).
+ */
+export declare function progressNote(step: number, tool: string, isError: boolean): string;
+/**
+ * Build the `RunOptions.onEvent` handler the orchestrator passes into each
+ * child's run options. Emits at most one `subtask.progress` per tool call:
+ * a `tool_result` is only mirrored when its `tool_call_end` was observed
+ * first, so duplicate/late results can never double-emit. (The note needs
+ * the ok/ERR outcome, which only `tool_result` carries — `tool_call_end`
+ * alone cannot build it — hence the end-gated result throttle.)
+ */
+export declare function createSubtaskProgressEmitter(opts: {
+    taskId: string;
+    sessionId: string;
+}): (ev: RuntimeEvent) => void;
 export declare class AgentOrchestrator {
     readonly sessionId: string;
     readonly deps: RuntimeDeps;

package/dist/agent/orchestrator.js

@@ -87,6 +87,45 @@ function mapResultStatus(status) {
             return 'failed';
     }
 }
+/**
+ * Build a `subtask.progress` note for one finished tool call.
+ * Pure — unit-tested directly (see agent-tools.test.ts).
+ */
+export function progressNote(step, tool, isError) {
+    return `step ${step}: ${tool} ${isError ? 'ERR' : 'ok'}`;
+}
+/**
+ * Build the `RunOptions.onEvent` handler the orchestrator passes into each
+ * child's run options. Emits at most one `subtask.progress` per tool call:
+ * a `tool_result` is only mirrored when its `tool_call_end` was observed
+ * first, so duplicate/late results can never double-emit. (The note needs
+ * the ok/ERR outcome, which only `tool_result` carries — `tool_call_end`
+ * alone cannot build it — hence the end-gated result throttle.)
+ */
+export function createSubtaskProgressEmitter(opts) {
+    let step = 0;
+    const ended = new Set();
+    return (ev) => {
+        if (ev.kind === 'step_start') {
+            step = ev.step;
+        }
+        else if (ev.kind === 'tool_call_end') {
+            ended.add(ev.id);
+        }
+        else if (ev.kind === 'tool_result') {
+            if (!ended.has(ev.id))
+                return;
+            ended.delete(ev.id);
+            globalBus.emit({
+                type: 'subtask.progress',
+                ts: Date.now(),
+                sessionId: opts.sessionId,
+                taskId: opts.taskId,
+                note: progressNote(step, ev.name, ev.isError),
+            });
+        }
+    };
+}
 export class AgentOrchestrator {
     sessionId;
     deps;
@@ -212,14 +251,17 @@ export class AgentOrchestrator {
         const registryTools = new Set(this.deps.registry.list().map((t) => t.name));
         const resolved = this.resolveChild(def, parent, registryTools);
         const childModel = input.model ?? resolved.model ?? parent.model;
-        // Worktree isolation: write-capable children without an explicit cwd get
-        // their own worktree; readonly agents keep the parent cwd. A
-        // write-capable spawn outside a git repo is rejected outright.
+        // Worktree isolation: write-capable children get their own worktree —
+        // including when the spawn carries an explicit cwd (the worktree is
+        // then rooted at the resolved explicit cwd, which containment above
+        // already pinned inside the parent). Readonly agents keep the resolved
+        // cwd with no worktree. A write-capable spawn outside a git repo is
+        // rejected outright.
         const writeCapable = [...resolved.allowed].some((t) => DEFAULT_WRITE_TOOLS.has(t));
         let childCwd = baseCwd;
         let worktree;
         let repoCwd;
-        if (!resolved.readonly && writeCapable && !input.cwd) {
+        if (!resolved.readonly && writeCapable) {
             const isRepo = await ensureGitRepo(baseCwd).catch(() => false);
             if (!isRepo) {
                 return {
@@ -285,6 +327,11 @@ export class AgentOrchestrator {
             maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
             signal: record.abortController.signal,
             nonInteractive: true,
+            // Mid-life progress: mirror each finished tool call as one
+            // `subtask.progress` bus event (see createSubtaskProgressEmitter).
+            // Process-isolated children don't run this closure — only the
+            // in-process path reports mid-life progress.
+            onEvent: createSubtaskProgressEmitter({ taskId: record.id, sessionId: this.sessionId }),
             // Grandchildren: only children that canSpawn receive the bridge —
             // otherwise tools see NO_ORCHESTRATOR as before.
             ...(resolved.canSpawn ? { agentBridge: this.bridgeFor(childRef) } : {}),

package/dist/agent/retry.js

@@ -17,6 +17,7 @@
  *
  * The default policy matches the L6 plan: 5 attempts, 500ms base, 8s cap.
  */
+import { acquireStreamSlot, noteRateLimited } from './stream-budget.js';
 export const DEFAULT_RETRY = {
     maxAttempts: 5,
     baseMs: 500,
@@ -88,6 +89,28 @@ export function computeBackoff(attempt, baseMs, maxMs) {
     const jitter = exp * 0.25 * (Math.random() * 2 - 1);
     return Math.max(0, Math.floor(exp + jitter));
 }
+/**
+ * True when a retryable error event carries a 429 rate-limit signal.
+ * Checks the `status` field first, then `code`; accepts numeric values
+ * and `'429'` substrings (e.g. `'429'`, `'HTTP_429'`).
+ */
+function isRateLimitedError(ev) {
+    if (ev.kind !== 'error')
+        return false;
+    const rec = ev;
+    for (const key of ['status', 'code']) {
+        const value = rec[key];
+        if (typeof value === 'string' && value.includes('429'))
+            return true;
+        if (typeof value === 'number' && String(value).includes('429'))
+            return true;
+    }
+    return false;
+}
+function rateLimitDelayMs(ev) {
+    const raw = ev['retryAfterMs'];
+    return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
 export function retryingAdapter(inner, opts = {}) {
     const cfg = { ...DEFAULT_RETRY, ...opts };
     const sleep = opts.sleep ?? defaultSleep;
@@ -129,20 +152,39 @@ export function retryingAdapter(inner, opts = {}) {
                 opts.onAttempt?.(attempt);
                 if (effectiveSignal?.aborted)
                     return;
+                // Rate-limit scheduler: hold one stream slot for the duration of
+                // this attempt's inner.stream consumption. Abort while queued ends
+                // the stream promptly with no inner call.
+                let release;
                 let sawRetryable = false;
                 let lastError = null;
-                for await (const ev of streamWithAbort(inner.stream(attemptReq), effectiveSignal)) {
-                    if (effectiveSignal?.aborted)
+                try {
+                    try {
+                        release = await acquireStreamSlot(effectiveSignal);
+                    }
+                    catch {
                         return;
-                    if (ev.kind === 'error' && ev.retryable) {
-                        // Buffer the retryable error; don't yield it yet. We'll either
-                        // re-issue (and the caller will never see the error) or, on
-                        // final attempt, yield it as the terminal error.
-                        sawRetryable = true;
-                        lastError = ev;
-                        break; // stop consuming; the stream is dead on retryable errors.
                     }
-                    yield ev;
+                    for await (const ev of streamWithAbort(inner.stream(attemptReq), effectiveSignal)) {
+                        if (effectiveSignal?.aborted)
+                            return;
+                        if (ev.kind === 'error' && ev.retryable) {
+                            // Adaptive throttling: a 429 collapses the global stream cap
+                            // to 1 for retryAfterMs (or 60s) — see stream-budget.ts.
+                            if (isRateLimitedError(ev))
+                                noteRateLimited(rateLimitDelayMs(ev));
+                            // Buffer the retryable error; don't yield it yet. We'll either
+                            // re-issue (and the caller will never see the error) or, on
+                            // final attempt, yield it as the terminal error.
+                            sawRetryable = true;
+                            lastError = ev;
+                            break; // stop consuming; the stream is dead on retryable errors.
+                        }
+                        yield ev;
+                    }
+                }
+                finally {
+                    release?.();
                 }
                 if (!sawRetryable)
                     return; // success or non-retryable error — done.

package/dist/agent/runtime.d.ts

@@ -31,6 +31,13 @@ export type VerifyMode = typeof import('../verification/engine.js') extends {
 } ? V : 'strict' | 'advisory' | 'off';
 export interface RuntimeDeps {
     adapter: ProviderAdapter;
+    /**
+     * Ordered failover adapters (L15). When the active adapter ends a step
+     * with a terminal provider error, the runtime swaps to the next entry
+     * and re-issues the step (bounded by chain length, never loops).
+     * Optional — single-adapter callers behave exactly as before.
+     */
+    failoverAdapters?: ProviderAdapter[];
     registry: ToolRegistry;
     policy: PolicyEngine;
     approval: ApprovalPrompt;
@@ -226,6 +233,22 @@ export type RuntimeEvent = {
 } | {
     kind: 'checkpoint_saved';
     sessionId: string;
+} | {
+    kind: 'status';
+    message: string;
+} | {
+    kind: 'budget_warning';
+    ratio: number;
+    threshold: number;
+} | {
+    kind: 'provider_failover';
+    from: string;
+    to: string;
+    reason: string;
+} | {
+    kind: 'model_override';
+    requested: string;
+    effective: string;
 };
 export interface RunResult {
     status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';
@@ -264,7 +287,18 @@ export declare function toolDefinitions(registry: ToolRegistry): ToolDefinition[
 export declare function estimateCost(model: string, usage: {
     input: number;
     output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
 }): number;
+/**
+ * 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 declare const MAX_PARALLEL_TOOLS = 8;
+/** Progressive budget-warning thresholds (fraction of maxCost), fired once each per run. */
+export declare const BUDGET_WARNING_THRESHOLDS: readonly [0.4, 0.7, 0.9];
 /** Run the autonomous loop. */
 export declare function run(opts: RunOptions, deps: RuntimeDeps): Promise<RunResult>;
 export declare function defaultSystemPrompt(ctx: {

package/dist/agent/runtime.js

@@ -23,11 +23,12 @@ 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 { 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);
@@ -42,18 +43,30 @@ export function toolDefinitions(registry) {
         inputSchema: t.function.parameters,
     }));
 }
-// BUG-005: Model-aware cost estimation, single-sourced from the
+// 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.
+// 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 { input: inRate, output: outRate } = ratesFor(model);
-    return (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
+    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,
@@ -90,6 +103,18 @@ 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 = '';
@@ -120,6 +145,27 @@ export async function run(opts, deps) {
     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;
@@ -140,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) => {
@@ -270,7 +320,7 @@ export async function run(opts, deps) {
             ...(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.
@@ -279,6 +329,12 @@ export async function run(opts, deps) {
         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;
@@ -318,6 +374,7 @@ export async function run(opts, deps) {
                         ...(usage.cacheRead !== undefined ? { cacheRead: usage.cacheRead } : {}),
                         ...(usage.cacheWrite !== undefined ? { cacheWrite: usage.cacheWrite } : {}),
                     });
+                    checkBudgetWarnings();
                 }
                 else {
                     // Providers that omit usage (Ollama, vLLM, proxies): estimate from
@@ -329,6 +386,7 @@ export async function run(opts, deps) {
                     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') {
@@ -357,6 +415,24 @@ export async function run(opts, deps) {
                     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 {
@@ -386,6 +462,19 @@ export async function run(opts, deps) {
             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
@@ -478,7 +567,8 @@ export async function run(opts, deps) {
                     emit?.({ kind: 'verification_started', command: advisoryCmd });
                     let advisoryResult;
                     try {
-                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs });
+                        // 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);
@@ -557,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) {
@@ -568,7 +658,7 @@ 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;
                     }
@@ -787,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);
@@ -874,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) => {
@@ -897,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);