klyro 1.0.1 → 1.0.2

package/dist/cli/hooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hooks engine (10.2) — preToolUse / postToolUse shell hooks.
+ *
+ * Config files:
+ *   - project: `<cwd>/.klyro/hooks.json`
+ *   - global:  `~/.klyro/hooks.json` (merged; project wins on name clash)
+ *
+ * Schema: `{ hooks: Array<{ name, event, command, timeoutMs? }> }`.
+ *
+ * `loadHooks` never throws — a missing file is `[]`, an invalid file is
+ * `[]` plus a one-time stderr warning per path. `runHook` spawns the
+ * command with `shell: true` (commands are strings, must work on win +
+ * posix), a default 30s timeout, a filtered env, plus `KLYRO_TOOL_NAME`
+ * and `KLYRO_TOOL_INPUT_JSON` for the hook's inspection.
+ */
+import { z } from 'zod';
+export declare const HookSchema: z.ZodObject<{
+    name: z.ZodString;
+    event: z.ZodEnum<{
+        preToolUse: "preToolUse";
+        postToolUse: "postToolUse";
+    }>;
+    command: z.ZodString;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Hook = z.infer<typeof HookSchema>;
+export interface HookResult {
+    ok: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 30000;
+/**
+ * Load hooks for a run. Global first, then project — a project hook with
+ * the same `name` replaces the global one. Never throws.
+ */
+export declare function loadHooks(cwd: string): Hook[];
+export interface HookContext {
+    toolName: string;
+    input: unknown;
+}
+/**
+ * Run one hook. Resolves (never rejects) with the exit code + sliced
+ * output. `ok` is true only when the process exited 0.
+ */
+export declare function runHook(hook: Hook, ctx: HookContext): Promise<HookResult>;

package/dist/cli/hooks.js

@@ -0,0 +1,181 @@
+/**
+ * Hooks engine (10.2) — preToolUse / postToolUse shell hooks.
+ *
+ * Config files:
+ *   - project: `<cwd>/.klyro/hooks.json`
+ *   - global:  `~/.klyro/hooks.json` (merged; project wins on name clash)
+ *
+ * Schema: `{ hooks: Array<{ name, event, command, timeoutMs? }> }`.
+ *
+ * `loadHooks` never throws — a missing file is `[]`, an invalid file is
+ * `[]` plus a one-time stderr warning per path. `runHook` spawns the
+ * command with `shell: true` (commands are strings, must work on win +
+ * posix), a default 30s timeout, a filtered env, plus `KLYRO_TOOL_NAME`
+ * and `KLYRO_TOOL_INPUT_JSON` for the hook's inspection.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { z } from 'zod';
+export const HookSchema = z.object({
+    name: z.string().min(1),
+    event: z.enum(['preToolUse', 'postToolUse']),
+    command: z.string().min(1),
+    timeoutMs: z.number().int().positive().optional(),
+});
+const HooksFileSchema = z.object({
+    hooks: z.array(HookSchema),
+});
+export const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+const MAX_HOOK_OUTPUT_CHARS = 4000;
+/** Paths already warned about (invalid JSON/schema) — warn once per path. */
+const warnedPaths = new Set();
+function warnOnce(filePath, detail) {
+    if (warnedPaths.has(filePath))
+        return;
+    warnedPaths.add(filePath);
+    try {
+        process.stderr.write(`klyro: hooks: ignoring invalid file ${filePath}: ${detail}\n`);
+    }
+    catch { /* ignore */ }
+}
+/** Read + validate one hooks file. Missing → []. Invalid → [] + warn once. */
+function readHooksFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return []; // missing/unreadable — silent, zero-cost fast path stays silent
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        warnOnce(filePath, err instanceof Error ? err.message : String(err));
+        return [];
+    }
+    const checked = HooksFileSchema.safeParse(parsed);
+    if (!checked.success) {
+        const first = checked.error.issues[0];
+        warnOnce(filePath, first ? `${first.path.join('.') || 'hooks'}: ${first.message}` : 'schema mismatch');
+        return [];
+    }
+    return checked.data.hooks;
+}
+function globalHooksPath() {
+    try {
+        return path.join(os.homedir() || process.cwd(), '.klyro', 'hooks.json');
+    }
+    catch {
+        return path.join(process.cwd(), '.klyro', 'hooks.json');
+    }
+}
+/**
+ * Load hooks for a run. Global first, then project — a project hook with
+ * the same `name` replaces the global one. Never throws.
+ */
+export function loadHooks(cwd) {
+    let out = [];
+    try {
+        const byName = new Map();
+        for (const h of readHooksFile(globalHooksPath()))
+            byName.set(h.name, h);
+        const projectFile = path.join(cwd, '.klyro', 'hooks.json');
+        for (const h of readHooksFile(projectFile))
+            byName.set(h.name, h);
+        out = [...byName.values()];
+    }
+    catch {
+        return [];
+    }
+    return out;
+}
+/**
+ * Minimal filtered env for hook children (mirrors the shell_exec policy:
+ * secrets stripped, only safe prefixes pass). Kept local so the hooks
+ * engine never depends on the tool layer at import time.
+ */
+function hookEnv() {
+    const out = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (k.startsWith('KLYRO_') && k.includes('API_KEY'))
+            continue;
+        if (k.includes('SECRET') || k.includes('TOKEN') || k === 'ANTHROPIC_API_KEY' || k === 'OPENAI_API_KEY')
+            continue;
+        if (k.startsWith('PATH') || k.startsWith('HOME') || k.startsWith('USER') ||
+            k.startsWith('SHELL') || k.startsWith('TERM') || k.startsWith('LANG') ||
+            k.startsWith('NODE_') || k.startsWith('NPM_') || k.startsWith('PNPM_') ||
+            k.startsWith('YARN_') || k === 'PWD' || k === 'TMPDIR' || k === 'TEMP' ||
+            k === 'SystemRoot' || k === 'windir' || k === 'PATHEXT' || k === 'OS') {
+            out[k] = v;
+        }
+    }
+    out.PATH = process.env.PATH;
+    return out;
+}
+/**
+ * Run one hook. Resolves (never rejects) with the exit code + sliced
+ * output. `ok` is true only when the process exited 0.
+ */
+export function runHook(hook, ctx) {
+    const timeoutMs = hook.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let env;
+        try {
+            // Filtered env (same policy as shell_exec): secrets stripped, only
+            // safe prefixes pass — plus the hook's own inspection vars below.
+            env = hookEnv();
+        }
+        catch {
+            env = { PATH: process.env.PATH };
+        }
+        env.KLYRO_TOOL_NAME = ctx.toolName;
+        try {
+            env.KLYRO_TOOL_INPUT_JSON = JSON.stringify(ctx.input ?? {}).slice(0, 16_000);
+        }
+        catch {
+            env.KLYRO_TOOL_INPUT_JSON = '{}';
+        }
+        let child;
+        try {
+            child = spawn(hook.command, {
+                cwd: process.cwd(),
+                shell: true,
+                windowsHide: true,
+                timeout: timeoutMs,
+                env,
+            });
+        }
+        catch (err) {
+            resolve({ ok: false, exitCode: -1, stdout: '', stderr: String(err instanceof Error ? err.message : err).slice(0, MAX_HOOK_OUTPUT_CHARS) });
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString();
+            if (stdout.length > MAX_HOOK_OUTPUT_CHARS * 2)
+                stdout = stdout.slice(0, MAX_HOOK_OUTPUT_CHARS * 2);
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+            if (stderr.length > MAX_HOOK_OUTPUT_CHARS * 2)
+                stderr = stderr.slice(0, MAX_HOOK_OUTPUT_CHARS * 2);
+        });
+        child.on('error', (err) => {
+            resolve({ ok: false, exitCode: -1, stdout: stdout.slice(0, MAX_HOOK_OUTPUT_CHARS), stderr: String(err.message ?? err).slice(0, MAX_HOOK_OUTPUT_CHARS) });
+        });
+        child.on('close', (code) => {
+            const exitCode = typeof code === 'number' ? code : -1;
+            resolve({
+                ok: exitCode === 0,
+                exitCode,
+                stdout: stdout.slice(0, MAX_HOOK_OUTPUT_CHARS),
+                stderr: stderr.slice(0, MAX_HOOK_OUTPUT_CHARS),
+            });
+        });
+    });
+}

