klyro 1.0.5 → 1.0.7

package/dist/agent/runtime.js

@@ -23,14 +23,15 @@ import { verify, diagnosticForModel } from '../verification/engine.js';
 import { detectVerifyCommand } from '../verification/auto.js';
 import { ensureBaseline, getBaseline } from '../verification/baseline.js';
 import { compressTranscript, totalTokens, calibrateEstimate, transcriptCharLength } from '../context/tokenizer.js';
-import { capForModel } from '../context/accounting.js';
+import { capForModel, RESERVE_OUTPUT_TOKENS } from '../context/accounting.js';
+import { shouldRemind, reminderForTodos } from '../context/memory.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 { killAllJobs } from '../tools/shell/background.js';
-import { loadHooks, runHook } from '../cli/hooks.js';
+import { loadHooks, runHook, hooksForEvent } from '../cli/hooks.js';
 /** Normalize either systemPrompt shape into {system, suffix}. */
 export function resolveSystemPrompt(fn, ctx) {
     const r = fn(ctx);
@@ -118,6 +119,7 @@ export async function run(opts, deps) {
         }
     };
     let steps = 0;
+    let lastRemindTurn = 0;
     let toolCallCount = 0;
     let finalText = '';
     let repairs = 0;
@@ -154,16 +156,21 @@ export async function run(opts, deps) {
         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.
+    // file exists, the list is empty and every hook call site is skipped.
+    // --bare skips hooks entirely (deterministic runs).
+    // Tool-event hooks are matched per tool at the call sites below
+    // (hooksForEvent over runHooks); lifecycle events run at their own points.
     let runHooks = [];
-    try {
-        runHooks = loadHooks(opts.cwd);
-    }
-    catch {
-        runHooks = [];
+    if (!opts.bare) {
+        try {
+            runHooks = loadHooks(opts.cwd);
+        }
+        catch {
+            runHooks = [];
+        }
     }
-    const preHooks = runHooks.filter((h) => h.event === 'preToolUse');
-    const postHooks = runHooks.filter((h) => h.event === 'postToolUse');
+    // Tool-event hooks are matched per tool at the call sites below
+    // (hooksForEvent over runHooks); lifecycle events run at their own points.
     // L15 failover chain: the active adapter starts as deps.adapter; each
     // terminal provider error consumes one fallback. Bounded — never loops.
     let activeAdapter = deps.adapter;
@@ -179,6 +186,16 @@ export async function run(opts, deps) {
         bus.emit(ev);
         tracer?.write(ev).catch(() => undefined);
     };
+    // Light audit writer: mirrors policy decisions + tool results into the
+    // chained audit log. Best-effort — audit errors must not break the run.
+    const auditLog = opts.audit?.log;
+    const auditSessionId = opts.audit?.sessionId ?? opts.persist?.sessionId;
+    const writeAudit = (ev) => {
+        if (!auditLog || !auditSessionId)
+            return;
+        // fire-and-forget — the log serializes its own chain internally
+        void auditLog.write(ev).catch(() => undefined);
+    };
     const closeTracer = async () => {
         try {
             await tracer?.close();
@@ -247,11 +264,35 @@ export async function run(opts, deps) {
         // Fire-and-forget initial checkpoint (don't await to block loop start)
         void checkpoint(transcript[transcript.length - 1]);
     }
+    // sessionStart: prerequisite gate. A non-zero exit aborts the run before
+    // step 1 with status 'blocked' (e.g. missing toolchain, dirty tree).
+    {
+        const starters = hooksForEvent(runHooks, 'sessionStart');
+        for (const hook of starters) {
+            let r = null;
+            try {
+                r = await runHook(hook, { toolName: '', input: {} }, { event: 'sessionStart', sessionId, cwd: opts.cwd, task: opts.task });
+            }
+            catch {
+                r = null;
+            }
+            if (r && !r.ok) {
+                const reason = (r.stderr || r.stdout || 'sessionStart hook failed').slice(0, 500);
+                emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'session_blocked', message: reason });
+                await closeTracer();
+                return { status: 'blocked', steps, toolCalls: toolCallCount, finalText: `Blocked by sessionStart hook ${hook.name}: ${reason}`, transcript, hasEdits, usage, repairs, phase: 'blocked' };
+            }
+        }
+    }
     // 5.2 — stuck detection state
     const callHistory = [];
     const fileEditCounts = new Map();
     let stuckTriggers = 0;
     let stuckAbort = false;
+    // Steerable stop: a stop hook's `{"continue":true}` verdict carries one
+    // more turn. Consumed once at the completion point, max 3 per run.
+    let stopCont = null;
+    let stopContUsed = 0;
     outer: while (steps < maxSteps) {
         // 5.1 limits: max-cost, max-time
         if (maxCost !== undefined) {
@@ -282,6 +323,33 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined, phase: 'blocked' };
         }
         steps++;
+        // 8.4 — stale-todo reminder: every 20 turns, re-inject pending plan
+        // items from `.klyro/plans/todos.json` (written by todo_write) so a
+        // long run cannot silently drop its checklist. Best-effort + tiny.
+        if (shouldRemind(steps, lastRemindTurn)) {
+            lastRemindTurn = steps;
+            try {
+                const { readFileSync } = await import('node:fs');
+                const { join } = await import('node:path');
+                const rawTodos = JSON.parse(readFileSync(join(opts.cwd, '.klyro', 'plans', 'todos.json'), 'utf-8'));
+                if (Array.isArray(rawTodos)) {
+                    const planSteps = rawTodos
+                        .filter((t) => typeof t.title === 'string')
+                        .map((t, i) => ({
+                        id: `todo-${i}`,
+                        title: t.title,
+                        status: ['pending', 'in_progress', 'done', 'failed', 'skipped'].includes(t.status) ? t.status : 'pending',
+                    }));
+                    const reminder = reminderForTodos(planSteps);
+                    if (reminder) {
+                        const note = { role: 'user', content: [text(`[system note] ${reminder}`)] };
+                        transcript.push(note);
+                        await checkpoint(note);
+                    }
+                }
+            }
+            catch { /* no todos file — nothing to remind */ }
+        }
         // 5.1 phase transitions (model-narrated)
         if (steps === 1)
             setPhase('understanding');
@@ -304,7 +372,7 @@ export async function run(opts, deps) {
         const systemForBudget = telemetrySuffix ? `${stableSystem}\n\n${telemetrySuffix}` : stableSystem;
         // Window-aware ceiling (was a hardcoded 120k that overflowed 8k local
         // models): size the input budget to the model's context window.
-        const BUDGET = { total: capForModel(opts.model, 4000), reservedOutput: 4000 };
+        const BUDGET = { total: capForModel(opts.model, RESERVE_OUTPUT_TOKENS), reservedOutput: RESERVE_OUTPUT_TOKENS };
         let reqMessages = transcript;
         let reqSystem = stableSystem;
         let reqSuffix = telemetrySuffix;
@@ -410,7 +478,7 @@ export async function run(opts, deps) {
                     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 });
+                        const compacted = compressTranscript(reqSystem, transcript, { total: 30_000, reservedOutput: RESERVE_OUTPUT_TOKENS });
                         if (compacted.messages.length < transcript.length || compacted.dropped > 0) {
                             transcript.splice(0, transcript.length, ...compacted.messages);
                         }
@@ -418,7 +486,7 @@ export async function run(opts, deps) {
                             // 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 });
+                            const smaller = compressTranscript(reqSystem, transcript, { total: halved, reservedOutput: RESERVE_OUTPUT_TOKENS });
                             transcript.splice(0, transcript.length, ...smaller.messages);
                         }
                         tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
@@ -549,6 +617,17 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
+            // Steerable stop: a stop hook asked for one more turn instead of
+            // completing. Consumed once per verdict, max 3 per run.
+            if (stopCont !== null && stopContUsed < 3) {
+                stopContUsed++;
+                const contMsg = { role: 'user', content: [text(`[system note] ${stopCont}`)] };
+                stopCont = null;
+                transcript.push(contMsg);
+                await checkpoint(contMsg);
+                emit?.({ kind: 'step_end', step: steps });
+                continue;
+            }
             if (hadInvalidTool) {
                 // The model attempted a tool call that failed validation; the error is
                 // already a tool_result in the transcript — loop so the model can
@@ -833,39 +912,49 @@ export async function run(opts, deps) {
         // results immediately — gate runs in call order so these stay ordered.
         // Returns true when the call is approved for execution.
         const gateCall = async (call) => {
-            const decision = await deps.policy.evaluate({ name: call.name, input: call.input, permission: deps.registry.get(call.name)?.permission }, { 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
-            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',
-                    content: [
-                        mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: decision.reason }, true),
-                    ],
-                };
-                transcript.push(denyMsg);
-                await checkpoint(denyMsg, { toolCallId: call.id, toolName: call.name, input: call.input, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true });
-                emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output: { error: 'POLICY_DENIED' }, isError: true, latencyMs: 0 });
-                telemetry.recordToolError(call, 'policy_denied');
-                emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true, latencyMs: 0 });
-                return false;
-            }
-            if (decision.action === 'ask') {
+            // Edit-and-retry loop: an `e`dit choice re-validates + re-evaluates
+            // policy on the edited input (bounded to 3 rounds so a user can't be
+            // re-prompted forever). `call.input` is updated in place so the
+            // executed + checkpointed call reflects what was approved.
+            let effectiveInput = call.input;
+            for (let round = 0; round < 3; round++) {
+                const decision = await deps.policy.evaluate({ name: call.name, input: effectiveInput, permission: deps.registry.get(call.name)?.permission }, { 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
+                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 });
+                }
+                writeAudit({ kind: 'policy_decision', sessionId: auditSessionId ?? 'ephemeral', callId: call.id, action: decision.action, ts: Date.now() });
+                if (decision.action === 'deny') {
+                    const denyMsg = {
+                        role: 'tool',
+                        content: [
+                            mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: decision.reason }, true),
+                        ],
+                    };
+                    transcript.push(denyMsg);
+                    await checkpoint(denyMsg, { toolCallId: call.id, toolName: call.name, input: effectiveInput, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true });
+                    emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output: { error: 'POLICY_DENIED' }, isError: true, latencyMs: 0 });
+                    telemetry.recordToolError(call, 'policy_denied');
+                    emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true, latencyMs: 0 });
+                    return false;
+                }
+                if (decision.action === 'allow') {
+                    call.input = effectiveInput;
+                    return true;
+                }
+                // decision.action === 'ask'
                 emitKlyro({ type: 'permission.ask', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, reason: decision.reason });
                 const choice = await deps.approval.ask({
                     toolName: call.name,
                     reason: decision.reason,
-                    summary: summarizeToolCall(call),
-                    input: call.input,
-                    pattern: patternForCall(call.name, call.input),
+                    summary: summarizeToolCall({ ...call, input: effectiveInput }),
+                    input: effectiveInput,
+                    pattern: patternForCall(call.name, effectiveInput),
                 });
