klyro 0.1.62 → 0.1.63

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

@@ -8,14 +8,15 @@
  *  1. `system` is a top-level field, not a message with role=system.
  *  2. Tool definitions use `input_schema` not `parameters`, and have no
  *     `type: 'function'` wrapper.
- *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
- *     `input_json_delta` block.
+ *  3. `tool_use_id` becomes our `id`; tool input arrives fragmented across
+ *     `input_json_delta` frames, assembled per content_block index (never
+ *     assumed whole, never silently dropped).
  *
  * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
  */
 import type { Message } from './message.js';
-import type { ProviderAdapter, ToolDefinition } from './provider-adapter.js';
+import type { ProviderAdapter, StreamEvent, ToolDefinition } from './provider-adapter.js';
 export interface AnthropicAdapterOptions {
     baseURL?: string;
     apiKey: string;
@@ -50,17 +51,37 @@ interface AnthropicMessage {
         is_error?: boolean;
     }>;
 }
+interface AnthropicSseEvent {
+    type: string;
+    [key: string]: unknown;
+}
 export declare class AnthropicApiError extends Error {
     readonly status: number;
     readonly body: string;
     constructor(status: number, body: string);
 }
 export declare function anthropicAdapter(opts: AnthropicAdapterOptions): ProviderAdapter;