package/dist/cli/repl.js

@@ -185,6 +185,27 @@ export async function startRepl(opts = {}) {
         },
     });
     let adapter = buildAdapter(currentProvider, currentBaseUrl, currentApiKey);
+    // L15 failover — initial adapter only: extra `providers.failover` entries
+    // become fallback adapters for agent runs in this session. Live
+    // /provider switches rebuild a single adapter (buildAdapter) and bypass
+    // the chain — documented, not a bug.
+    let replFailoverAdapters = [];
+    try {
+        const { resolveProviderChain } = await import('./config.js');
+        const chain = await resolveProviderChain(cwd);
+        for (const entry of chain.slice(1)) {
+            if (!entry.apiKey)
+                continue;
+            try {
+                replFailoverAdapters.push(buildAdapter(entry.provider, entry.baseURL ?? currentBaseUrl, entry.apiKey));
+            }
+            catch { /* skip unbuildable entries */ }
+        }
+        if (replFailoverAdapters.length > 0) {
+            process.stderr.write(`klyro: failover chain: ${replFailoverAdapters.map((b) => b.id).join(' → ')}\n`);
+        }
+    }
+    catch { /* best-effort — single-provider session proceeds */ }
     const ctxBlock = await buildLevel6Context({ cwd });
     let ctxPrefix = ctxBlock.formatted ? `\n\n<context>\n${ctxBlock.formatted}\n</context>` : '';
     // 4.4 KLYRO.md hierarchy (mutable — /reload refreshes). Content is gated
