klyro 1.0.4 → 1.0.6

package/README.md

@@ -26,6 +26,35 @@ node dist/index.js chat "Explain TypeScript in 2 sentences"
 node dist/index.js chat
 ```
 
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success / complete |
+| 1 | Unexpected failure (last-resort handler) |
+| 2 | Usage / config error, policy refusal to commit, unknown command or option |
+| 3 | Config invalid / not found |
+| 4 | Provider error (auth, rate-limit, timeout) |
+| 5 | No final answer from provider |
+| 7 | Stopped: max steps, cost/time limit, or stuck |
+| 8 | Verification failed (or `--require-verify` unsatisfied) |
+| 130 | Aborted (Ctrl+C / Esc×2 / /cancel / SIGINT) |
+
+## Environment
+
+| Variable | Scope |
+|---|---|
+| `KLYRO_BASE_URL`, `KLYRO_API_KEY`, `KLYRO_MODEL`, `KLYRO_PROVIDER` | Provider selection |
+| `KLYRO_CONFIG` / `--config` | Config file override |
+| `KLYRO_YES` / `--yes` | **Commit only** — auto-approves `klyro commit` prompts; nothing else reads it |
+| `KLYRO_NO_UPDATE_CHECK=1` | Disables the 24h update check |
+| `KLYRO_ALLOW_MAIN_PUSH=1` | Per-risk escape for protected-branch push |
+| `KLYRO_CREDENTIALS_INSECURE_OK=1` | Warn (don't refuse) on group-readable credentials |
+| `KLYRO_LSP=0` | Force language tools off |
+| `KLYRO_SYMBOLS=0` | Force `find_symbol` off |
+| `KLYRO_WORKER=0` | Disable subprocess isolation for subagents |
+| `KLYRO_SESSIONS_DIR`, `KLYRO_UPDATE_CACHE`, `KLYRO_CREDENTIALS_FILE` | Relocatable state (tests + power users) |
+
 ## Documentation
 
 | Doc | Purpose |

package/dist/agent/custom-agents.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from './orchestrator.js';
+/** Load custom agents: global first, project wins on id clash. Never throws. */
+export declare function loadCustomAgents(cwd: string): AgentDefinition[];

package/dist/agent/custom-agents.js

@@ -0,0 +1,96 @@
+/**
+ * Custom subagents from markdown files:
+ *   `<cwd>/.klyro/agents/*.md` (project) + `~/.klyro/agents/*.md` (global).
+ * Project wins on id clash (including overriding a builtin).
+ *
+ * Frontmatter fields: name (default: filename), description, tools
+ * (comma/list — omitted inherits parent tools), model, readonly,
+ * canSpawn, maxSteps, maxTokens, maxCost, maxTimeMs, allowedPaths.
+ * The markdown body becomes specialist instructions (`prompt`) prepended
+ * to the delegated task. Unknown tool names are NOT rejected here —
+ * `resolveCapabilities` drops them with reasons at spawn time.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseFrontmatter, parseList, parseBool, parseInt_ } from '../cli/slash/custom.js';
+const AGENT_ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+function readAgentFile(file, source) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const { data, body } = parseFrontmatter(raw);
+    const fallback = path.basename(file, path.extname(file));
+    const id = (data['name'] || fallback).toLowerCase();
+    if (!AGENT_ID_RE.test(id))
+        return null;
+    const description = data['description'] || `Custom agent ${id}`;
+    const def = { id, description };
+    const tools = parseList(data['tools']);
+    if (tools.length > 0)
+        def.allowedTools = tools;
+    if (data['model'])
+        def.model = data['model'];
+    if (data['readonly'] !== undefined && data['readonly'] !== '')
+        def.readonly = parseBool(data['readonly'], false);
+    if (data['canSpawn'] !== undefined && data['canSpawn'] !== '')
+        def.canSpawn = parseBool(data['canSpawn'], false);
+    const maxSteps = parseInt_(data['maxsteps']);
+    if (maxSteps !== undefined)
+        def.maxSteps = maxSteps;
+    const maxTokens = parseInt_(data['maxtokens']);
+    if (maxTokens !== undefined)
+        def.maxTokens = maxTokens;
+    const maxCost = data['maxcost'] !== undefined && data['maxcost'] !== '' ? Number(data['maxcost']) : undefined;
+    if (maxCost !== undefined && Number.isFinite(maxCost) && maxCost > 0)
+        def.maxCost = maxCost;
+    const maxTimeMs = parseInt_(data['maxtimems']);
+    if (maxTimeMs !== undefined)
+        def.maxTimeMs = maxTimeMs;
+    const paths = parseList(data['allowedpaths']);
+    if (paths.length > 0)
+        def.allowedPaths = paths;
+    const prompt = body.trim();
+    if (prompt)
+        def.prompt = prompt;
+    def.source = source;
+    return def;
+}
+function listAgentFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+/** Load custom agents: global first, project wins on id clash. Never throws. */
+export function loadCustomAgents(cwd) {
+    const byId = new Map();
+    try {
+        const home = os.homedir() || process.cwd();
+        for (const f of listAgentFiles(path.join(home, '.klyro', 'agents'))) {
+            const d = readAgentFile(f, 'global');
+            if (d)
+                byId.set(d.id, d);
+        }
+        for (const f of listAgentFiles(path.join(cwd, '.klyro', 'agents'))) {
+            const d = readAgentFile(f, 'project');
+            if (d)
+                byId.set(d.id, d);
+        }
+    }
+    catch {
+        return [...byId.values()];
+    }
+    return [...byId.values()];
+}