-/** Match an Anthropic content_block index to the tool_use id we emitted. */
-declare function findToolIdByIndex(index: number | undefined, buffers: Map<string, {
-    name: string;
-    argsJson: string;
-}>, indexToToolId?: Map<number, string>): string | undefined;
+/**
+ * Mutable per-stream assembly state. Blocks are keyed by content_block
+ * index; the tool id is carried inside the block entry. There is no global
+ * "current tool" — concurrent or interleaved blocks stay correctly routed.
+ */
+interface AnthropicStreamState {
+    blocks: Map<number, {
+        id: string;
+        name: string;
+        argsJson: string;
+        open: boolean;
+    }>;
+    /** Fragments for an index with no open block yet (flushed on block start). */
+    orphans: Map<number, string>;
+    thinkingIdx: number | null;
+    usage: {
+        input?: number;
+        output?: number;
+    };
+}
+declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
 declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
 declare function toAnthropicTool(t: ToolDefinition): {
     name: string;
@@ -70,6 +91,6 @@ declare function toAnthropicTool(t: ToolDefinition): {
 export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
-    findToolIdByIndex: typeof findToolIdByIndex;
+    translateSse: typeof translateSse;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -8,8 +8,9 @@
  *  1. `system` is a top-level field, not a message with role=system.
  *  2. Tool definitions use `input_schema` not `parameters`, and have no
  *     `type: 'function'` wrapper.
- *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
- *     `input_json_delta` block.
+ *  3. `tool_use_id` becomes our `id`; tool input arrives fragmented across
+ *     `input_json_delta` frames, assembled per content_block index (never
+ *     assumed whole, never silently dropped).
  *
  * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
@@ -111,12 +112,14 @@ async function* streamAnthropic(req, opts) {
     const reader = resp.body.getReader();
     const decoder = new TextDecoder('utf-8');
     let buf = '';
-    // Track in-progress tool calls so we can emit start/delta/end.
-    const toolBuffers = new Map();
-    // Map content_block index → tool_use id (persists after tool completes to handle late deltas)
-    const indexToToolId = new Map();
-    // Active thinking-block index (Anthropic reasoning channel).
-    const thinkingState = { idx: null };
+    // Per-block assembly keyed by content_block index (tool input IS
+    // fragmented across input_json_delta frames — never assume otherwise).
+    const state = {
+        blocks: new Map(),
+        orphans: new Map(),
+        thinkingIdx: null,
+        usage: {},
+    };
     // message_stop already yields message_end — don't emit a second one at EOF.
     let sawMessageEnd = false;
     try {
@@ -155,7 +158,7 @@ async function* streamAnthropic(req, opts) {
                 catch {
                     continue;
                 }
-                const out = translateSse(e.event, parsed, toolBuffers, indexToToolId, thinkingState);
+                const out = translateSse(e.event, parsed, state);
                 for (const ev of out) {
                     if (ev.kind === 'message_end')
                         sawMessageEnd = true;
@@ -172,23 +175,69 @@ async function* streamAnthropic(req, opts) {
     finally {
         reader.releaseLock();
     }
-    if (!sawMessageEnd)
-        yield { kind: 'message_end', finishReason: 'stop' };
+    // Truncated stream: close open blocks so the runtime finalizes them as
+    // (malformed) structured errors instead of hanging, then terminate.
+    for (const b of state.blocks.values()) {
+        if (b.open) {
+            b.open = false;
+            yield { kind: 'tool_call_end', id: b.id };
+        }
+    }
+    state.blocks.clear();
+    // Fragments that could never be attributed to a tool block are a stream
+    // integrity failure — surface loudly, never silently drop.
+    if (state.orphans.size > 0 && !sawMessageEnd) {
+        const count = [...state.orphans.values()].reduce((n, s) => n + s.length, 0);
+        state.orphans.clear();
+        yield {
+            kind: 'error',
+            code: 'ORPHAN_TOOL_DELTAS',
+            message: `stream ended with ${count} chars of tool input that match no content block`,
+            retryable: false,
+        };
+        return;
+    }
+    state.orphans.clear();
+    if (!sawMessageEnd) {
+        yield {
+            kind: 'message_end',
+            finishReason: 'stop',
+            ...(state.usage.input !== undefined || state.usage.output !== undefined
+                ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                : {}),
+        };
+    }
 }
-function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
+function translateSse(event, parsed, state) {
     const out = [];
     switch (event) {
+        case 'message_start': {
+            const usage = parsed.message?.usage;
+            if (typeof usage?.input_tokens === 'number')
+                state.usage.input = usage.input_tokens;
+            return out;
+        }
+        case 'message_delta': {
+            const usage = parsed.usage;
+            if (typeof usage?.output_tokens === 'number') {
+                state.usage.output = (state.usage.output ?? 0) + usage.output_tokens;
+            }
+            return out;
+        }
         case 'content_block_start': {
             const block = parsed.content_block;
             const idx = parsed.index;
-            if (block?.type === 'tool_use' && block.id && block.name) {
-                toolBuffers.set(block.id, { name: block.name, argsJson: '' });
-                if (idx !== undefined)
-                    indexToToolId.set(idx, block.id);
+            if (block?.type === 'tool_use' && block.id && block.name && idx !== undefined) {
+                // Flush any fragments that arrived before the block start.
+                const stashed = state.orphans.get(idx);
+                state.orphans.delete(idx);
+                state.blocks.set(idx, { id: block.id, name: block.name, argsJson: stashed ?? '', open: true });
                 out.push({ kind: 'tool_call_start', id: block.id, name: block.name });
+                if (stashed)
+                    out.push({ kind: 'tool_call_delta', id: block.id, argsJson: stashed });
             }
-            else if ((block?.type === 'thinking' || block?.type === 'redacted_thinking') && thinking && idx !== undefined) {
-                thinking.idx = idx;
+            else if ((block?.type === 'thinking' || block?.type === 'redacted_thinking') && idx !== undefined) {
+                state.thinkingIdx = idx;
             }
             return out;
         }
@@ -202,31 +251,50 @@ function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
                 out.push({ kind: 'thinking_delta', text: delta.thinking });
             }
             else if (delta?.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
-                const id = findToolIdByIndex(index, toolBuffers, indexToToolId);
-                if (id) {
-                    const buf = toolBuffers.get(id);
-                    if (buf) {
-                        buf.argsJson += delta.partial_json;
-                        out.push({ kind: 'tool_call_delta', id, argsJson: delta.partial_json });
+                const entry = index !== undefined ? state.blocks.get(index) : undefined;
+                if (entry && entry.open) {
+                    entry.argsJson += delta.partial_json;
+                    out.push({ kind: 'tool_call_delta', id: entry.id, argsJson: delta.partial_json });
+                }
+                else if (index !== undefined) {
+                    const open = [...state.blocks.values()].filter((b) => b.open);
+                    if (open.length === 1) {
+                        // Single in-flight tool: attribute here (documented heuristic).
+                        open[0].argsJson += delta.partial_json;
+                        out.push({ kind: 'tool_call_delta', id: open[0].id, argsJson: delta.partial_json });
+                    }
+                    else {
+                        // No safe attribution — stash for a later block start, or
+                        // surface as ORPHAN_TOOL_DELTAS at stream end. Never drop.
+                        state.orphans.set(index, (state.orphans.get(index) ?? '') + delta.partial_json);
                     }
                 }
+                else {
+                    state.orphans.set(-1, (state.orphans.get(-1) ?? '') + delta.partial_json);
+                }
             }
             return out;
         }
         case 'content_block_stop': {
             const index = parsed.index;
-            if (thinking && index !== undefined && index === thinking.idx)
-                thinking.idx = null;
-            const id = findToolIdByIndex(index, toolBuffers, indexToToolId);
-            if (id) {
-                toolBuffers.delete(id);
-                // Keep index mapping for late deltas that may arrive after stop (rare)
-                out.push({ kind: 'tool_call_end', id });
+            if (index !== undefined && index === state.thinkingIdx)
+                state.thinkingIdx = null;
+            const entry = index !== undefined ? state.blocks.get(index) : undefined;
+            if (entry && entry.open) {
+                entry.open = false;
+                state.blocks.delete(index);
+                out.push({ kind: 'tool_call_end', id: entry.id });
             }
             return out;
         }
         case 'message_stop': {
-            out.push({ kind: 'message_end', finishReason: 'stop' });
+            out.push({
+                kind: 'message_end',
+                finishReason: 'stop',
+                ...(state.usage.input !== undefined || state.usage.output !== undefined
+                    ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                    : {}),
+            });
             return out;
         }
         case 'error': {
@@ -243,21 +311,6 @@ function translateSse(event, parsed, toolBuffers, indexToToolId, thinking) {
             return out;
     }
 }
-/** Match an Anthropic content_block index to the tool_use id we emitted. */
-function findToolIdByIndex(index, buffers, indexToToolId) {
-    if (index === undefined)
-        return undefined;
-    if (indexToToolId) {
-        const direct = indexToToolId.get(index);
-        if (direct)
-            return direct;
-    }
-    // Single-buffer fallback: if only one in-flight tool, any delta belongs to it
-    if (buffers.size === 1)
-        return buffers.keys().next().value;
-    // No reliable mapping — drop the delta rather than misroute to wrong tool (prevents _parse_error loops)
-    return undefined;
-}
 function toAnthropicMessages(messages) {
     return messages.map((m) => {
         if (m.role === 'user') {
@@ -320,4 +373,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, findToolIdByIndex };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse };

package/dist/agent/provider-adapter.js

@@ -195,10 +195,41 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buf = '';
-    // Track per-tool-call id by index.
-    const toolIds = new Map();
-    const toolNames = new Map();
+    const blocks = new Map();
     let pendingUsage;
+    // Canonical contract: exactly one terminal event per stream.
+    let terminalEmitted = false;
+    function* emitTerminal(finishReason, usage) {
+        if (terminalEmitted)
+            return;
+        terminalEmitted = true;
+        for (const b of blocks.values()) {
+            if (b.started && !b.ended && b.id) {
+                b.ended = true;
+                yield { kind: 'tool_call_end', id: b.id };
+            }
+        }
+        // Fragments that never gained an identity are surfaced as incomplete
+        // calls (the runtime turns them into structured errors) — never dropped.
+        let incomplete = 0;
+        for (const b of blocks.values()) {
+            if (!b.started && (b.argsJson || b.id || b.name)) {
+                const id = b.id ?? `incomplete_${incomplete++}`;
+                yield { kind: 'tool_call_start', id, name: b.name ?? 'unknown' };
+                if (b.argsJson)
+                    yield { kind: 'tool_call_delta', id, argsJson: b.argsJson };
+                yield { kind: 'tool_call_end', id };
+                b.started = true;
+                b.ended = true;
+            }
+        }
+        const end = { kind: 'message_end' };
+        if (finishReason)
+            end.finishReason = finishReason;
+        if (usage)
+            end.usage = usage;
+        yield end;
+    }
     try {
         while (true) {
             const { value, done } = await reader.read();
@@ -215,7 +246,7 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                         continue;
                     const data = line.slice(5).trim();
                     if (data === '[DONE]') {
-                        yield { kind: 'message_end' };
+                        yield* emitTerminal(undefined, pendingUsage);
                         return;
                     }
                     let chunk;
@@ -248,17 +279,28 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                             yield { kind: 'thinking_delta', text: thinking };
                         }
                         for (const tc of choice.delta.tool_calls ?? []) {
-                            if (tc.id && tc.function?.name) {
-                                toolIds.set(tc.index, tc.id);
-                                toolNames.set(tc.index, tc.function.name);
-                                yield { kind: 'tool_call_start', id: tc.id, name: tc.function.name };
+                            let b = blocks.get(tc.index);
+                            if (!b) {
+                                b = { argsJson: '', started: false, ended: false };
+                                blocks.set(tc.index, b);
                             }
-                            else if (tc.id) {
-                                toolIds.set(tc.index, tc.id);
+                            if (tc.id)
+                                b.id = tc.id;
+                            if (tc.function?.name)
+                                b.name = tc.function.name;
+                            const newArgs = tc.function?.arguments;
+                            if (newArgs)
+                                b.argsJson += newArgs;
+                            if (b.id && b.name && !b.started) {
+                                // Identity arrived (possibly after earlier fragments). Emit
+                                // start, then flush any accumulated args as one delta.
+                                b.started = true;
+                                yield { kind: 'tool_call_start', id: b.id, name: b.name };
+                                if (b.argsJson)
+                                    yield { kind: 'tool_call_delta', id: b.id, argsJson: b.argsJson };
                             }
-                            if (tc.function?.arguments) {
-                                const id = toolIds.get(tc.index) ?? `call_${tc.index}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-                                yield { kind: 'tool_call_delta', id, argsJson: tc.function.arguments };
+                            else if (b.started && b.id && newArgs) {
+                                yield { kind: 'tool_call_delta', id: b.id, argsJson: newArgs };
                             }
                         }
                         if (choice.finish_reason) {
@@ -266,38 +308,19 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
                                 ? { input: chunk.usage.prompt_tokens, output: chunk.usage.completion_tokens }
                                 : undefined);
                             pendingUsage = undefined;
-                            // Clear tool tracking per message to avoid stale ids on next turn
-                            const ids = [...toolIds.values()];
-                            toolIds.clear();
-                            toolNames.clear();
-                            for (const id of ids)
-                                yield { kind: 'tool_call_end', id };
-                            yield { kind: 'message_end', finishReason: choice.finish_reason, usage };
+                            yield* emitTerminal(choice.finish_reason, usage);
                         }
                     }
                 }
             }
         }
-        if (toolIds.size) {
-            for (const id of toolIds.values())
-                yield { kind: 'tool_call_end', id };
-            if (pendingUsage) {
-                yield { kind: 'message_end', usage: pendingUsage };
-            }
-            else {
-                yield { kind: 'message_end' };
-            }
-        }
-        else if (pendingUsage) {
-            yield { kind: 'message_end', usage: pendingUsage };
-        }
-        else {
-            yield { kind: 'message_end' };
-        }
+        yield* emitTerminal(undefined, pendingUsage);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        if (!terminalEmitted) {
+            const msg = err instanceof Error ? err.message : String(err);
+            yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+        }
     }
     finally {
         clearTimeout(timer);

package/dist/agent/runtime.d.ts

@@ -139,6 +139,7 @@ export type RuntimeEvent = {
     kind: 'usage';
     input: number;
     output: number;
+    estimated?: boolean;
 } | {
     kind: 'final_text';
     text: string;
@@ -171,7 +172,7 @@ export type RuntimeEvent = {
     sessionId: string;
 };
 export interface RunResult {
-    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked';
+    status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';
     steps: number;
     toolCalls: number;
     finalText: string;
@@ -181,6 +182,7 @@ export interface RunResult {
     usage: {
         input: number;
         output: number;
+        estimated?: boolean;
     };
     /** Number of policy-driven user prompts the user accepted. */
     repairs?: number;

package/dist/agent/runtime.js

@@ -16,6 +16,7 @@
  */
 import { text, toolUse, toolResult as mkToolResult } from './message.js';
 import { redact } from '../policy/secret-redactor.js';
+import { patternForCall } from '../policy/patterns.js';
 import { RuntimeTelemetry, emptyTelemetryBlock, summarizeToolCall } from '../context/level7.js';
 import * as path from 'node:path';
 import { verify, diagnosticForModel } from '../verification/engine.js';
@@ -173,6 +174,8 @@ export async function run(opts, deps) {
     // 5.2 — stuck detection state
     const callHistory = [];
     const fileEditCounts = new Map();
+    let stuckTriggers = 0;
+    let stuckAbort = false;
     outer: while (steps < maxSteps) {
         // 5.1 limits: max-cost, max-time
         if (maxCost !== undefined) {
@@ -273,6 +276,17 @@ export async function run(opts, deps) {
                     telemetry.recordUsage(ev.usage.input, ev.usage.output);
                     emit?.({ kind: 'usage', input: usage.input, output: usage.output });
                 }
+                else {
+                    // Providers that omit usage (Ollama, vLLM, proxies): estimate from
+                    // the actual request + generated output so cost accounting never
+                    // silently records zero. Marked estimated for the UI/debugging.
+                    const est = estimateTurnUsage(reqSystem, reqMessages, textBuf, pendingToolCalls);
+                    usage.input += est.input;
+                    usage.output += est.output;
+                    usage.estimated = true;
+                    telemetry.recordUsage(est.input, est.output);
+                    emit?.({ kind: 'usage', input: usage.input, output: usage.output, estimated: true });
+                }
             }
             else if (ev.kind === 'error') {
                 telemetry.recordError(`stream_error: ${ev.code}`);
@@ -296,22 +310,47 @@ export async function run(opts, deps) {
                 };
             }
         }
-        // Build the assistant message.
+        // Build the assistant message. Tool calls are finalized here: JSON is
+        // parsed and schema-validated BEFORE policy/execution. Malformed calls
+        // become structured MALFORMED_TOOL_CALL results — garbage arguments must
+        // never reach a real tool.
         const assistantContent = [];
         if (textBuf)
             assistantContent.push(text(textBuf));
         const finalizedCalls = [];
+        let hadInvalidTool = false;
         for (const tc of pendingToolCalls.values()) {
-            let input = {};
-            try {
-                input = JSON.parse(tc.argsJson || '{}');
-            }
-            catch {
-                input = { _parse_error: true, raw: tc.argsJson };
+            const validated = validateFinalizedCall(deps.registry, tc.id, tc.name, tc.argsJson);
+            if (!validated.ok) {
+                hadInvalidTool = true;
+                // Record the model's tool_use (empty input — safe to replay to any
+                // provider) and answer it immediately with a structured error.
+                assistantContent.push(toolUse(tc.id, tc.name, {}));
+                emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input: {} });
+                const errMsg = {
+                    role: 'tool',
+                    content: [mkToolResult(tc.id, tc.name, validated.output, true)],
+                };
+                transcript.push(errMsg);
+                await checkpoint(errMsg, {
+                    toolCallId: tc.id, toolName: tc.name,
+                    input: { raw: redact(tc.argsJson).slice(0, 500) }, output: validated.output, isError: true,
+                });
+                let attempted = {};
+                try {
+                    attempted = JSON.parse(tc.argsJson);
+                }
+                catch {
+                    attempted = {};
+                }
+                telemetry.recordToolError(toolUse(tc.id, tc.name, attempted), validated.code);
+                emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: tc.id, name: tc.name, output: validated.output, isError: true, latencyMs: 0 });
+                emit?.({ kind: 'tool_result', id: tc.id, name: tc.name, output: validated.output, isError: true, latencyMs: 0 });
+                continue;
             }
-            finalizedCalls.push(toolUse(tc.id, tc.name, input));
-            assistantContent.push(toolUse(tc.id, tc.name, input));
-            emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input });
+            finalizedCalls.push(toolUse(tc.id, tc.name, validated.input));
+            assistantContent.push(toolUse(tc.id, tc.name, validated.input));
+            emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input: validated.input });
         }
         const assistantMsg = { role: 'assistant', content: assistantContent };
         transcript.push(assistantMsg);
@@ -332,6 +371,14 @@ export async function run(opts, deps) {
             return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
         }
         if (finalizedCalls.length === 0) {
+            if (hadInvalidTool) {
+                // The model attempted a tool call that failed validation; the error is
+                // already a tool_result in the transcript — loop so the model can
+                // repair next turn instead of treating an answerable error as a
+                // completion. Bounded by maxSteps and stuck detection (P0-3).
+                emit?.({ kind: 'step_end', step: steps });
+                continue;
+            }
             finalText = textBuf;
             // Level 8 — Verification + Autonomous Repair (gated on hasEdits below — pure analysis skips verify)
             const verifyEnabled = opts.verify?.enabled !== false;
@@ -528,8 +575,11 @@ export async function run(opts, deps) {
             sessionId,
         };
         const allSafe = finalizedCalls.length > 1 && finalizedCalls.every((c) => deps.registry.get(c.name)?.isConcurrencySafe !== false);
-        const runOne = async (call) => {
-            // Use per-call handling without continue (runOne is not a loop)
+        // Gate phase: policy decision + approval prompt for one call. Runs
+        // sequentially (approval UI is one-modal-at-a-time). Commits deny/user-deny
+        // 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
@@ -546,7 +596,7 @@ export async function run(opts, deps) {
                 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;
+                return false;
             }
             if (decision.action === 'ask') {
                 emitKlyro({ type: 'permission.ask', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, reason: decision.reason });
@@ -554,6 +604,8 @@ export async function run(opts, deps) {
                     toolName: call.name,
                     reason: decision.reason,
                     summary: summarizeToolCall(call),
+                    input: call.input,
+                    pattern: patternForCall(call.name, call.input),
                 });
                 // Approval UI in TUI handles y/a/A/n/e/? — e edits input, ? explains
                 if (choice === 'deny') {
@@ -567,15 +619,49 @@ export async function run(opts, deps) {
                     await checkpoint(denyMsg2, { toolCallId: call.id, toolName: call.name, input: call.input, 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;
+                    return false;
                 }
                 // Handle 'edit' choice: for now treat as allow with edited input (future: re-prompt)
                 repairs++;
             }
+            return true;
+        };
+        // Execute phase: run the tool with no transcript writes, so concurrent
+        // executions can't interleave. A throw here becomes a tool error (an
+        // executor crash must never kill the step).
+        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 });
-            const obs = await deps.registry.execute(call.name, call.input, toolCtx);
+            let obs;
+            try {
+                obs = await deps.registry.execute(call.name, call.input, toolCtx);
+            }
+            catch (err) {
+                obs = { ok: false, error: { code: 'EXEC_CRASH', message: err instanceof Error ? err.message : String(err) } };
+            }
             const latencyMs = Date.now() - t0;
+            return { obs, latencyMs };
+        };
+        // 5.2 stuck termination (P0-3): the FIRST detection injects one
+        // "change approach" synthetic message for the next model turn; the SECOND
+        // detection aborts the automated loop with a `stuck` status so a repeated
+        // tool loop never burns unbounded tokens. Covers both signals: identical
+        // call ×3 and same-file edited >8×.
+        const markStuck = async (msg) => {
+            stuckTriggers++;
+            emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: msg });
+            if (stuckTriggers === 1) {
+                const note = { role: 'user', content: [text(`[system note] Stuck detected: ${msg}. Stop repeating the same action; change approach.`)] };
+                transcript.push(note);
+                await checkpoint(note);
+            }
+            else {
+                stuckAbort = true;
+            }
+        };
+        // Commit phase: fold one execution result into the transcript, in original
+        // call order. The only writer — call sequentially, never concurrently.
+        const commitResult = async (call, obs, latencyMs) => {
             const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
             const toolMsg = {
                 role: 'tool',
@@ -620,7 +706,7 @@ export async function run(opts, deps) {
                     const cnt = (fileEditCounts.get(fileChanged.path) ?? 0) + 1;
                     fileEditCounts.set(fileChanged.path, cnt);
                     if (cnt > 8) {
-                        emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: `same file edited >8×: ${fileChanged.path}` });
+                        await markStuck(`same file edited >8×: ${fileChanged.path}`);
                     }
                 }
             }
@@ -631,23 +717,42 @@ export async function run(opts, deps) {
                 callHistory.shift();
             const last3 = callHistory.slice(-3);
             if (last3.length === 3 && last3[0] === last3[1] && last3[1] === last3[2]) {
-                emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'stuck', message: `identical call ×3: ${sig}` });
-                // Inject system note for next turn
-                const note = { role: 'user', content: [text(`[system note] Stuck detected: identical call ×3: ${sig}. Try a different approach.`)] };
-                transcript.push(note);
-                await checkpoint(note);
+                await markStuck(`identical call ×3: ${sig}`);
             }
         };
-        // 3.5 — parallel if all concurrencySafe, sequential otherwise
-        // BUG-002: preserve call order — run sequentially even when allSafe to avoid out-of-order transcript
-        // Parallel execution previously pushed tool_results out of order via Promise.all
+        // Sequential path: gate → execute → commit per call, in order.
+        const runOne = async (call) => {
+            if (!(await gateCall(call)))
+                return;
+            const { obs, latencyMs } = await execTool(call);
+            await commitResult(call, obs, latencyMs);
+        };
+        // 3.5 — parallel when every call is concurrencySafe, sequential otherwise.
+        // Gate runs sequentially in both paths (approval UI is one-at-a-time).
+        // Parallel path executes concurrently but commits in original call order,
+        // so the transcript reads exactly as if the calls ran in order (this is
+        // what the old BUG-002 sequential fallback was protecting).
         if (allSafe) {
+            const approved = [];
             for (const call of finalizedCalls) {
                 toolCallCount++;
-                await runOne(call);
+                if (await gateCall(call))
+                    approved.push(call);
                 if (opts.signal?.aborted)
                     break;
             }
+            if (approved.length > 0 && !opts.signal?.aborted) {
+                const settled = await Promise.allSettled(approved.map((c) => execTool(c)));
+                for (let i = 0; i < approved.length; i++) {
+                    const s = settled[i];
+                    if (s.status === 'fulfilled') {
+                        await commitResult(approved[i], s.value.obs, s.value.latencyMs);
+                    }
+                    else {
+                        await commitResult(approved[i], { ok: false, error: { code: 'EXEC_CRASH', message: String(s.reason) } }, 0);
+                    }
+                }
+            }
         }
         else {
             for (const call of finalizedCalls) {
@@ -666,6 +771,9 @@ export async function run(opts, deps) {
             }
             catch { /* ignore */ }
         }
+        // 5.2 — terminate the automated loop once stuck recurs after the note
+        if (stuckAbort)
+            break;
     }
     if (opts.signal?.aborted) {
         emit?.({ kind: 'aborted' });
@@ -678,6 +786,18 @@ export async function run(opts, deps) {
         await closeTracer();
         return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
     }
+    // 5.2 — stuck termination (P0-3): bounded stop instead of unbounded token burn.
+    if (stuckAbort) {
+        emit?.({ kind: 'final_text', text: finalText });
+        if (store && sessionId) {
+            try {
+                await store.setStatus(sessionId, 'stuck', finalText);
+            }
+            catch { /* ignore */ }
+        }
+        await closeTracer();
+        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+    }
     emit?.({ kind: 'final_text', text: finalText });
     if (store && sessionId) {
         try {
@@ -688,6 +808,88 @@ export async function run(opts, deps) {
     await closeTracer();
     return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
 }
+/**
+ * Estimate usage for a turn whose provider omitted it (Ollama, vLLM,
+ * proxies). Input is measured from the actual request via the tokenizer;
+ * output is a chars/4 heuristic over generated text + tool arguments.
+ */
+function estimateTurnUsage(system, messages, textOut, toolCalls) {
+    let argsChars = 0;
+    for (const tc of toolCalls.values())
+        argsChars += tc.argsJson.length;
+    return {
+        input: totalTokens(system, messages),
+        output: Math.max(1, Math.ceil((textOut.length + argsChars) / 4)),
+    };
+}
+/**
+ * Validate one assembled tool call before it reaches policy or execution.
+ * Returns the parsed+schema-validated input, or a structured error output
+ * (MALFORMED_TOOL_CALL / UNKNOWN_TOOL) that the runtime records as a tool
+ * result without executing anything.
+ */
+function validateFinalizedCall(registry, id, name, argsJson) {
+    void id;
+    let parsed = {};
+    if (argsJson.trim()) {
+        try {
+            parsed = JSON.parse(argsJson);
+        }
+        catch {
+            return {
+                ok: false,
+                code: 'MALFORMED_TOOL_CALL',
+                output: {
+                    code: 'MALFORMED_TOOL_CALL',
+                    tool: name,
+                    message: 'Tool arguments were incomplete or invalid JSON. Re-issue the call with complete arguments.',
+                    retryable: true,
+                },
+            };
+        }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            code: 'MALFORMED_TOOL_CALL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: 'Tool arguments must be a JSON object. Re-issue the call with complete arguments.',
+                retryable: true,
+            },
+        };
+    }
+    const tool = registry.get(name);
+    if (!tool) {
+        return {
+            ok: false,
+            code: 'UNKNOWN_TOOL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: `Unknown tool "${name}". Use one of the available tools.`,
+                retryable: true,
+            },
+        };
+    }
+    const checked = tool.inputSchema.safeParse(parsed);
+    if (!checked.success) {
+        const first = checked.error.issues[0];
+        const detail = first ? ` (${first.path.join('.') || 'input'}: ${first.message})` : '';
+        return {
+            ok: false,
+            code: 'MALFORMED_TOOL_CALL',
+            output: {
+                code: 'MALFORMED_TOOL_CALL',
+                tool: name,
+                message: `Tool arguments failed validation${detail}. Re-issue the call with correct arguments.`,
+                retryable: true,
+            },
+        };
+    }
+    return { ok: true, input: parsed };
+}
 function redactOutput(v) {
     if (typeof v === 'string')
         return redact(v);

package/dist/cli/config.d.ts

@@ -34,6 +34,27 @@ declare function parseValue(raw: string): unknown;
 export declare function loadConfig(): Promise<Record<string, unknown>>;
 export declare function loadConfigSync(): Record<string, unknown>;
 export declare function loadMergedConfig(cwd?: string, flags?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export interface PermissionRules {
+    allow: string[];
+    deny: string[];
+    ask: string[];
+}
+/**
+ * Permission glob rules (`tool(glob)` grammar) from the merged config
+ * layers — home settings, project settings, project local. Fed into the
+ * policy engine at startup so persisted "always allow" patterns apply
+ * without re-prompting.
+ */
+export declare function loadPermissionRules(cwd?: string): Promise<PermissionRules>;
+/**
+ * Persist an "always allow" pattern to the home settings file
+ * (~/.klyro/settings.json, honors KLYRO_CONFIG). Returns whether it was
+ * added (false when already present) and the file written.
+ */
+export declare function persistAllowRule(rule: string): Promise<{
+    added: boolean;
+    path: string;
+}>;
 export declare function saveConfig(obj: Record<string, unknown>): Promise<void>;
 export declare function runConfig(args: string[]): Promise<number>;
 export declare const _helpers: {

package/dist/cli/config.js

@@ -320,6 +320,37 @@ export async function loadMergedConfig(cwd = process.cwd(), flags = {}) {
     }
     return merged;
 }
+function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((e) => typeof e === 'string') : [];
+}
+/**
+ * Permission glob rules (`tool(glob)` grammar) from the merged config
+ * layers — home settings, project settings, project local. Fed into the
+ * policy engine at startup so persisted "always allow" patterns apply
+ * without re-prompting.
+ */
+export async function loadPermissionRules(cwd = process.cwd()) {
+    const merged = await loadMergedConfig(cwd, {});
+    return {
+        allow: asStringArray(merged.allow),
+        deny: asStringArray(merged.deny),
+        ask: asStringArray(merged.ask),
+    };
+}
+/**
+ * Persist an "always allow" pattern to the home settings file
+ * (~/.klyro/settings.json, honors KLYRO_CONFIG). Returns whether it was
+ * added (false when already present) and the file written.
+ */
+export async function persistAllowRule(rule) {
+    const cfg = await loadConfig();
+    const allow = asStringArray(cfg.allow);
+    if (allow.includes(rule))
+        return { added: false, path: getConfigPath() };
+    cfg.allow = [...allow, rule];
+    await saveConfig(cfg);
+    return { added: true, path: getConfigPath() };
+}
 export async function saveConfig(obj) {
     const p = getConfigPath();
     await fs.mkdir(path.dirname(p), { recursive: true });

package/dist/cli/repl.js

@@ -16,7 +16,7 @@ import { run } from '../agent/runtime.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, clonePolicyConfig, PolicyEngine } from '../policy/engine.js';
 import { buildLevel6Context } from '../context/level6.js';
-import { DenyAllApprovalPrompt, StdinApprovalPrompt } from '../policy/approval.js';
+import { DenyAllApprovalPrompt, PatternApprovalCache, StdinApprovalPrompt } from '../policy/approval.js';
 import { TuiApprovalBridge } from '../tui/approval.js';
 import { parseUnifiedDiff } from '../tui/diff-parser.js';
 import { parse } from './slash/parser.js';
@@ -72,6 +72,15 @@ export async function startRepl(opts = {}) {
     // Clone: /mode and /sandbox mutate this config — it must never leak into
     // the shared DEFAULT_POLICY_CONFIG across sessions.
     const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
+    // Persisted permission rules (home + project settings layers) — "always"
+    // choices from previous sessions apply without re-prompting.
+    try {
+        const { loadPermissionRules } = await import('./config.js');
+        policy.applyRules(await loadPermissionRules(cwd));
+    }
+    catch {
+        /* ignore — engine defaults stand */
+    }
     const providerKind = inferProviderFromBaseURL(baseUrl);
     // Local Ollama exposes OpenAI-compat but hostname could contain "anthropic"
     // via proxy — don't try anthropic adapter with empty key (would 401).
@@ -105,9 +114,29 @@ export async function startRepl(opts = {}) {
     // App and the runtime so the modal can resolve the runtime's ask().
     const tuiBridge = new TuiApprovalBridge();
     const useTui = opts.forceTty || process.stdin.isTTY;
-    const approval = opts.nonInteractive
+    // Ask-once-per-pattern: session cache + optional persist. `a` records for
+    // the session, `A` additionally appends the pattern to settings and the
+    // live engine (matches the modal's [a] session / [A] always→settings).
+    const approvalBase = opts.nonInteractive
         ? new DenyAllApprovalPrompt()
         : (useTui ? tuiBridge : new StdinApprovalPrompt());
+    const approval = opts.nonInteractive
+        ? approvalBase
+        : new PatternApprovalCache(approvalBase, {
+            onPersist: async (pattern) => {
+                const { persistAllowRule } = await import('./config.js');
+                const res = await persistAllowRule(pattern);
+                policy.addAllow(pattern);
+                queuedAppend({
+                    id: `allow-${Date.now()}`,
+                    kind: 'text',
+                    text: res.added
+                        ? `allowed always: ${pattern} (saved to ${res.path} — revoke by deleting the line)`
+                        : `allowed always: ${pattern} (already in ${res.path})`,
+                    role: 'assistant',
+                });
+            },
+        });
     let inflight = null;
     let lastStatus = null;
     const pendingQueue = [];

package/dist/cli/run.js

@@ -59,6 +59,14 @@ export async function runOnce(opts) {
     }
     const registry = builtinRegistry();
     const policy = new PolicyEngine(builtinRules(), clonePolicyConfig());
+    // Persisted "always allow" patterns apply to one-shot runs too.
+    try {
+        const { loadPermissionRules } = await import('./config.js');
+        policy.applyRules(await loadPermissionRules(opts.cwd));
+    }
+    catch {
+        /* ignore — engine defaults stand */
+    }
     const systemPrompt = await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt);
     // Level 9 — session setup (create or resume)
     const persistEnabled = opts.persist !== false;
@@ -193,6 +201,7 @@ export async function runOnce(opts) {
             aborted: 'aborted',
             no_final: 'aborted',
             verify_failed: 'verify_failed',
+            stuck: 'stuck',
         };
         try {
             await store.setStatus(sessionId, statusMap[result.status] ?? 'complete', result.finalText);

package/dist/persistence/store.d.ts

@@ -9,7 +9,7 @@
  * ~50-task eval suite. v1.0 can swap in SQLite behind the same
  * SessionStore interface.
  */
-export type SessionStatus = 'open' | 'complete' | 'verify_failed' | 'aborted' | 'max_steps';
+export type SessionStatus = 'open' | 'complete' | 'verify_failed' | 'aborted' | 'max_steps' | 'stuck';
 export interface SessionConfig {
     model: string;
     maxSteps: number;

package/dist/policy/approval.d.ts

@@ -5,12 +5,22 @@
  * Non-TTY: returns deny. Callers should treat non-TTY as the default
  * (the user opted out of prompts with `--yes` or pipe input).
  */
-export type ApprovalChoice = 'allow' | 'deny' | 'always';
+export type ApprovalChoice = 
+/** Yes, just this once. */
+'allow' | 'deny'
+/** Yes, and auto-allow this pattern for the rest of the session. */
+ | 'always'
+/** Yes, session-allow AND persist the pattern to settings (survives restarts). */
+ | 'always-persist';
 export interface ApprovalRequest {
     toolName: string;
     reason: string;
     /** Best-effort summary of the call (command or path). */
     summary: string;
+    /** Raw tool input — used to derive the approval pattern when `pattern` is absent. */
+    input?: Record<string, unknown>;
+    /** Pre-derived approval pattern (`tool(glob)` grammar). */
+    pattern?: string;
 }
 export interface ApprovalPrompt {
     ask(req: ApprovalRequest): Promise<ApprovalChoice>;
@@ -24,12 +34,23 @@ export declare class DenyAllApprovalPrompt implements ApprovalPrompt {
     ask(_req: ApprovalRequest): Promise<ApprovalChoice>;
 }
 /**
- * In-memory allowlist: tracks "always" choices by command prefix so a
- * single prompt per command covers repeat invocations in the same session.
+ * Pattern approval cache — ask-once-per-pattern (Claude-Code-like).
+ *
+ * Wraps any inner prompt (TUI modal, stdin). The first `ask` for a pattern
+ * delegates to the user; `always` records the pattern for the session,
+ * `always-persist` additionally calls `onPersist` (the CLI wires this to
+ * append the pattern to ~/.klyro/settings.json and the live engine).
+ * Re-prompts never happen for a recorded pattern within the session.
+ *
+ * The pattern comes from `req.pattern` (pre-derived by the runtime via
+ * `patternForCall`) or is derived from `req.input` here as a fallback.
  */
-export declare class InMemoryAllowlist implements ApprovalPrompt {
+export declare class PatternApprovalCache implements ApprovalPrompt {
     private readonly inner;
-    private readonly allow;
-    constructor(inner?: ApprovalPrompt);
+    private readonly opts;
+    private readonly session;
+    constructor(inner?: ApprovalPrompt, opts?: {
+        onPersist?: (pattern: string) => void | Promise<void>;
+    });
     ask(req: ApprovalRequest): Promise<ApprovalChoice>;
 }

package/dist/policy/approval.js

@@ -7,6 +7,7 @@
  */
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
+import { patternForCall } from './patterns.js';
 /** Default prompt backed by readline on stdin/stdout. */
 export class StdinApprovalPrompt {
     async ask(req) {
@@ -34,21 +35,48 @@ export class DenyAllApprovalPrompt {
     }
 }
 /**
- * In-memory allowlist: tracks "always" choices by command prefix so a
- * single prompt per command covers repeat invocations in the same session.
+ * Pattern approval cache — ask-once-per-pattern (Claude-Code-like).
+ *
+ * Wraps any inner prompt (TUI modal, stdin). The first `ask` for a pattern
+ * delegates to the user; `always` records the pattern for the session,
+ * `always-persist` additionally calls `onPersist` (the CLI wires this to
+ * append the pattern to ~/.klyro/settings.json and the live engine).
+ * Re-prompts never happen for a recorded pattern within the session.
+ *
+ * The pattern comes from `req.pattern` (pre-derived by the runtime via
+ * `patternForCall`) or is derived from `req.input` here as a fallback.
  */
-export class InMemoryAllowlist {
+export class PatternApprovalCache {
     inner;
-    allow = new Set();
-    constructor(inner = new DenyAllApprovalPrompt()) {
+    opts;
+    session = new Set();
+    constructor(inner = new DenyAllApprovalPrompt(), opts = {}) {
         this.inner = inner;
+        this.opts = opts;
     }
     async ask(req) {
-        if (this.allow.has(req.summary))
+        const key = req.pattern ?? patternFromRequest(req);
+        if (key && this.session.has(key))
             return 'allow';
         const choice = await this.inner.ask(req);
-        if (choice === 'always')
-            this.allow.add(req.summary);
+        if ((choice === 'always' || choice === 'always-persist') && key) {
+            this.session.add(key);
+        }
+        if (choice === 'always-persist' && key) {
+            // Best-effort: the current call is already approved via the session
+            // set above — a persist failure must not retro-deny it.
+            try {
+                await this.opts.onPersist?.(key);
+            }
+            catch {
+                /* ignore */
+            }
+        }
         return choice;
     }
 }
+function patternFromRequest(req) {
+    if (!req.input)
+        return undefined;
+    return patternForCall(req.toolName, req.input);
+}

package/dist/policy/engine.d.ts

@@ -67,6 +67,19 @@ export declare class PolicyEngine {
         nonInteractive: boolean;
     }): Promise<Decision>;
     private evaluateGlobRules;
+    /**
+     * Session rule management — appends a glob rule (`tool(glob)` grammar)
+     * if not already present. Used for persisted "always allow" patterns
+     * (loaded at startup) and live additions (approval `always→settings`).
+     */
+    addAllow(rule: string): void;
+    addDeny(rule: string): void;
+    addAsk(rule: string): void;
+    applyRules(rules: {
+        allow?: string[];
+        deny?: string[];
+        ask?: string[];
+    }): void;
 }
 /** Builtin set of rules. Order matters: first match wins. */
 export declare function builtinRules(): PolicyRule[];

package/dist/policy/engine.js

@@ -116,6 +116,34 @@ export class PolicyEngine {
         // Precedence: deny → allow → ask
         return check(this.config.deny, 'deny') ?? check(this.config.allow, 'allow') ?? check(this.config.ask, 'ask') ?? null;
     }
+    /**
+     * Session rule management — appends a glob rule (`tool(glob)` grammar)
+     * if not already present. Used for persisted "always allow" patterns
+     * (loaded at startup) and live additions (approval `always→settings`).
+     */
+    addAllow(rule) {
+        const list = (this.config.allow ??= []);
+        if (!list.includes(rule))
+            list.push(rule);
+    }
+    addDeny(rule) {
+        const list = (this.config.deny ??= []);
+        if (!list.includes(rule))
+            list.push(rule);
+    }
+    addAsk(rule) {
+        const list = (this.config.ask ??= []);
+        if (!list.includes(rule))
+            list.push(rule);
+    }
+    applyRules(rules) {
+        for (const r of rules.allow ?? [])
+            this.addAllow(r);
+        for (const r of rules.deny ?? [])
+            this.addDeny(r);
+        for (const r of rules.ask ?? [])
+            this.addAsk(r);
+    }
 }
 /** Builtin set of rules. Order matters: first match wins. */
 export function builtinRules() {

package/dist/policy/patterns.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Approval patterns — the unit of "always allow this pattern".
+ *
+ * A pattern uses the same `tool(glob)` grammar the policy engine matches
+ * (`matchesGlobRule` in engine.ts), e.g. `shell_exec(npm *)`,
+ * `write_file(src/index.ts)`. Derivation is deterministic: the same call
+ * shape always yields the same pattern, so session caching can key on exact
+ * pattern equality and persisted patterns re-match across sessions.
+ *
+ * Scoping (Claude-Code-like):
+ *   - shell_exec / run_verify → first command word + ` *`
+ *     (`npm test` and `npm run build` share `shell_exec(npm *)`)
+ *   - file tools with a path → the exact path (safest: no wildcards)
+ *   - everything else → the bare tool name (whole-tool session allow)
+ */
+export declare function patternForCall(name: string, input: Record<string, unknown>): string;

package/dist/policy/patterns.js

@@ -0,0 +1,26 @@
+/**
+ * Approval patterns — the unit of "always allow this pattern".
+ *
+ * A pattern uses the same `tool(glob)` grammar the policy engine matches
+ * (`matchesGlobRule` in engine.ts), e.g. `shell_exec(npm *)`,
+ * `write_file(src/index.ts)`. Derivation is deterministic: the same call
+ * shape always yields the same pattern, so session caching can key on exact
+ * pattern equality and persisted patterns re-match across sessions.
+ *
+ * Scoping (Claude-Code-like):
+ *   - shell_exec / run_verify → first command word + ` *`
+ *     (`npm test` and `npm run build` share `shell_exec(npm *)`)
+ *   - file tools with a path → the exact path (safest: no wildcards)
+ *   - everything else → the bare tool name (whole-tool session allow)
+ */
+export function patternForCall(name, input) {
+    if ((name === 'shell_exec' || name === 'run_verify') && typeof input.command === 'string') {
+        const first = input.command.trim().split(/\s+/, 1)[0] ?? '';
+        if (first)
+            return `${name}(${first} *)`;
+    }
+    if (typeof input.path === 'string' && input.path.length > 0) {
+        return `${name}(${input.path})`;
+    }
+    return name;
+}

package/dist/tui/approval.d.ts

@@ -13,7 +13,7 @@
  *      a Promise.
  *   3. The App polls getPending() on every render to show a modal.
  *   4. The App's useInput handler sees a pending prompt and routes
- *      y/n/a to the resolver.
+ *      y/a/A/n to the resolver (A = always-persist to settings).
  *
  * Non-TTY mode (no Ink mounted) keeps using StdinApprovalPrompt; this
  * module is only used when the TUI is active.

package/dist/tui/approval.js

@@ -14,7 +14,7 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  *      a Promise.
  *   3. The App polls getPending() on every render to show a modal.
  *   4. The App's useInput handler sees a pending prompt and routes
- *      y/n/a to the resolver.
+ *      y/a/A/n to the resolver (A = always-persist to settings).
  *
  * Non-TTY mode (no Ink mounted) keeps using StdinApprovalPrompt; this
  * module is only used when the TUI is active.
@@ -85,7 +85,7 @@ export function ApprovalModal({ bridge }) {
             return;
         }
         if (c === 'A') {
-            bridge.resolve('always');
+            bridge.resolve('always-persist');
             return;
         }
         if (c === 'd' || c === 'n') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "klyro",
-  "version": "0.1.62",
-  "description": "Klyro \u2014 autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
+  "version": "0.1.63",
+  "description": "Klyro — autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",