@@ -646,6 +667,19 @@ export async function startRepl(opts = {}) {
         if (isMounted && directHooks)
             directHooks.clearTranscript();
     }
+    // Update nudge (best-effort, cached 24h, silent fail): a single stderr
+    // line when a newer version exists. No prompt, no blocking — the check
+    // itself is fire-and-forget.
+    void (async () => {
+        try {
+            const { checkForUpdate } = await import('./update.js');
+            const cur = readVersion();
+            const latest = await checkForUpdate(cur);
+            if (latest)
+                process.stderr.write(`Update available: ${cur} → ${latest} (klyro update)\n`);
+        }
+        catch { /* silent */ }
+    })();
     app = render(React.createElement(App, {
         initialModel: model,
         maxSteps: currentMaxSteps,
@@ -897,8 +931,14 @@ export async function startRepl(opts = {}) {
                     else if (ev.kind === 'aborted') {
                         queuedStatus({ status: 'aborted' });
                     }
+                    else if (ev.kind === 'model_override') {
+                        queuedAppend({ id: `movr-${Date.now()}`, kind: 'text', text: `[model] override: requested ${ev.requested} → effective ${ev.effective}`, role: 'assistant' });
+                    }
                 },
-            }, { adapter, registry, policy, approval, systemPrompt: systemPromptFn });
+            }, {
+                adapter, registry, policy, approval, systemPrompt: systemPromptFn,
+                ...(replFailoverAdapters.length > 0 ? { failoverAdapters: replFailoverAdapters } : {}),
+            });
             if (result.finalText)
                 lastAssistantText = result.finalText;
             if (result.verification) {

package/dist/cli/run.d.ts

@@ -70,6 +70,12 @@ export interface RunCliOptions {
     agent?: string;
     maxDepth?: number;
 }
+/**
+ * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
+ * within 1500ms of the first forces `process.exit(130)`. The live handler
+ * below owns the timestamp closure; tests exercise only this predicate.
+ */
+export declare function shouldForceExit(lastSigintAt: number | undefined, now: number): boolean;
 export declare function runOnce(opts: RunCliOptions): Promise<number>;
 /** Wrap a system-prompt fn to inject Level-6 context (project map etc.) + KLYRO.md (4.4). */
 export declare function makeRunSystemPrompt(cwd: string, base: SystemPromptFn): Promise<SystemPromptFn>;

package/dist/cli/run.js

@@ -16,6 +16,7 @@ import { run } from '../agent/runtime.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, clonePolicyConfig, PolicyEngine } from '../policy/engine.js';
 import { DenyAllApprovalPrompt } from '../policy/approval.js';
+import { redact } from '../policy/secret-redactor.js';
 import { buildLevel6Context } from '../context/level6.js';
 import { memoryBlock } from '../context/memory.js';
 import { resolveSessionId } from '../persistence/session.js';
@@ -24,6 +25,14 @@ function readEnv(name, fallback) {
     const v = process.env[name];
     return v && v.length > 0 ? v : fallback;
 }
+/**
+ * Double-Ctrl+C detector (pure, exported for tests): the second SIGINT
+ * within 1500ms of the first forces `process.exit(130)`. The live handler
+ * below owns the timestamp closure; tests exercise only this predicate.
+ */
+export function shouldForceExit(lastSigintAt, now) {
+    return lastSigintAt !== undefined && now - lastSigintAt < 1500;
+}
 export async function runOnce(opts) {
     // P0.5 — load <cwd>/.env first so KLYRO_* vars resolve without `export`.
     // Never throws (missing file is a no-op); explicit env wins (no-clobber).
@@ -88,6 +97,36 @@ export async function runOnce(opts) {
             adapter = retryingAdapter(httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 }), { onRetry: onRetryEmit });
         }
     }