package/dist/agent/orchestrator.d.ts

@@ -43,11 +43,17 @@ export interface AgentDefinition {
      * spawn time (`undefined` = no additional constraint).
      */
     allowedPaths?: string[];
+    /**
+     * Specialist instructions (from `.klyro/agents/*.md` body or programmatic
+     * defs). Prepended to the delegated task at spawn time.
+     */
+    prompt?: string;
+    /** Where the definition came from (builtins omit this = 'builtin'). */
+    source?: 'builtin' | 'project' | 'global';
 }
 /** Default agents a model can delegate to. */
 export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
-/** Compact summary returned to the parent — the child's transcript stays separate. */
-export interface ChildSummary {
+/** Compact summary returned to the parent — the child's transcript stays separate. */ export interface ChildSummary {
     taskId: string;
     agentName: string;
     status: TaskStatus;
@@ -158,7 +164,20 @@ export interface OrchestratorOpts {
      * always isolate. Defaults to false.
      */
     isTui?: boolean;
+    /**
+     * Working directory used to discover custom agents
+     * (`.klyro/agents/*.md`). Defaults to `process.cwd()`.
+     */
+    cwd?: string;
 }
+/**
+ * All agents: builtins plus custom `.klyro/agents/*.md` definitions.
+ * Custom ids win on clash (including overriding a builtin) — the override
+ * is surfaced via `source`. No instance needed; used by CLI + spawn paths.
+ */
+export declare function listAllAgents(cwd?: string): AgentDefinition[];
+/** Find one agent by id across builtins + custom files. */
+export declare function findAgent(id: string, cwd?: string): AgentDefinition | undefined;
 /**
  * Build a `subtask.progress` note for one finished tool call.
  * Pure — unit-tested directly (see agent-tools.test.ts).
@@ -182,6 +201,7 @@ export declare class AgentOrchestrator {
     readonly taskManager: TaskManager;
     readonly workerSpawner: WorkerSpawner;
     readonly isTui: boolean;
+    private readonly customCwd;
     /** Per-task spawn metadata: capability drops + worktree placement. */
     private readonly taskMeta;
     /** Finished summaries not yet drained via `drainCompletions`. */

package/dist/agent/orchestrator.js

@@ -19,6 +19,7 @@ import { TaskManager } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
 import { resolveCapabilities, DEFAULT_WRITE_TOOLS, DEFAULT_SPAWN_TOOLS, DEFAULT_DENIED_TOOLS, } from './capabilities.js';
 import { forkChild, workerEntryPath } from './child-worker.js';
+import { loadCustomAgents } from './custom-agents.js';
 import { resolveAndFollowSymlinks } from '../policy/path-guard.js';
 import { ensureGitRepo, createWorktree, mergeWorktree, removeWorktree, deleteBranch, } from './worktree-manager.js';
 /** Concurrency budgets enforced in `spawnAgent` (CONCURRENCY_LIMIT on exceed). */
@@ -70,6 +71,26 @@ export const BUILTIN_AGENTS = [
         allowedTools: ['read_file', 'list_directory', 'glob', 'grep', 'search_files', 'repo_map', 'recent_files'],
     },
 ];
+/**
+ * All agents: builtins plus custom `.klyro/agents/*.md` definitions.
+ * Custom ids win on clash (including overriding a builtin) — the override
+ * is surfaced via `source`. No instance needed; used by CLI + spawn paths.
+ */
+export function listAllAgents(cwd) {
+    const byId = new Map();
+    for (const d of BUILTIN_AGENTS)
+        byId.set(d.id, { ...d, source: 'builtin' });
+    try {
+        for (const d of loadCustomAgents(cwd ?? process.cwd()))
+            byId.set(d.id, d);
+    }
+    catch { /* custom agents are best-effort */ }
+    return [...byId.values()];
+}
+/** Find one agent by id across builtins + custom files. */
+export function findAgent(id, cwd) {
+    return listAllAgents(cwd).find((a) => a.id === id);
+}
 /** Map a runtime `RunResult.status` to a task status. */
 function mapResultStatus(status) {
     switch (status) {
@@ -132,6 +153,7 @@ export class AgentOrchestrator {
     taskManager;
     workerSpawner;
     isTui;
+    customCwd;
     /** Per-task spawn metadata: capability drops + worktree placement. */
     taskMeta = new Map();
     /** Finished summaries not yet drained via `drainCompletions`. */
@@ -142,12 +164,13 @@ export class AgentOrchestrator {
         this.taskManager = opts.taskManager ?? new TaskManager({ sessionId: opts.sessionId });
         this.workerSpawner = opts.workerSpawner ?? new WorkerSpawner();
         this.isTui = opts.isTui ?? false;
+        this.customCwd = opts.cwd;
     }
     listAgents() {
-        return [...BUILTIN_AGENTS];
+        return listAllAgents(this.customCwd);
     }
     getAgent(id) {
-        return BUILTIN_AGENTS.find((a) => a.id === id);
+        return listAllAgents(this.customCwd).find((a) => a.id === id);
     }
     /** Build the bridge the parent's runtime hands to tools. */
     bridgeFor(parent) {
@@ -357,8 +380,11 @@ export class AgentOrchestrator {
             ...(childModel !== undefined ? { model: childModel } : {}),
             ...(resolved.allowedPaths !== undefined ? { allowedPaths: resolved.allowedPaths } : {}),
         };
+        // Specialist instructions from `.klyro/agents/*.md` (or programmatic
+        // defs) ride with the delegated task on both paths below.
+        const childTask = def.prompt ? `${def.prompt}\n\n---\n\n${input.task}` : input.task;
         const childOptions = {
-            task: input.task,
+            task: childTask,
             cwd: childCwd,
             model: childModel ?? 'inherit', // model override must reach the adapter (see runtime)
             maxSteps: def.maxSteps,
@@ -413,7 +439,7 @@ export class AgentOrchestrator {
                     const systemPrompt = sysPrompt.suffix ? `${sysPrompt.system}\n${sysPrompt.suffix}` : sysPrompt.system;
                     const payload = {
                         cwd: childCwd,
-                        task: input.task,
+                        task: childTask,
                         // A concrete provider model must reach the child — 'inherit' only
                         // exists to defer resolution inside the parent's run().
                         model: (childModel ?? parent.model),

package/dist/agent/runtime.d.ts

@@ -85,6 +85,11 @@ export interface RunOptions {
     temperature?: number;
     signal?: AbortSignal;
     nonInteractive: boolean;
+    /**
+     * Bare mode: skip all hooks (load + sessionStart/stop). The caller is
+     * responsible for skipping MCP/persistence/context (see runOnce `bare`).
+     */
+    bare?: boolean;
     /**
      * Optional pre-existing transcript to seed the conversation. When set,
      * the runtime skips the initial `[{role:'user', content:[text(task)]}]`

package/dist/agent/runtime.js

@@ -23,12 +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 { 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 { loadHooks, runHook } from '../cli/hooks.js';
+import { killAllJobs } from '../tools/shell/background.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);
@@ -116,6 +119,7 @@ export async function run(opts, deps) {
         }
     };
     let steps = 0;
+    let lastRemindTurn = 0;
     let toolCallCount = 0;
     let finalText = '';
     let repairs = 0;
@@ -152,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;
@@ -245,6 +254,26 @@ 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();
@@ -267,6 +296,9 @@ export async function run(opts, deps) {
         }
         if (opts.signal?.aborted) {
             emit?.({ kind: 'aborted' });
+            // Abort cascade (fix: background shells must not outlive the run).
+            const killed = killAllJobs();
+            emitKlyro({ type: 'abort', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', reason: killed.length > 0 ? `aborted by operator (${killed.length} background job(s) killed)` : 'aborted by operator' });
             if (store && sessionId) {
                 try {
                     await store.setStatus(sessionId, 'aborted', finalText);
@@ -277,6 +309,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');
@@ -297,7 +356,9 @@ export async function run(opts, deps) {
         // 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 };
+        // 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 };
         let reqMessages = transcript;
         let reqSystem = stableSystem;
         let reqSuffix = telemetrySuffix;
@@ -530,6 +591,8 @@ export async function run(opts, deps) {
         if (opts.signal?.aborted) {
             finalText = textBuf;
             emit?.({ kind: 'aborted' });
+            const killed = killAllJobs();
+            emitKlyro({ type: 'abort', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', reason: killed.length > 0 ? `aborted by operator (${killed.length} background job(s) killed)` : 'aborted by operator' });
             if (store && sessionId) {
                 try {
                     await store.setStatus(sessionId, 'aborted', finalText);
@@ -824,39 +887,48 @@ 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 }, { 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 });
+                }
+                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',
@@ -865,15 +937,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
@@ -881,14 +987,16 @@ 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.
+            const matchingPre = hooksForEvent(runHooks, 'preToolUse', call.name);
+            if (matchingPre.length > 0) {
+                for (const hook of matchingPre) {
                     let exitCode = -1;
                     let detail = '';
                     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);
                     }
@@ -994,12 +1102,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 {
@@ -1084,6 +1193,20 @@ export async function run(opts, deps) {
             }
         }
         catch { /* ignore — completions are best-effort visibility */ }
+        // stop hooks: run once per completed step (blocking, side effects only —
+        // output is logged, never injected into the transcript).
+        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 */ }
+                }
+            }
+            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/checkpoints/store.d.ts

@@ -12,6 +12,15 @@
  */
 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[]>;
 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>;