-                // Approval UI in TUI handles y/a/A/n/e/? — e edits input, ? explains
                 if (choice === 'deny') {
                     const denyMsg2 = {
                         role: 'tool',
@@ -874,15 +963,49 @@ export async function run(opts, deps) {
                         ],
                     };
                     transcript.push(denyMsg2);
-                    await checkpoint(denyMsg2, { toolCallId: call.id, toolName: call.name, input: call.input, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true });
+                    await checkpoint(denyMsg2, { toolCallId: call.id, toolName: call.name, input: effectiveInput, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true });
                     telemetry.recordToolError(call, 'user_denied');
                     emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true, latencyMs: 0 });
                     return false;
                 }
-                // Handle 'edit' choice: for now treat as allow with edited input (future: re-prompt)
+                if (typeof choice === 'object' && choice.kind === 'edit') {
+                    // Re-validate the edited input against the tool schema before it
+                    // goes anywhere — a malformed edit denies instead of executing.
+                    const tool = deps.registry.get(call.name);
+                    const parsed = tool?.inputSchema.safeParse(choice.editedInput);
+                    if (!parsed || !parsed.success) {
+                        const denyMsg3 = {
+                            role: 'tool',
+                            content: [
+                                mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: 'edited input failed tool schema validation' }, true),
+                            ],
+                        };
+                        transcript.push(denyMsg3);
+                        await checkpoint(denyMsg3, { toolCallId: call.id, toolName: call.name, input: effectiveInput, output: { error: 'POLICY_DENIED', reason: 'edited input invalid' }, isError: true });
+                        telemetry.recordToolError(call, 'edit_invalid');
+                        emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: 'edited input invalid' }, isError: true, latencyMs: 0 });
+                        return false;
+                    }
+                    effectiveInput = parsed.data;
+                    continue; // re-evaluate policy on the edited input
+                }
+                // allow / always / always-persist — approved with (possibly edited) input.
                 repairs++;