+    // L15 provider failover: extra chain entries (after the primary) become
+    // fallback adapters for the runtime. Custom injected adapters (tests)
+    // skip chain wiring. Failures resolving the chain never block the run.
+    let failoverAdapters;
+    if (!opts.adapter) {
+        try {
+            const { resolveProviderChain } = await import('./config.js');
+            const chain = await resolveProviderChain(opts.cwd);
+            const fallbacks = chain.slice(1);
+            if (fallbacks.length > 0) {
+                const built = [];
+                for (const entry of fallbacks) {
+                    if (!entry.apiKey)
+                        continue;
+                    const base = entry.provider === 'anthropic'
+                        ? anthropicAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                        : entry.baseURL
+                            ? httpChatAdapter({ baseURL: entry.baseURL, apiKey: entry.apiKey, timeoutMs: opts.timeoutMs ?? 60_000 })
+                            : null;
+                    if (base)
+                        built.push(retryingAdapter(base, { onRetry: onRetryEmit }));
+                }
+                if (built.length > 0) {
+                    failoverAdapters = built;
+                    stderr.write(`klyro: failover chain: ${built.map((b) => b.id).join(' → ')}\n`);
+                }
+            }
+        }
+        catch { /* best-effort — single-provider run proceeds */ }
+    }
     const registry = builtinRegistry();
     const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
     // Persisted "always allow" patterns apply to one-shot runs too.
@@ -149,6 +188,16 @@ export async function runOnce(opts) {
                 return 2;
             }
             sessionId = full;
+            // M22 resume-lock warning (read-only probe — takeover proceeds anyway).
+            try {
+                const { readSessionLock } = await import('../persistence/store.js');
+                const { getDefaultSessionsDir } = await import('../persistence/session.js');
+                const lock = readSessionLock(opts.sessionsDir ?? getDefaultSessionsDir(), sessionId);
+                if (lock.held && lock.alive) {
+                    stderr.write(`klyro: session ${sessionId.slice(0, 8)} is locked by live pid ${lock.pid ?? '?'} — taking over (proceeding anyway)\n`);
+                }
+            }
+            catch { /* probe is best-effort; never block resume */ }
             const msgs = await store.loadMessages(sessionId);
             // Convert StoredMessage to Message
             initialTranscript = msgs.map((m) => ({ role: m.role, content: m.content }));
