klyro 1.0.4 → 1.0.5

package/dist/cli/update.js

@@ -2,10 +2,12 @@
  * klyro update — check registry for newer version, cached 24h.
  * Env KLYRO_NO_UPDATE_CHECK=1 disables.
  *
- * Integrity: before recommending `npm i`, we verify the tarball's SRI hash
- * (sha512) against the registry's recorded `dist.integrity`. An install is
- * only recommended when the download hash matches, so a tampered CDN or
- * MITM registry response can't push a malicious binary to the operator.
+ * Integrity: before recommending `npm i`, we verify the tarball against
+ * BOTH the registry's SRI digest (sha512/sha256) AND the legacy sha1
+ * `dist.shasum` when present — a tampered CDN or MITM registry response
+ * must forge two independent digests to push a malicious binary.
+ * Downgrade protection: a registry `latest` that is not strictly newer
+ * than the running version (semver) is never recommended.
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
@@ -24,6 +26,28 @@ function cachePath() {
     const home = os.homedir() || process.cwd();
     return path.join(home, '.klyro', 'update-cache.json');
 }
+/** Minimal semver compare for `x.y.z[-prerelease]`; null when unparseable. */
+export function compareSemver(a, b) {
+    const pa = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(a.trim());
+    const pb = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(b.trim());
+    if (!pa || !pb)
+        return null;
+    for (const i of [1, 2, 3]) {
+        const d = Number(pa[i]) - Number(pb[i]);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    const ra = pa[4] ?? '';
+    const rb = pb[4] ?? '';
+    if (ra === rb)
+        return 0;
+    // A prerelease is older than the release with the same core.
+    if (ra === '')
+        return 1;
+    if (rb === '')
+        return -1;
+    return ra < rb ? -1 : 1;
+}
 /** SRI string may carry multiple hashes parsable with `pick`; we accept sha512 or sha256. */
 function parseSRI(integrity) {
     if (!integrity)
@@ -49,7 +73,7 @@ async function fetchWithTimeout(url, timeoutMs = FETCH_TIMEOUT_MS) {
         clearTimeout(t);
     }
 }
-/** Download the tarball and confirm its hash equals the registry's SRI digest. */
+/** Download the tarball and confirm it matches the registry's SRI digest AND shasum. */
 async function verifyTarballIntegrity(dist) {
     const sri = parseSRI(dist.integrity);
     const tarball = dist.tarball;
@@ -58,7 +82,15 @@ async function verifyTarballIntegrity(dist) {
     const res = await fetchWithTimeout(tarball, TARBALL_TIMEOUT_MS);
     const buf = Buffer.from(await res.arrayBuffer());
     const actual = createHash(sri.algo).update(buf).digest('base64');
-    return actual === sri.digest;
+    if (actual !== sri.digest)
+        return false;
+    // Second independent digest: legacy sha1 shasum, when the registry sends one.
+    if (typeof dist.shasum === 'string' && /^[0-9a-f]{40}$/i.test(dist.shasum)) {
+        const sha1 = createHash('sha1').update(buf).digest('hex');
+        if (sha1.toLowerCase() !== dist.shasum.toLowerCase())
+            return false;
+    }
+    return true;
 }
 export async function checkForUpdate(current) {
     if (process.env.KLYRO_NO_UPDATE_CHECK === '1')
@@ -78,7 +110,12 @@ export async function checkForUpdate(current) {
         const res = await fetchWithTimeout(`${REGISTRY_BASE}/latest`);
         const json = (await res.json());
         const latest = json.version ?? '';
-        if (latest && latest !== current) {
+        // Downgrade protection: only ever recommend a strictly newer version.
+        // A registry answering with an older-or-equal `latest` (stale mirror,
+        // cache poisoning, downgrade attack) is treated as "no update".
+        const cmp = compareSemver(latest, current);
+        const isNewer = cmp === null ? latest !== current : cmp > 0;
+        if (latest && isNewer) {
             // Verify the tarball's integrity before caching/recommending this version.
             const verRes = await fetchWithTimeout(`${REGISTRY_BASE}/${encodeURIComponent(latest)}`);
             const verJson = (await verRes.json());
@@ -89,6 +126,12 @@ export async function checkForUpdate(current) {
             await fs.writeFile(cache, JSON.stringify({ at: Date.now(), latest }), 'utf-8');
             return latest;
         }
+        if (latest && cmp !== null && cmp <= 0) {
+            // Refresh the negative cache so a poisoned answer isn't re-fetched
+            // every invocation for the next 24h.
+            await fs.mkdir(path.dirname(cache), { recursive: true }).catch(() => undefined);
+            await fs.writeFile(cache, JSON.stringify({ at: Date.now(), latest: current }), 'utf-8').catch(() => undefined);
+        }
     }
     catch {
         // network failure — silent

package/dist/context/accounting.d.ts

@@ -12,5 +12,13 @@ export declare function accounting(system: string | undefined, messages: Message
     reserveOutput?: number;
     toolResultMax?: number;
     compactAt?: number;
+    model?: string;
 }): ContextAccounting;
+/**
+ * Input-token budget for a model: its context window minus the output
+ * reserve, clamped to the legacy 120k ceiling and a 4k usable floor so
+ * tiny windows still function. Unknown models use the registry fallback
+ * window (100k); a missing model name keeps the legacy 120k.
+ */
+export declare function capForModel(model: string | undefined, reserveOutput?: number): number;
 export declare function contextMeter(pct: number): string;

package/dist/context/accounting.js

@@ -3,15 +3,32 @@
  * Live token estimate, ctx%, compactAt, reserveOutput, toolResultMax
  */
 import { totalTokens } from './tokenizer.js';
+import { getModelInfo } from '../providers/model-info.js';
 export function accounting(system, messages, opts = {}) {
-    const cap = opts.cap ?? 120_000;
     const reserveOutput = opts.reserveOutput ?? 16_000;
+    // Window-aware default: the legacy 120k ceiling overflows small-window
+    // models (e.g. 8k local models) and wastes large ones — size to the model.
+    const cap = opts.cap ?? capForModel(opts.model, reserveOutput);
     const toolResultMax = opts.toolResultMax ?? 2000;
     const compactAt = opts.compactAt ?? 0.8;
     const used = totalTokens(system, messages);
     const pct = Math.round((used / cap) * 100);
     return { used, cap, pct, reserveOutput, compactAt, toolResultMax };
 }
+/**
+ * Input-token budget for a model: its context window minus the output
+ * reserve, clamped to the legacy 120k ceiling and a 4k usable floor so
+ * tiny windows still function. Unknown models use the registry fallback
+ * window (100k); a missing model name keeps the legacy 120k.
+ */
+export function capForModel(model, reserveOutput = 16_000) {
+    if (!model)
+        return 120_000;
+    const window = getModelInfo(model).contextWindow;
+    if (!Number.isFinite(window) || window <= 0)
+        return 120_000;
+    return Math.max(4_000, Math.min(120_000, Math.floor(window - reserveOutput)));
+}
 export function contextMeter(pct) {
     const filled = Math.round((pct / 100) * 20);
     return `${'▰'.repeat(filled)}${'▱'.repeat(20 - filled)}`;

package/dist/context/compaction.d.ts

@@ -15,4 +15,5 @@ export declare function compact(messages: Message[], opts: {
     focus?: string;
     checkpointedFiles?: string[];
     summarizeFn?: (prompt: string) => Promise<string>;
+    model?: string;
 }): Promise<CompactionResult>;

package/dist/context/compaction.js

@@ -1,6 +1,7 @@
 import { compressTranscript } from './tokenizer.js';
+import { capForModel } from './accounting.js';
 export async function compact(messages, opts) {
-    const cap = opts.cap ?? 120_000;
+    const cap = opts.cap ?? capForModel(opts.model);
     // (a) elide old tool results
     const elided = compressTranscript(opts.system, messages, { total: cap, reservedOutput: 16_000 });
     if (opts.checkpointedFiles && elided.dropped > 0) {

package/dist/index.js

@@ -56,7 +56,7 @@ async function main() {
         .option('--verbose', 'Verbose output')
         .option('--quiet', 'Suppress non-essential output')
         .option('--json', 'Force JSON output where supported')
-        .option('--yes', 'Auto-approve prompts where possible')
+        .option('--yes', 'Auto-approve commit prompts (scope: `klyro commit` only)')
         .option('--no-color', 'Disable colored output')
         .option('-p, --print <prompt>', 'Headless one-shot prompt (alias for run, --output json for machine)')
         .option('--output-format <fmt>', 'Headless output format: text|json|stream-json (default text)')
@@ -552,16 +552,58 @@ async function main() {
         }
         const rec = await store.get(full);
         const msgs = await store.loadMessages(full);
+        const obs = await store.loadObservations(full);
         const out = file ?? `${full}.export.json`;
-        await (await import('node:fs/promises')).writeFile(out, JSON.stringify({ record: rec, messages: msgs }, null, 2));
+        await (await import('node:fs/promises')).writeFile(out, JSON.stringify({ record: rec, messages: msgs, observations: obs }, null, 2));
         process.stdout.write(`exported ${full} → ${out}\n`);
     });
-    sessions.command('import <file>').description('Import session from file').action(async (file) => {
-        const data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+    sessions.command('import <file>').description('Import session from file (restores record + messages + observations)').action(async (file) => {
+        let data;
+        try {
+            data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+        }
+        catch (err) {
+            process.stderr.write(`klyro: cannot import ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+        const rec = data.record ?? {};
         const { getDefaultSessionStore } = await import('./persistence/session.js');
         const store = getDefaultSessionStore();
-        const rec = await store.create({ cwd: data.record?.cwd ?? process.cwd(), task: data.record?.task ?? 'imported', config: data.record?.config ?? { model: 'imported', maxSteps: 30 } });
-        process.stdout.write(`imported → ${rec.id}\n`);
+        const cfg = (rec.config && typeof rec.config === 'object' ? rec.config : { model: 'imported', maxSteps: 30 });
+        const created = await store.create({ cwd: typeof rec.cwd === 'string' ? rec.cwd : process.cwd(), task: typeof rec.task === 'string' ? rec.task : 'imported', config: cfg });
+        // Restore the transcript — previously this was silently dropped (lossy
+        // import). Messages/observations go through append* so at-rest redaction
+        // still applies. Malformed entries fail loudly instead of half-importing.
+        const d = data;
+        let restored = 0;
+        if (d.messages !== undefined) {
+            if (!Array.isArray(d.messages)) {
+                process.stderr.write(`klyro: import failed: "messages" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            for (const m of d.messages) {
+                if (!m || typeof m !== 'object' || typeof m.role !== 'string' || !('content' in m)) {
+                    process.stderr.write(`klyro: import failed: malformed message entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendMessage(created.id, m);
+                restored++;
+            }
+        }
+        if (d.observations !== undefined) {
+            if (!Array.isArray(d.observations)) {
+                process.stderr.write(`klyro: import failed: "observations" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            for (const o of d.observations) {
+                if (!o || typeof o !== 'object') {
+                    process.stderr.write(`klyro: import failed: malformed observation entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendObservation(created.id, o);
+            }
+        }
+        process.stdout.write(`imported → ${created.id} (${restored} messages restored)\n`);
     });
     sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => {
         const { getDefaultSessionStore, matchSessionIds } = await import('./persistence/session.js');
@@ -612,7 +654,31 @@ async function main() {
             process.stdout.write(`${name} source=${source}${spec?.disabled ? ' disabled' : ''}\n`);
         }
     });
-    mcp.command('add <name> <url>').description('Add MCP server').action(async (name) => { process.stdout.write(`added mcp ${name} (stub)\n`); });
+    mcp.command('add <name> <command> [args...]').description('Add a project MCP server to .mcp.json (stdio command)').action(async (name, command, args) => {
+        const { addProjectServer, projectMcpPath } = await import('./mcp/config.js');
+        try {
+            addProjectServer(process.cwd(), name, { command, ...(args && args.length > 0 ? { args } : {}) });
+            process.stdout.write(`added mcp server "${name}" → ${projectMcpPath(process.cwd())}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp add failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+    });
+    mcp.command('remove <name>').description('Remove a project MCP server from .mcp.json').action(async (name) => {
+        const { removeProjectServer, projectMcpPath } = await import('./mcp/config.js');
+        try {
+            if (!removeProjectServer(process.cwd(), name)) {
+                process.stderr.write(`klyro: mcp server not found in ${projectMcpPath(process.cwd())}: ${name}\n`);
+                process.exit(2);
+            }
+            process.stdout.write(`removed mcp server "${name}"\n`);
+        }
+        catch (err) {
+            process.stderr.write(`klyro: mcp remove failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+    });
     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());
@@ -647,7 +713,11 @@ async function main() {
             catch { /* ignore */ }
         }
     });
-    mcp.command('serve').description('Serve as MCP server').action(async () => { process.stdout.write('klyro mcp serve — exposing tools (stub)\n'); });
+    mcp.command('serve').description('Serve builtin tools as an MCP server over stdio (policy-gated)').action(async () => {
+        const { serveStdio } = await import('./mcp/serve.js');
+        const code = await serveStdio(process.cwd());
+        process.exit(code);
+    });
     // 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') {

package/dist/mcp/config.d.ts

@@ -38,3 +38,10 @@ export declare function expandEnv(value: string): string;
 export declare function loadMcpServers(cwd: string): McpServersConfig;
 /** Servers eligible for connection (configured and not disabled). */
 export declare function enabledServers(cfg: McpServersConfig): Record<string, McpServerSpec>;
+/** Server names are bounded: the registry builds `mcp__<server>__<tool>` (≤64 chars). */
+export declare const MCP_NAME_RE: RegExp;
+export declare function projectMcpPath(cwd: string): string;
+/** Add (or reject duplicates of) a project-level MCP server. Throws on invalid input. */
+export declare function addProjectServer(cwd: string, name: string, spec: unknown): void;
+/** Remove a project-level MCP server. Returns false when absent. */
+export declare function removeProjectServer(cwd: string, name: string): boolean;

package/dist/mcp/config.js

@@ -97,3 +97,48 @@ export function enabledServers(cfg) {
     }
     return out;
 }
+/** Server names are bounded: the registry builds `mcp__<server>__<tool>` (≤64 chars). */
+export const MCP_NAME_RE = /^[A-Za-z0-9_-]{1,20}$/;
+export function projectMcpPath(cwd) {
+    return path.join(cwd, '.mcp.json');
+}
+function readProjectDoc(cwd) {
+    const raw = readJsonFile(projectMcpPath(cwd));
+    const doc = (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {});
+    const servers = normalizeRaw(doc);
+    return { doc, servers: { ...servers } };
+}
+function writeProjectDoc(cwd, doc, servers) {
+    const next = { ...doc };
+    if ('mcpServers' in next)
+        next['mcpServers'] = servers;
+    else
+        next['servers'] = servers;
+    if (Object.keys(next).length === 0)
+        next['mcpServers'] = servers;
+    const tmp = `${projectMcpPath(cwd)}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, projectMcpPath(cwd));
+}
+/** Add (or reject duplicates of) a project-level MCP server. Throws on invalid input. */
+export function addProjectServer(cwd, name, spec) {
+    if (!MCP_NAME_RE.test(name))
+        throw new Error(`invalid server name "${name}" (want 1-20 chars of A-Za-z0-9_-)`);
+    const parsed = McpServerSpecSchema.safeParse(spec);
+    if (!parsed.success)
+        throw new Error(`invalid server spec: ${parsed.error.issues.map((i) => i.message).join('; ')}`);
+    const { doc, servers } = readProjectDoc(cwd);
+    if (name in servers)
+        throw new Error(`server "${name}" already configured in ${projectMcpPath(cwd)} (remove it first)`);
+    servers[name] = parsed.data;
+    writeProjectDoc(cwd, doc, servers);
+}
+/** Remove a project-level MCP server. Returns false when absent. */
+export function removeProjectServer(cwd, name) {
+    const { doc, servers } = readProjectDoc(cwd);
+    if (!(name in servers))
+        return false;
+    delete servers[name];
+    writeProjectDoc(cwd, doc, servers);
+    return true;
+}

package/dist/mcp/registry.js

@@ -11,10 +11,12 @@
  *   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.
+ * Permission class: the runtime passes each tool's `permission` into
+ * `PolicyEngine.evaluate`, and `execute`/`admin` tools with no explicit
+ * allow rule fall through to ask (interactive) or deny (headless). 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.
  *
  * Debug capture: when `KLYRO_MCP_DEBUG=1` is set, every MCP tool success
  * AND error ALSO writes the UNREDACTED raw JSON payload (pre-redaction,

package/dist/mcp/serve.d.ts

@@ -0,0 +1,23 @@
+import { type ToolRegistry } from '../tools/registry.js';
+import type { ToolContext } from '../tools/types.js';
+import { PolicyEngine } from '../policy/engine.js';
+interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: {
+        name?: string;
+        arguments?: unknown;
+    };
+}
+export interface ServeDeps {
+    registry?: ToolRegistry;
+    policy?: PolicyEngine;
+    ctx?: ToolContext;
+}
+export declare function makeServeDeps(cwd: string, overrides?: ServeDeps): Required<ServeDeps>;
+/** Pure request handler — unit-tested without stdio. Returns null for notifications. */
+export declare function handleMcpRequest(deps: Required<ServeDeps>, msg: JsonRpcRequest): Promise<Record<string, unknown> | null>;
+/** Stdio loop: one JSON-RPC message per line on stdin, responses on stdout. */
+export declare function serveStdio(cwd: string): Promise<number>;
+export {};

package/dist/mcp/serve.js

@@ -0,0 +1,111 @@
+/**
+ * `klyro mcp serve` — expose the builtin tool registry as a minimal MCP
+ * server over stdio (newline-delimited JSON-RPC 2.0).
+ *
+ * Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`.
+ * Every call is gated by the PolicyEngine (default config + builtin rules)
+ * in headless mode: `allow` runs, `deny`/`ask` are refused as tool errors
+ * (serve cannot prompt, so nothing privileged runs without an explicit
+ * allow rule) — serving never bypasses policy.
+ */
+import * as readline from 'node:readline';
+import { builtinRegistry } from '../tools/registry.js';
+import { PolicyEngine, builtinRules, DEFAULT_POLICY_CONFIG } from '../policy/engine.js';
+import { readVersion } from '../version.js';
+export function makeServeDeps(cwd, overrides = {}) {
+    return {
+        registry: overrides.registry ?? builtinRegistry(),
+        policy: overrides.policy ?? new PolicyEngine(builtinRules(), DEFAULT_POLICY_CONFIG),
+        ctx: overrides.ctx ?? { cwd, env: process.env, nonInteractive: true },
+    };
+}
+/** Pure request handler — unit-tested without stdio. Returns null for notifications. */
+export async function handleMcpRequest(deps, msg) {
+    const id = msg.id ?? null;
+    if (msg.method === undefined || typeof msg.method !== 'string') {
+        if (id === null || id === undefined)
+            return null;
+        return { jsonrpc: '2.0', id, error: { code: -32600, message: 'Invalid Request' } };
+    }
+    if (id === null || id === undefined)
+        return null; // notification — no response
+    if (msg.method === 'initialize') {
+        return {
+            jsonrpc: '2.0', id,
+            result: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'klyro', version: readVersion() },
+            },
+        };
+    }
+    if (msg.method === 'ping')
+        return { jsonrpc: '2.0', id, result: {} };
+    if (msg.method === 'tools/list') {
+        const schemas = deps.registry.jsonSchemas();
+        return {
+            jsonrpc: '2.0', id,
+            result: {
+                tools: deps.registry.list().map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    inputSchema: schemas[t.name] ?? { type: 'object' },
+                })),
+            },
+        };
+    }
+    if (msg.method === 'tools/call') {
+        const name = msg.params?.name;
+        const args = msg.params?.arguments ?? {};
+        if (typeof name !== 'string' || !deps.registry.get(name)) {
+            return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${String(name)}` } };
+        }
+        const decision = await deps.policy.evaluate({ name, input: (args ?? {}), permission: deps.registry.get(name)?.permission }, { cwd: deps.ctx.cwd, nonInteractive: true });
+        if (decision.action !== 'allow') {
+            return {
+                jsonrpc: '2.0', id,
+                result: {
+                    content: [{ type: 'text', text: `POLICY_DENIED: ${decision.action === 'deny' ? decision.reason ?? 'denied' : 'approval required (non-interactive serve cannot prompt)'}` }],
+                    isError: true,
+                },
+            };
+        }
+        const res = await deps.registry.execute(name, args, deps.ctx);
+        if (!res.ok) {
+            const e = res.error;
+            return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: `${e.code ?? 'ERROR'}: ${e.message ?? ''}` }], isError: true } };
+        }
+        return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: typeof res.value === 'string' ? res.value : JSON.stringify(res.value) }] } };
+    }
+    return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
+}
+/** Stdio loop: one JSON-RPC message per line on stdin, responses on stdout. */
+export async function serveStdio(cwd) {
+    const deps = makeServeDeps(cwd);
+    const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n');
+            continue;
+        }
+        try {
+            const res = await handleMcpRequest(deps, msg);
+            if (res)
+                process.stdout.write(JSON.stringify(res) + '\n');
+        }
+        catch (err) {
+            const id = msg.id ?? null;
+            if (id !== null && id !== undefined) {
+                process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32603, message: err instanceof Error ? err.message : String(err) } }) + '\n');
+            }
+        }
+    }
+    return 0;
+}

package/dist/policy/engine.d.ts

@@ -20,6 +20,13 @@ export interface ToolCallLike {
     name: string;
     /** Parsed tool input. */
     input: Record<string, unknown>;
+    /**
+     * Tool risk class from the registry (`read|edit|execute|admin`).
+     * The runtime always passes this; when present, `execute`/`admin`
+     * tools fall through to ask/deny instead of the legacy default-allow
+     * (see evaluate). Omitted in unit tests → legacy default-allow.
+     */
+    permission?: 'read' | 'edit' | 'execute' | 'admin';
 }
 export interface PolicyContext {
     cwd: string;
@@ -55,7 +62,10 @@ export interface PolicyRule {
 export declare const DEFAULT_POLICY_CONFIG: PolicyConfig;
 /**
  * Compose multiple rules. The first rule to return a Decision wins.
- * If none return a Decision, the default is `allow`.
+ * If none return a Decision, privileged tools (`execute`/`admin`, when
+ * the caller passes `permission`) fall through to ask (interactive) or
+ * deny (headless) instead of allow; everything else defaults to `allow`.
+ * `auto` mode keeps the legacy allow-everything behavior.
  */
 export declare class PolicyEngine {
     private readonly rules;

package/dist/policy/engine.js

@@ -44,7 +44,10 @@ export const DEFAULT_POLICY_CONFIG = {
 };
 /**
  * Compose multiple rules. The first rule to return a Decision wins.
- * If none return a Decision, the default is `allow`.
+ * If none return a Decision, privileged tools (`execute`/`admin`, when
+ * the caller passes `permission`) fall through to ask (interactive) or
+ * deny (headless) instead of allow; everything else defaults to `allow`.
+ * `auto` mode keeps the legacy allow-everything behavior.
  */
 export class PolicyEngine {
     rules;
@@ -116,6 +119,16 @@ export class PolicyEngine {
             if (d)
                 return d;
         }
+        // Privileged-class default: an `execute`/`admin` tool that no rule
+        // explicitly allowed must not run silently. Interactive sessions get
+        // an approval prompt; headless sessions get a denial naming the
+        // escape hatch (an explicit `tool`/`tool(glob)` allow rule).
+        if (ctx.config.mode !== 'auto' && (call.permission === 'execute' || call.permission === 'admin')) {
+            if (ctx.nonInteractive) {
+                return { action: 'deny', reason: `${call.name} is a privileged ${call.permission} tool — pre-approve with an allow rule (e.g. "${call.name}")` };
+            }
+            return { action: 'ask', reason: `${call.name} is a privileged ${call.permission} tool and needs approval` };
+        }
         return { action: 'allow' };
     }
     evaluateGlobRules(call) {

package/dist/policy/secret-redactor.js

@@ -12,7 +12,10 @@ import { Transform } from 'node:stream';
 const PATTERNS = [
     { name: 'aws-key', re: /AKIA[0-9A-Z]{16}/g },
     { name: 'aws-secret', re: /(?:aws_secret_access_key|secret)\s*[:=]\s*[A-Za-z0-9/+=]{40}/gi },
-    { name: 'aws-secret-b64', re: /(?<![A-Za-z0-9/+=])(?=[A-Za-z0-9/+=]*[+/=])[A-Za-z0-9/+=]{40,}={0,2}(?![A-Za-z0-9/+=])/g, },
+    // Long base64-ish runs must BOTH contain a +/= (excludes pure-hex SHAs
+    // and hashes) AND a digit (excludes letter-only words/sentences that
+    // happen to be long). Genuine secrets mix classes; prose rarely does.
+    { name: 'aws-secret-b64', re: /(?<![A-Za-z0-9/+=])(?=[A-Za-z0-9/+=]*[+/=])(?=[A-Za-z0-9/+=]*[0-9])[A-Za-z0-9/+=]{40,}={0,2}(?![A-Za-z0-9/+=])/g, },
     { name: 'pem-block', re: /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g },
     { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{36,255}/g },
     { name: 'slack-token', re: /xox[abprs]-[A-Za-z0-9-]{10,}/g },

package/dist/shared/error-map.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Single mapper unifying the three error dialects:
+ *   - ToolErrorCode  (tools/normalize.ts — per-tool failures)
+ *   - FailureClass   (verification/classify.ts — verify repair classes)
+ *   → KlyroErrorCode (shared/errors.ts — harness-wide + exit codes)
+ *
+ * Type-only imports keep this module cycle-free: it is safe to import
+ * from tools/, verification/, and cli/ alike.
+ */
+import { EXIT_CODE, type KlyroErrorCode } from './errors.js';
+import type { FailureClass } from '../verification/classify.js';
+export { EXIT_CODE };
+export type { KlyroErrorCode };
+/** Map any tool-layer error code to its harness-wide KlyroErrorCode. */
+export declare function toolErrorToKlyroCode(code: string): KlyroErrorCode;
+/** Map a verification failure class to its harness-wide code. */
+export declare function failureClassToKlyroCode(cls: FailureClass): KlyroErrorCode;
+/** Exit code for any mapped error: single entry point for CLI mapping. */
+export declare function exitCodeFor(code: KlyroErrorCode): number;

package/dist/shared/error-map.js

@@ -0,0 +1,58 @@
+/**
+ * Single mapper unifying the three error dialects:
+ *   - ToolErrorCode  (tools/normalize.ts — per-tool failures)
+ *   - FailureClass   (verification/classify.ts — verify repair classes)
+ *   → KlyroErrorCode (shared/errors.ts — harness-wide + exit codes)
+ *
+ * Type-only imports keep this module cycle-free: it is safe to import
+ * from tools/, verification/, and cli/ alike.
+ */
+import { EXIT_CODE } from './errors.js';
+export { EXIT_CODE };
+/** Map any tool-layer error code to its harness-wide KlyroErrorCode. */
+export function toolErrorToKlyroCode(code) {
+    switch (code) {
+        case 'NOT_FOUND':
+        case 'COMMAND_NOT_FOUND':
+        case 'MATCH_NOT_FOUND':
+        case 'UNKNOWN_TOOL':
+            return 'TOOL_NOT_FOUND';
+        case 'PERMISSION_DENIED':
+        case 'COMMAND_DENIED':
+        case 'POLICY_DENIED':
+            return 'TOOL_DENIED';
+        case 'PATH_ESCAPE':
+            return 'PATH_ESCAPE';
+        case 'TIMEOUT':
+            return 'PROVIDER_TIMEOUT';
+        case 'INVALID_INPUT':
+        case 'INVALID_PATCH':
+        case 'HUNK_MISMATCH':
+        case 'MATCH_AMBIGUOUS':
+            return 'CONFIG_INVALID';
+        case 'ABORTED':
+        case 'STALE':
+        case 'EXIT_NONZERO':
+        case 'IO_ERROR':
+        case 'INTERNAL':
+        default:
+            return 'UNKNOWN';
+    }
+}
+/** Map a verification failure class to its harness-wide code. */
+export function failureClassToKlyroCode(cls) {
+    switch (cls) {
+        case 'introduced':
+            return 'VERIFY_FAILED';
+        case 'pre_existing':
+        case 'flaky':
+            // Not the agent's fault — surfaced as advisory, not a hard failure.
+            return 'UNKNOWN';
+        case 'env':
+            return 'CONFIG_INVALID';
+    }
+}
+/** Exit code for any mapped error: single entry point for CLI mapping. */
+export function exitCodeFor(code) {
+    return EXIT_CODE[code] ?? 1;
+}