+                call.input = effectiveInput;
+                return true;
             }
-            return true;
+            // Edit rounds exhausted without approval — deny rather than loop forever.
+            const denyMsg4 = {
+                role: 'tool',
+                content: [
+                    mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: 'approval rounds exhausted' }, true),
+                ],
+            };
+            transcript.push(denyMsg4);
+            await checkpoint(denyMsg4, { toolCallId: call.id, toolName: call.name, input: effectiveInput, output: { error: 'POLICY_DENIED', reason: 'approval rounds exhausted' }, isError: true });
+            telemetry.recordToolError(call, 'approval_exhausted');
+            emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: 'approval rounds exhausted' }, isError: true, latencyMs: 0 });
+            return false;
         };
         // Execute phase: run the tool with no transcript writes, so concurrent
         // executions can't interleave. A throw here becomes a tool error (an
@@ -890,30 +1013,43 @@ 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) {
+            // Hooks: matching preToolUse hooks run before execution. A non-zero
+            // exit denies the tool with POLICY_DENIED — the real tool never runs.
+            // Matchers scope hooks per tool; stdin carries the structured payload.
+            // A structured JSON verdict wins over the exit code: deny blocks with
+            // its message, allow+context attaches model-visible context.
+            const hookContext = [];
+            const matchingPre = hooksForEvent(runHooks, 'preToolUse', call.name);
+            if (matchingPre.length > 0) {
+                for (const hook of matchingPre) {
                     let exitCode = -1;
                     let detail = '';
+                    let verdict;
                     try {
-                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        const r = await runHook(hook, { toolName: call.name, input: call.input }, { event: 'preToolUse', tool: call.name, input: call.input, sessionId, cwd: opts.cwd });
                         exitCode = r.exitCode;
                         detail = (r.stderr || r.stdout || '').slice(0, 300);
+                        if (r.verdict)
+                            verdict = r.verdict;
                     }
                     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'}`;
+                    if (verdict?.decision === 'deny' || exitCode !== 0) {
+                        const reason = `hook ${hook.name} denied: ${verdict?.message || 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,
+                            hookContext,
                         };
                     }
+                    // Allow verdicts may carry model-visible context (sliced at parse).
+                    if (verdict?.decision !== 'deny' && typeof verdict?.context === 'string' && verdict.context) {
+                        hookContext.push({ hook: hook.name, context: verdict.context });
+                    }
                 }
             }
             let obs;
@@ -924,7 +1060,7 @@ export async function run(opts, deps) {
                 obs = { ok: false, error: { code: 'EXEC_CRASH', message: err instanceof Error ? err.message : String(err) } };
             }
             const latencyMs = Date.now() - t0;
-            return { obs, latencyMs };
+            return { obs, latencyMs, hookContext };
         };
         // 5.2 stuck termination (P0-3): the FIRST detection injects one
         // "change approach" synthetic message for the next model turn; the SECOND
@@ -945,7 +1081,7 @@ export async function run(opts, deps) {
         };
         // Commit phase: fold one execution result into the transcript, in original
         // call order. The only writer — call sequentially, never concurrently.
-        const commitResult = async (call, obs, latencyMs) => {
+        const commitResult = async (call, obs, latencyMs, hookContext = []) => {
             const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
             const toolMsg = {
                 role: 'tool',
@@ -953,6 +1089,16 @@ export async function run(opts, deps) {
             };
             transcript.push(toolMsg);
             await checkpoint(toolMsg, { toolCallId: call.id, toolName: call.name, input: call.input, output, isError: !obs.ok });
+            // Hook-injected context rides as its own user message right after the
+            // tool result (uniform across output shapes — no result surgery).
+            if (hookContext.length > 0) {
+                const note = {
+                    role: 'user',
+                    content: [text(hookContext.map((h) => `[hook ${h.hook} context]\n${h.context}`).join('\n\n'))],
+                };
+                transcript.push(note);
+                await checkpoint(note);
+            }
             if (obs.ok) {
                 telemetry.recordToolCall(call, latencyMs, false);
                 if (call.name === 'write_file' || call.name === 'edit_file' || call.name === 'multi_edit' || call.name === 'apply_patch') {
@@ -975,6 +1121,8 @@ export async function run(opts, deps) {
             }
             emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
             emit?.({ kind: 'tool_result', id: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
+            // Light audit: every executed call completes into the chained log.
+            writeAudit({ kind: 'tool_call_completed', sessionId: auditSessionId ?? 'ephemeral', callId: call.id, isError: !obs.ok, latencyMs, ts: Date.now() });
             if (obs.ok) {
                 const fileChanged = inferFileChanged(call.name, call.input, obs.value);
                 if (fileChanged) {
@@ -1003,12 +1151,13 @@ 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) {
+            // Hooks: matching postToolUse hooks are best-effort — failures warn
+            // on stderr plus a bus event, and never fail the turn.
+            const matchingPost = hooksForEvent(runHooks, 'postToolUse', call.name);
+            if (matchingPost.length > 0) {
+                for (const hook of matchingPost) {
                     try {
-                        const r = await runHook(hook, { toolName: call.name, input: call.input });
+                        const r = await runHook(hook, { toolName: call.name, input: call.input }, { event: 'postToolUse', tool: call.name, input: call.input, sessionId, cwd: opts.cwd });
                         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 {
@@ -1033,8 +1182,8 @@ export async function run(opts, deps) {
         const runOne = async (call) => {
             if (!(await gateCall(call)))
                 return;
-            const { obs, latencyMs } = await execTool(call);
-            await commitResult(call, obs, latencyMs);
+            const { obs, latencyMs, hookContext } = await execTool(call);
+            await commitResult(call, obs, latencyMs, hookContext);
         };
         // 3.5 — parallel when every call is concurrencySafe, sequential otherwise.
         // Gate runs sequentially in both paths (approval UI is one-at-a-time).
@@ -1064,7 +1213,7 @@ export async function run(opts, deps) {
                 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);
+                        await commitResult(approved[i], s.value.obs, s.value.latencyMs, s.value.hookContext);
                     }
                     else {
                         await commitResult(approved[i], { ok: false, error: { code: 'EXEC_CRASH', message: String(s.reason) } }, 0);
@@ -1093,6 +1242,28 @@ export async function run(opts, deps) {
             }
         }
         catch { /* ignore — completions are best-effort visibility */ }
+        // stop hooks: run once per completed step (blocking). A structured
+        // `{"continue": true, "message": ...}` verdict asks for one more turn
+        // instead of completing — consumed at the completion point below,
+        // bounded to 3 continuations per run so a hook can't loop forever.
+        stopCont = null; // fresh verdict per step; stale ones never carry over
+        for (const hook of hooksForEvent(runHooks, 'stop')) {
+            try {
+                const r = await runHook(hook, { toolName: '', input: {} }, { event: 'stop', sessionId, cwd: opts.cwd, step: steps, status: 'open' });
+                if (!r.ok) {
+                    try {
+                        process.stderr.write(`klyro: hooks: stop ${hook.name} failed (exit ${String(r.exitCode)})\n`);
+                    }
+                    catch { /* ignore */ }
+                }
+                else if (r.verdict?.cont === true && stopContUsed < 3) {
+                    stopCont = typeof r.verdict.message === 'string' && r.verdict.message
+                        ? r.verdict.message
+                        : `stop hook ${hook.name} requested continuation`;
+                }
+            }
+            catch { /* ignore — stop hooks never fail the turn */ }
+        }
         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

package/dist/chat.d.ts

@@ -20,6 +20,8 @@ export interface ChatOptions {
 }
 /** Strip a trailing slash so we can append /chat/completions cleanly. */
 export declare function normalizeBaseURL(url: string): string;
+/** True for loopback hostnames (localhost / 127.0.0.0/8 / ::1). */
+export declare function isLoopbackHost(host: string): boolean;
 /**
  * Validate that the base URL is HTTPS (or localhost over HTTP for local LLMs).
  * Refuses to send the bearer token over a plaintext remote connection.
@@ -31,6 +33,14 @@ export declare function normalizeBaseURL(url: string): string;
 export declare function assertSafeBaseURL(url: string, opts?: {
     allowInsecure?: boolean;
 }): void;
+/**
+ * Remote MCP URL guard. Mirrors `assertSafeBaseURL`'s fail-closed posture but
+ * is named for MCP config/transports so callers do not have to import provider
+ * URL text.
+ */
+export declare function assertSafeRemoteURL(url: string, opts?: {
+    allowInsecure?: boolean;
+}): void;
 export declare function chat(prompt: string, system: string, modelOverride?: string, opts?: ChatOptions): Promise<void>;
 /**
  * Parse SSE frames and write text deltas to stdout. Handles

package/dist/chat.js

@@ -18,6 +18,17 @@ const MAX_ERROR_BODY_BYTES = 4_000;
 export function normalizeBaseURL(url) {
     return url.replace(/\/+$/, '');
 }
+/** True for loopback hostnames (localhost / 127.0.0.0/8 / ::1). */
+export function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+    if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h === '0.0.0.0' || h === '::')
+        return true;
+    if (h.startsWith('127.')) {
+        const parts = h.split('.');
+        return parts.length === 4 && parts.every((p) => /^\d+$/.test(p) && Number(p) >= 0 && Number(p) <= 255);
+    }
+    return false;
+}
 /**
  * Validate that the base URL is HTTPS (or localhost over HTTP for local LLMs).
  * Refuses to send the bearer token over a plaintext remote connection.
@@ -41,14 +52,10 @@ export function assertSafeBaseURL(url, opts) {
         if (opts?.allowInsecure === true || process.env.KLYRO_ALLOW_INSECURE === '1')
             return;
         const host = parsed.hostname.toLowerCase();
-        // Allow loopback and private networks without extra flag
-        if (host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0' || host === '::' || host === '[::]')
+        // Allow loopback without flag (shared helper); private LAN ranges keep
+        // the provider-path behavior below.
+        if (isLoopbackHost(host))
             return;
-        if (host.startsWith('127.')) {
-            const parts = host.split('.');
-            if (parts.length === 4 && parts.every((p) => /^\d+$/.test(p) && Number(p) >= 0 && Number(p) <= 255))
-                return;
-        }
         // Private ranges 10/8, 192.168/16, 172.16-31/12
         if (/^10\.\d+\.\d+\.\d+$/.test(host))
             return;
@@ -62,6 +69,31 @@ export function assertSafeBaseURL(url, opts) {
     }
     throw new Error(`Unsupported KLYRO_BASE_URL protocol: ${parsed.protocol}`);
 }
+/**
+ * Remote MCP URL guard. Mirrors `assertSafeBaseURL`'s fail-closed posture but
+ * is named for MCP config/transports so callers do not have to import provider
+ * URL text.
+ */
+export function assertSafeRemoteURL(url, opts) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`invalid remote MCP URL: ${url}`);
+    }
+    if (parsed.protocol === 'https:')
+        return;
+    if (parsed.protocol === 'http:') {
+        if (isLoopbackHost(parsed.hostname))
+            return;
+        if (opts?.allowInsecure === true || process.env.KLYRO_ALLOW_INSECURE === '1')
+            return;
+        throw new Error(`Refusing to connect to remote MCP server over plaintext HTTP to ${parsed.hostname}. ` +
+            `Use https:// or a loopback URL, or set KLYRO_ALLOW_INSECURE=1 for this terminal only (not recommended).`);
+    }
+    throw new Error(`unsupported remote MCP URL protocol: ${parsed.protocol}`);
+}
 export async function chat(prompt, system, modelOverride, opts = {}) {
     const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL ?? 'https://api.openai.com/v1';
     const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY;

package/dist/checkpoints/store.d.ts

@@ -12,6 +12,17 @@
  */
 export declare function snapshot(cwd: string, files: string[]): Promise<string>;
 export declare function listCheckpoints(cwd: string): Promise<string[]>;
+export interface CheckpointInfo {
+    /** 1-based index from the latest (1 = newest, like `undo(n)`). */
+    index: number;
+    id: string;
+    ts: number;
+    files: number;
+}
+/** Numbered snapshot list for `/checkpoints` and the `/rewind` menu. */
+export declare function listCheckpointInfo(cwd: string): Promise<CheckpointInfo[]>;
+/** File paths a snapshot would restore (for `/rewind <n> preview`). */
+export declare function snapshotFiles(cwd: string, id: string): Promise<string[]>;
 export declare function diff(cwd: string, id?: string): Promise<string>;
 export declare function undo(cwd: string, n?: number): Promise<void>;
 export declare function rewind(cwd: string): Promise<void>;

package/dist/checkpoints/store.js

@@ -154,6 +154,38 @@ export async function listCheckpoints(cwd) {
         return [];
     }
 }
+/** Numbered snapshot list for `/checkpoints` and the `/rewind` menu. */
+export async function listCheckpointInfo(cwd) {
+    const ids = await listCheckpoints(cwd);
+    const out = [];
+    for (let i = ids.length - 1; i >= 0; i--) {
+        const id = ids[i];
+        let ts = 0;
+        let files = 0;
+        try {
+            const meta = JSON.parse(await fs.readFile(path.join(ckptDir(cwd), id, '.meta.json'), 'utf-8'));
+            if (typeof meta.ts === 'number')
+                ts = meta.ts;
+            if (Array.isArray(meta.files))
+                files = meta.files.length;
+        }
+        catch { /* best-effort */ }
+        out.push({ index: ids.length - i, id, ts, files });
+    }
+    return out;
+}
+/** File paths a snapshot would restore (for `/rewind <n> preview`). */
+export async function snapshotFiles(cwd, id) {
+    try {
+        const meta = JSON.parse(await fs.readFile(path.join(ckptDir(cwd), id, '.meta.json'), 'utf-8'));
+        const files = Array.isArray(meta.files) ? meta.files : [];
+        const missing = Array.isArray(meta.missing) ? meta.missing.map((f) => `${f} (deleted)`) : [];
+        return [...files, ...missing];
+    }
+    catch {
+        return [];
+    }
+}
 export async function diff(cwd, id) {
     const ckpts = await listCheckpoints(cwd);
     const target = id ?? ckpts[ckpts.length - 1];