@@ -176,7 +225,17 @@ export async function runOnce(opts) {
     // persistence is disabled or the session was never created).
     sessionIdForRetry.id = sessionId ?? 'ephemeral';
     const ac = new AbortController();
+    // Double-Ctrl+C: first press aborts the run; a second press within
+    // 1500ms forces process.exit(130) (shouldForceExit owns the predicate).
+    let lastSigintAt;
     const onSigint = () => {
+        const now = Date.now();
+        if (shouldForceExit(lastSigintAt, now)) {
+            stderr.write('\nklyro: SIGINT twice — forcing exit\n');
+            process.exit(130);
+            return;
+        }
+        lastSigintAt = now;
         stderr.write('\nklyro: SIGINT — aborting\n');
         ac.abort();
     };
@@ -298,8 +357,20 @@ export async function runOnce(opts) {
                     if (output === 'human')
                         stderr.write(`[session ${ev.sessionId.slice(0, 8)} checkpoint]\n`);
                 }
+                else if (ev.kind === 'provider_failover') {
+                    stderr.write(`[failover] ${ev.from} → ${ev.to}: ${ev.reason.slice(0, 200)}\n`);
+                }
+                else if (ev.kind === 'budget_warning') {
+                    stderr.write(`[budget] ${(ev.ratio * 100).toFixed(0)}% of max cost used (threshold ${(ev.threshold * 100).toFixed(0)}%)\n`);
+                }
+                else if (ev.kind === 'model_override') {
+                    stderr.write(`[model] override: requested ${ev.requested} → effective ${ev.effective}\n`);
+                }
             },
-        }, { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt });
+        }, {
+            adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt,
+            ...(failoverAdapters ? { failoverAdapters } : {}),
+        });
     }
     finally {
         doneSigint();
@@ -404,8 +475,10 @@ async function dryRunReport(opts) {
         maxSteps: opts.maxSteps,
         maxTokens: opts.maxTokens,
         temperature: opts.temperature,
-        systemPrompt,
-        task: opts.task,
+        // Secrets must never leak into a printable report: redact both the
+        // assembled system prompt and the task before printing.
+        systemPrompt: redact(systemPrompt),
+        task: redact(opts.task),
         toolCount: registry.list().length,
         toolNames: registry.list().map((t) => t.name),
         policyRules: rules.map((r) => r.name),

package/dist/events/catalog.d.ts

@@ -1,6 +1,15 @@
 /**
  * 3.1 — KlyroEvent catalog (Appendix C)
  * Every observable action in the harness is a typed event.
+ *
+ * Reserved-future members (declared but intentionally unproduced — no
+ * emitter exists yet, so do not treat their absence as a bug):
+ * `subtask.tool_call`, `subtask.tool_result`.
+ * `subtask.progress` IS emitted (throttled: max 1 per child tool call,
+ * in-process children only; process-isolated children don't run the emitter).
+ * The orchestrator otherwise emits started/completed/failed/cancelled/
+ * timed_out/merged only; grep for emitters before assuming one of the
+ * reserved members fires.
  */
 export type KlyroEvent = {
     type: 'session.start';

package/dist/events/catalog.js

@@ -1,5 +1,14 @@
 /**
  * 3.1 — KlyroEvent catalog (Appendix C)
  * Every observable action in the harness is a typed event.
+ *
+ * Reserved-future members (declared but intentionally unproduced — no
+ * emitter exists yet, so do not treat their absence as a bug):
+ * `subtask.tool_call`, `subtask.tool_result`.
+ * `subtask.progress` IS emitted (throttled: max 1 per child tool call,
+ * in-process children only; process-isolated children don't run the emitter).
+ * The orchestrator otherwise emits started/completed/failed/cancelled/
+ * timed_out/merged only; grep for emitters before assuming one of the
+ * reserved members fires.
  */
 export {};

package/dist/index.js

@@ -349,7 +349,7 @@ async function main() {
     });
     program
         .command('chat [prompt]')
-        .description('Legacy streamed chat. Without a prompt, start an interactive REPL.')
+        .description('Legacy streamed chat. Without a prompt, start an interactive REPL. (deprecated: history truncation is approximate; prefer `klyro tui`)')
         .option('-s, --system <text>', 'System message', 'You are a helpful assistant.')
         .option('-m, --model <id>', 'Override the model (default: env KLYRO_MODEL)')
         .option('-t, --timeout <ms>', 'Request timeout in ms (default: env KLYRO_TIMEOUT_MS or 60000)', (v) => parsePositiveInt('-t/--timeout', v))
@@ -613,11 +613,78 @@ async function main() {
         }
     });
     mcp.command('add <name> <url>').description('Add MCP server').action(async (name) => { process.stdout.write(`added mcp ${name} (stub)\n`); });
+    mcp.command('probe <name>').description('Connect to an MCP server (15s timeout), list its tools, print count+names').action(async (name) => {
+        const { loadMcpServers } = await import('./mcp/config.js');
+        const cfg = loadMcpServers(process.cwd());
+        const spec = cfg.servers[name];
+        if (!spec) {
+            process.stderr.write(`klyro: mcp server not found: ${name}\n`);
+            process.exit(2);
+        }
+        const { McpClient } = await import('./mcp/client.js');
+        const client = new McpClient(name, spec);
+        // 15s overall probe budget (connect has its own internal timeout too).
+        const timer = setTimeout(() => {
+            process.stderr.write(`klyro: mcp probe ${name} timed out after 15s\n`);
+            process.exit(2);
+        }, 15_000);
+        try {
+            await client.connect();
+            const tools = await client.listTools();
+            const names = tools.map((t) => t.name);
+            process.stdout.write(`${name}: ${tools.length} tool(s)${names.length > 0 ? `: ${names.join(', ')}` : ''}\n`);
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp probe ${name} failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+        finally {
+            clearTimeout(timer);
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+        }
+    });
     mcp.command('serve').description('Serve as MCP server').action(async () => { process.stdout.write('klyro mcp serve — exposing tools (stub)\n'); });
-    // 10.2 — Hooks / agents
-    program.command('hooks').description('List hooks (10.2)').action(async () => { process.stdout.write('hooks: SessionStart UserPromptSubmit PreToolUse PostToolUse (stub)\n'); });
-    program.command('agents [name]').description('List agents (10.2) or show one agent definition').action(async (name) => {
+    // 10.2 — Hooks: list configured preToolUse/postToolUse hooks.
+    program.command('hooks [cmd]').description('Hooks (10.2): `klyro hooks` or `klyro hooks list` prints configured hooks').action(async (cmd) => {
+        if (cmd && cmd !== 'list') {
+            process.stderr.write(`klyro: unknown hooks command: ${cmd} (usage: klyro hooks [list])\n`);
+            process.exit(2);
+        }
+        const { loadHooks } = await import('./cli/hooks.js');
+        const hooks = loadHooks(process.cwd());
+        if (hooks.length === 0) {
+            process.stdout.write('hooks: none configured (.klyro/hooks.json, ~/.klyro/hooks.json)\n');
+            return;
+        }
+        for (const h of hooks)
+            process.stdout.write(`${h.name} ${h.event} ${h.command}\n`);
+    });
+    program.command('agents [name] [extra...]').description('List agents (10.2), show one, or run: agents run <name> <task...>').action(async (name, extra) => {
         const { BUILTIN_AGENTS } = await import('./agent/orchestrator.js');
+        // `klyro agents run <name> <task...>`: one-shot run under a named agent.
+        if (name === 'run') {
+            const [agentName, ...taskParts] = extra ?? [];
+            if (!agentName || !BUILTIN_AGENTS.some((a) => a.id === agentName)) {
+                process.stderr.write(`klyro: unknown agent: ${agentName ?? '(missing)'} (known: ${BUILTIN_AGENTS.map((a) => a.id).join(', ')})\n`);
+                process.exit(2);
+            }
+            const task = (taskParts ?? []).join(' ').trim();
+            if (!task) {
+                process.stderr.write('klyro: agents run requires a task (usage: klyro agents run <name> <task...>)\n');
+                process.exit(2);
+            }
+            const model = process.env.KLYRO_MODEL;
+            if (!model) {
+                process.stderr.write('klyro: KLYRO_MODEL is not set (or pass --model via klyro run)\n');
+                process.exit(2);
+            }
+            const code = await runOnce({ task, cwd: process.cwd(), model, agent: agentName });
+            process.exit(code);
+        }
         if (!name) {
             for (const a of BUILTIN_AGENTS)
                 process.stdout.write(`${a.id} — ${a.description}\n`);
@@ -642,7 +709,24 @@ async function main() {
         process.stdout.write(lines.join('\n') + '\n');
     });
     // 10.3 — Web / git workflows / SDK
-    program.command('commit').description('Create commit (10.3)').action(async () => { process.stdout.write('commit — conventional message (stub, use /commit)\n'); });
+    program
+        .command('commit')
+        .description('Commit staged changes with a conventional message (verification hooks always run)')
+        .option('--dry-run', 'Print the message + files without committing')
+        .option('--message <msg>', 'Summary for the conventional message (default: update <n> files)')
+        .option('--force-secret', 'Commit even if the staged diff looks like it contains a secret')
+        .action(async (opts) => {
+        const { runCommit } = await import('./cli/commit.js');
+        const globalYes = program.opts().yes ?? process.env.KLYRO_YES === '1';
+        const code = await runCommit({
+            cwd: process.cwd(),
+            yes: !!globalYes,
+            dryRun: !!opts.dryRun,
+            ...(opts.message !== undefined ? { message: opts.message } : {}),
+            forceSecret: !!opts.forceSecret,
+        });
+        process.exit(code);
+    });
     program.command('audit [session]').description('Verify audit chain (13.4)').action(async (session) => {
         if (!session) {
             process.stderr.write('klyro: audit requires a session id (usage: klyro audit <session>)\n');

package/dist/mcp/client.js

@@ -90,7 +90,7 @@ export class McpClient {
                         await this.request('initialize', {
                             protocolVersion: PROTOCOL_VERSION,
                             capabilities: {},
-                            clientInfo: { name: 'klyro', version: '1.0.1' },
+                            clientInfo: { name: 'klyro', version: '1.0.2' },
                         }, timeoutMs);
                         this.notify('notifications/initialized', {});
                         this.connected = true;

package/dist/mcp/registry.d.ts

@@ -1,21 +1,3 @@
-/**
- * P1 — MCP tool registration (r-11-17.md §3.1).
- *
- * Exposes MCP server tools through the {@link ToolRegistry} under
- * `mcp__<server>__<tool>` names. Security properties (non-negotiable):
- *
- *   1. Deny-by-default: `evaluateMcpPolicy` runs BEFORE any client I/O; a
- *      denied tool returns POLICY_DENIED without touching the subprocess.
- *   2. Redact-before-transcript: every success value AND error message passes
- *      through `redact()` before it can reach the model or trace.
- *   3. `requireApproval` servers add an ask-rule to the PolicyEngine so the
- *      runtime loop prompts before executing.
- *
- * Permission class: no code in src consumes `Tool.permission` (it is
- * write-only metadata today), so we pick the most restrictive class,
- * 'admin' — the same class as `spawn_agent`, since MCP tools execute
- * arbitrary external side effects (read/write/network) outside our control.
- */
 import { type McpClientLike } from './client.js';
 import { type McpServerSpec } from './config.js';
 import type { PolicyEngine } from '../policy/engine.js';