klyro 0.1.63 → 1.0.1

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

@@ -30,7 +30,14 @@ export interface AnthropicAdapterOptions {
     authHeader?: 'x-api-key' | 'Authorization';
     /** Beta features (e.g. ['prompt-caching-2024-07-31', 'tools-2024-04-04']). */
     betas?: string[];
+    /**
+     * Prompt caching: put a `cache_control: {type:'ephemeral'}` breakpoint on
+     * the stable system block and send the `prompt-caching-2024-07-31` beta
+     * (merged with user betas). Default true.
+     */
+    promptCache?: boolean;
 }
+export declare const PROMPT_CACHING_BETA = "prompt-caching-2024-07-31";
 interface AnthropicMessage {
     role: 'user' | 'assistant';
     content: Array<{
@@ -51,6 +58,25 @@ interface AnthropicMessage {
         is_error?: boolean;
     }>;
 }
+interface AnthropicRequest {
+    model: string;
+    system?: string | Array<{
+        type: 'text';
+        text: string;
+        cache_control?: {
+            type: 'ephemeral';
+        };
+    }>;
+    messages: AnthropicMessage[];
+    tools?: Array<{
+        name: string;
+        description: string;
+        input_schema: unknown;
+    }>;
+    max_tokens: number;
+    temperature?: number;
+    stream: true;
+}
 interface AnthropicSseEvent {
     type: string;
     [key: string]: unknown;
@@ -61,6 +87,13 @@ export declare class AnthropicApiError extends Error {
     constructor(status: number, body: string);
 }
 export declare function anthropicAdapter(opts: AnthropicAdapterOptions): ProviderAdapter;
+/**
+ * Build the Anthropic `system` field. The stable system text gets the
+ * cache breakpoint; the volatile telemetry suffix (when present) rides as
+ * a second, uncached block so it never poisons the prefix cache.
+ * Exported via _internal for testing.
+ */
+export declare function buildAnthropicSystem(system: string | undefined, suffix: string | undefined, promptCache: boolean): AnthropicRequest['system'];
 /**
  * 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
@@ -79,6 +112,8 @@ interface AnthropicStreamState {
     usage: {
         input?: number;
         output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
 }
 declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
@@ -92,5 +127,6 @@ export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
     translateSse: typeof translateSse;
+    buildAnthropicSystem: typeof buildAnthropicSystem;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -16,8 +16,10 @@
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
  */
 import { assertSafeBaseURL } from '../chat.js';
+import { parseRetryAfterMs } from './provider-adapter.js';
 const DEFAULT_VERSION = '2023-06-01';
 const DEFAULT_TIMEOUT_MS = 120_000;
+export const PROMPT_CACHING_BETA = 'prompt-caching-2024-07-31';
 export class AnthropicApiError extends Error {
     status;
     body;
@@ -34,7 +36,10 @@ export function anthropicAdapter(opts) {
     const baseURL = rawBase.replace(/\/+$/, '');
     const version = opts.anthropicVersion ?? DEFAULT_VERSION;
     const authHeader = opts.authHeader ?? 'x-api-key';
-    const betas = opts.betas ?? [];
+    const promptCache = opts.promptCache ?? true;
+    const betas = [...(opts.betas ?? [])];
+    if (promptCache && !betas.includes(PROMPT_CACHING_BETA))
+        betas.push(PROMPT_CACHING_BETA);
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
         throw new Error('anthropicAdapter: no fetch available — pass opts.fetchImpl or run on Node 18+');
@@ -44,15 +49,36 @@ export function anthropicAdapter(opts) {
         stream(req) {
             return streamAnthropic(req, {
                 baseURL, apiKey: opts.apiKey, timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-                fetchImpl, version, authHeader, betas,
+                fetchImpl, version, authHeader, betas, promptCache,
             });
         },
     };
 }
+/**
+ * Build the Anthropic `system` field. The stable system text gets the
+ * cache breakpoint; the volatile telemetry suffix (when present) rides as
+ * a second, uncached block so it never poisons the prefix cache.
+ * Exported via _internal for testing.
+ */
+export function buildAnthropicSystem(system, suffix, promptCache) {
+    const hasSuffix = suffix !== undefined && suffix !== '';
+    const breakpoint = promptCache ? { cache_control: { type: 'ephemeral' } } : {};
+    if (hasSuffix) {
+        if (!system)
+            return promptCache ? [{ type: 'text', text: suffix, ...breakpoint }] : suffix;
+        return [
+            { type: 'text', text: system, ...breakpoint },
+            { type: 'text', text: suffix },
+        ];
+    }
+    if (!system)
+        return undefined;
+    return promptCache ? [{ type: 'text', text: system, ...breakpoint }] : system;
+}
 async function* streamAnthropic(req, opts) {
     const body = {
         model: req.model,
-        system: req.system,
+        system: buildAnthropicSystem(req.system, req.systemSuffix, opts.promptCache),
         messages: toAnthropicMessages(req.messages),
         tools: req.tools.length > 0 ? req.tools.map(toAnthropicTool) : undefined,
         max_tokens: req.maxTokens ?? 4096,
@@ -97,11 +123,19 @@ async function* streamAnthropic(req, opts) {
     clearTimeout(timer);
     if (!resp.ok || !resp.body) {
         const text = await resp.text().catch(() => '<unreadable>');
+        // 413 / request_too_large (or a too-long-prompt message) is context
+        // overflow, not transient: dedicated code, never retryable here — the
+        // runtime owns compress-and-retry.
+        const isOverflow = resp.status === 413 || /request_too_large|too_large|prompt_too_long|context_length|maximum context length|prompt is too long/i.test(text);
+        const retryable = !isOverflow && (resp.status >= 500 || resp.status === 429);
+        const retryAfterMs = retryable ? parseRetryAfterMs(resp.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
-            code: `http_${resp.status}`,
+            code: isOverflow ? 'REQUEST_TOO_LARGE' : `http_${resp.status}`,
             message: `Anthropic API returned ${resp.status}: ${text.slice(0, 500)}`,
-            retryable: resp.status >= 500 || resp.status === 429,
+            retryable,
+            status: String(resp.status),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         };
         return;
     }
@@ -203,25 +237,45 @@ async function* streamAnthropic(req, opts) {
             kind: 'message_end',
             finishReason: 'stop',
             ...(state.usage.input !== undefined || state.usage.output !== undefined
-                ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                ? { usage: withCache(state.usage) }
                 : {}),
         };
     }
 }
+/** Copy input/output plus any cache counters into a message_end usage payload. */
+function withCache(u) {
+    return {
+        input: u.input ?? 0,
+        output: u.output ?? 0,
+        ...(u.cacheRead !== undefined ? { cacheRead: u.cacheRead } : {}),
+        ...(u.cacheWrite !== undefined ? { cacheWrite: u.cacheWrite } : {}),
+    };
+}
+/** Fold an Anthropic `usage` object (message_start or message_delta) into stream state. */
+function recordAnthropicUsage(state, u) {
+    const rec = u;
+    if (typeof rec?.input_tokens === 'number')
+        state.usage.input = rec.input_tokens;
+    if (typeof rec?.output_tokens === 'number') {
+        state.usage.output = (state.usage.output ?? 0) + rec.output_tokens;
+    }
+    if (typeof rec?.cache_creation_input_tokens === 'number') {
+        state.usage.cacheWrite = (state.usage.cacheWrite ?? 0) + rec.cache_creation_input_tokens;
+    }
+    if (typeof rec?.cache_read_input_tokens === 'number') {
+        state.usage.cacheRead = (state.usage.cacheRead ?? 0) + rec.cache_read_input_tokens;
+    }
+}
 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;
+            recordAnthropicUsage(state, usage);
             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;
-            }
+            recordAnthropicUsage(state, parsed.usage);
             return out;
         }
         case 'content_block_start': {
@@ -292,17 +346,20 @@ function translateSse(event, parsed, state) {
                 kind: 'message_end',
                 finishReason: 'stop',
                 ...(state.usage.input !== undefined || state.usage.output !== undefined
-                    ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                    ? { usage: withCache(state.usage) }
                     : {}),
             });
             return out;
         }
         case 'error': {
             const err = parsed.error;
+            const rawType = err?.type ?? 'anthropic_error';
+            const rawMsg = err?.message ?? 'unknown Anthropic error';
+            const isOverflow = /too_large|too_long|context_length|prompt_too_long|prompt is too long/i.test(`${rawType} ${rawMsg}`);
             out.push({
                 kind: 'error',
-                code: err?.type ?? 'anthropic_error',
-                message: err?.message ?? 'unknown Anthropic error',
+                code: isOverflow ? 'REQUEST_TOO_LARGE' : rawType,
+                message: rawMsg,
                 retryable: false,
             });
             return out;
@@ -373,4 +430,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem };

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Agent capability enforcement (P0.2 from r-6-10.fix.md).
+ *
+ * Resolves the **effective tool set** for a (child) agent by intersecting:
+ *
+ *   1. the parent's effective tools — a child can never receive more tools than its parent
+ *   2. the agent definition's `allowedTools` (if specified)
+ *   3. the runtime policy's allowed tools (e.g. `--allow-write` flags)
+ *
+ * Then applies safety modifiers:
+ *
+ *   - `readonly: true` strips every tool classified as write or mutation.
+ *   - `canSpawn: false` (default for children) removes any spawn_agent-like tools.
+ *   - A deny-list always wins, regardless of what the agent declares.
+ *
+ * This is a pure function — no I/O, no side effects. It exists so the runtime
+ * can decide which tools to expose to the model BEFORE the model picks one.
+ *
+ * Wiring lives in src/agent/runtime.ts (see the tool-filter hook).
+ */
+export interface AgentCapabilities {
+    /** Tools the agent definition explicitly allows. `undefined` means "no allow-list". */
+    allowedTools?: string[];
+    /** If true, write/mutation tools are stripped. */
+    readonly?: boolean;
+    /** If false (or unset), tools that can spawn new agents are stripped. */
+    canSpawn?: boolean;
+    /** Model override — if the provider cannot satisfy it, callers must error rather than fall back. */
+    model?: string;
+    /** Recursion depth cap. Beyond this, spawn attempts are blocked. */
+    maxDepth?: number;
+    /**
+     * Path allow-list for filesystem scope. `undefined` means unconstrained.
+     * A child's effective list is the intersection with its parent's.
+     */
+    allowedPaths?: string[];
+}
+export interface ResolveToolsInput {
+    /** Tools the parent is allowed to use (or `null` for the root agent = all registered tools). */
+    parentTools: ReadonlySet<string> | null;
+    /** The agent's declared capability profile. */
+    agent: AgentCapabilities;
+    /** Tools currently allowed by runtime policy (e.g. user-permission flags). */
+    policyAllowed: ReadonlySet<string>;
+    /** All tools known to the registry (used when parentTools is null). */
+    registryTools: ReadonlySet<string>;
+    /** Tools that mutate state — stripped under `readonly`. */
+    writeTools: ReadonlySet<string>;
+    /** Tools that spawn other agents — stripped when `canSpawn` is false. */
+    spawnTools: ReadonlySet<string>;
+    /** Tools that are NEVER allowed, even if explicitly requested. */
+    denied: ReadonlySet<string>;
+    /** If true, spawn tools are kept even when agent.canSpawn is false/unset. */
+    canSpawnOverride?: boolean;
+}
+export interface ResolveToolsResult {
+    /** Tools the child agent is permitted to call. */
+    allowed: string[];
+    /** Tools that were denied (debugging/observability). */
+    dropped: {
+        tool: string;
+        reason: 'denied' | 'readonly' | 'no-spawn' | 'not-in-parent' | 'not-in-policy' | 'unknown';
+    }[];
+}
+/**
+ * Resolve the effective tool set for an agent.
+ *
+ * Order of operations:
+ *   1. Start from `parentTools ?? registryTools`.
+ *   2. Intersect with `policyAllowed`.
+ *   3. If `allowedTools` is set, intersect again.
+ *   4. Strip `writeTools` if `readonly`.
+ *   5. Strip `spawnTools` if `!canSpawn`.
+ *   6. Remove `denied` last (always wins).
+ */
+export declare function resolveAgentTools(input: ResolveToolsInput): ResolveToolsResult;
+/**
+ * Reason a tool was dropped from the resolved capability set. Mirrors
+ * `ResolveToolsResult.dropped[].reason`.
+ */
+export type DropReason = 'denied' | 'readonly' | 'no-spawn' | 'not-in-parent' | 'not-in-policy' | 'unknown';
+/**
+ * Fully-resolved capability profile for a child agent — tool set plus
+ * non-tool knobs (model override, recursion cap). Computed once at spawn
+ * time and threaded through the runtime as `parentContext`.
+ */
+export interface ResolvedCapabilities {
+    /** Sorted tool names the child is allowed to invoke. */
+    allowed: ReadonlySet<string>;
+    /** Per-tool drop reasons — surfaced in ChildSummary for parent visibility. */
+    dropped: {
+        tool: string;
+        reason: DropReason;
+    }[];
+    /** Model override to send to the provider (or undefined to inherit parent). */
+    model?: string;
+    /** Effective recursion depth cap. Caller MUST reject spawn when depth + 1 > maxDepth. */
+    maxDepth: number;
+    readonly: boolean;
+    canSpawn: boolean;
+    /**
+     * Effective filesystem scope: parent's `allowedPaths` intersected with the
+     * agent's own. `undefined` means unconstrained (neither side restricts).
+     */
+    allowedPaths?: string[];
+}
+/** Extra knobs consumed by `resolveCapabilities` on top of `ResolveToolsInput`. */
+export interface ResolveCapabilitiesExtra {
+    /** Caller-provided maxDepth (e.g. from CLI `--max-depth` or a parent's maxDepth). Required. */
+    maxDepth: number;
+    /** If true, the resolved `allowed` set may include tools that themselves spawn agents. */
+    canSpawnOverride?: boolean;
+    /**
+     * The parent's filesystem allow-list (`undefined` = unconstrained parent —
+     * the agent's own list, if any, applies as-is).
+     */
+    parentAllowedPaths?: string[];
+}
+/** Combined input for the one-shot resolver used by the orchestrator. */
+export interface ResolveCapabilitiesInput extends ResolveToolsInput, ResolveCapabilitiesExtra {
+}
+/**
+ * Intersect two filesystem allow-lists. `undefined` on either side means
+ * "unconstrained" — the other side applies as-is; both `undefined` stays
+ * `undefined`. Entries survive when they are equal to, or nested inside, an
+ * entry of the other list (so a parent `/repo` and a child `/repo/sub`
+ * intersect to `/repo/sub`). Comparison is case-insensitive on Windows.
+ */
+export declare function intersectAllowedPaths(parentPaths?: string[], agentPaths?: string[]): string[] | undefined;
+/**
+ * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
+ *
+ * `maxDepth` precedence (most specific wins):
+ *   1. `agent.maxDepth` (if set on the definition)
+ *   2. `extra.maxDepth` (parent / CLI cap)
+ * `model` is propagated only when the agent declares one; we do not silently
+ * override a parent's chosen model.
+ */
+export declare function resolveCapabilities(input: ResolveCapabilitiesInput): ResolvedCapabilities;
+/** Sensible defaults for "what counts as a write tool" if a caller doesn't override. */
+export declare const DEFAULT_WRITE_TOOLS: ReadonlySet<string>;
+/** Default spawn tools — removed from children by default. */
+export declare const DEFAULT_SPAWN_TOOLS: ReadonlySet<string>;
+/** Default deny-list — these are NEVER allowed, even if explicitly requested. */
+export declare const DEFAULT_DENIED_TOOLS: ReadonlySet<string>;

package/dist/agent/capabilities.js

@@ -0,0 +1,191 @@
+/**
+ * Agent capability enforcement (P0.2 from r-6-10.fix.md).
+ *
+ * Resolves the **effective tool set** for a (child) agent by intersecting:
+ *
+ *   1. the parent's effective tools — a child can never receive more tools than its parent
+ *   2. the agent definition's `allowedTools` (if specified)
+ *   3. the runtime policy's allowed tools (e.g. `--allow-write` flags)
+ *
+ * Then applies safety modifiers:
+ *
+ *   - `readonly: true` strips every tool classified as write or mutation.
+ *   - `canSpawn: false` (default for children) removes any spawn_agent-like tools.
+ *   - A deny-list always wins, regardless of what the agent declares.
+ *
+ * This is a pure function — no I/O, no side effects. It exists so the runtime
+ * can decide which tools to expose to the model BEFORE the model picks one.
+ *
+ * Wiring lives in src/agent/runtime.ts (see the tool-filter hook).
+ */
+/**
+ * Resolve the effective tool set for an agent.
+ *
+ * Order of operations:
+ *   1. Start from `parentTools ?? registryTools`.
+ *   2. Intersect with `policyAllowed`.
+ *   3. If `allowedTools` is set, intersect again.
+ *   4. Strip `writeTools` if `readonly`.
+ *   5. Strip `spawnTools` if `!canSpawn`.
+ *   6. Remove `denied` last (always wins).
+ */
+export function resolveAgentTools(input) {
+    const { parentTools, agent, policyAllowed, registryTools, writeTools, spawnTools, denied, } = input;
+    const allowed = new Set();
+    const dropped = [];
+    // 1. Baseline: parent's tools, or all registered tools for the root agent.
+    // Record narrowing for observability: registry tools outside the parent's
+    // set are reported as 'not-in-parent' drops (child can never exceed parent).
+    const baseline = parentTools ?? registryTools;
+    if (parentTools !== null) {
+        for (const name of registryTools) {
+            if (!parentTools.has(name)) {
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+    }
+    for (const name of baseline) {
+        if (!registryTools.has(name)) {
+            dropped.push({ tool: name, reason: 'unknown' });
+            continue;
+        }
+        if (!policyAllowed.has(name)) {
+            dropped.push({ tool: name, reason: 'not-in-policy' });
+            continue;
+        }
+        allowed.add(name);
+    }
+    // 3. Apply the agent's allow-list (if any). Anything not in the list is dropped.
+    if (agent.allowedTools) {
+        const explicit = new Set(agent.allowedTools);
+        for (const name of [...allowed]) {
+            if (!explicit.has(name)) {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+        // Tools requested in allowedTools but not in the baseline cannot be granted.
+        for (const name of agent.allowedTools) {
+            if (!allowed.has(name) && registryTools.has(name) && policyAllowed.has(name)) {
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+    }
+    // 4. readonly → strip write tools (plus run_verify: verification can
+    // execute arbitrary commands, so it is not read-only).
+    if (agent.readonly) {
+        for (const name of [...allowed]) {
+            if (writeTools.has(name) || name === 'run_verify') {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'readonly' });
+            }
+        }
+    }
+    // 5. canSpawn=false → strip spawn tools. Default: root agent (parentTools
+    // === null) may spawn; children strip unless explicitly enabled. An explicit
+    // canSpawnOverride=true (via resolveCapabilities) also keeps them.
+    const canSpawnEffective = input.canSpawnOverride ?? input.agent.canSpawn ?? (input.parentTools === null);
+    if (!canSpawnEffective) {
+        for (const name of [...allowed]) {
+            if (spawnTools.has(name)) {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'no-spawn' });
+            }
+        }
+    }
+    // 6. Deny-list always wins.
+    for (const name of [...allowed]) {
+        if (denied.has(name)) {
+            allowed.delete(name);
+            dropped.push({ tool: name, reason: 'denied' });
+        }
+    }
+    return {
+        allowed: [...allowed].sort(),
+        dropped: dropped.sort((a, b) => a.tool.localeCompare(b.tool)),
+    };
+}
+/**
+ * Intersect two filesystem allow-lists. `undefined` on either side means
+ * "unconstrained" — the other side applies as-is; both `undefined` stays
+ * `undefined`. Entries survive when they are equal to, or nested inside, an
+ * entry of the other list (so a parent `/repo` and a child `/repo/sub`
+ * intersect to `/repo/sub`). Comparison is case-insensitive on Windows.
+ */
+export function intersectAllowedPaths(parentPaths, agentPaths) {
+    if (parentPaths === undefined)
+        return agentPaths;
+    if (agentPaths === undefined)
+        return [...parentPaths];
+    const out = [];
+    const seen = new Set();
+    const within = (candidate, scope) => {
+        const norm = (p) => {
+            const n = p.replace(/\\/g, '/').replace(/\/+$/, '');
+            return process.platform === 'win32' ? n.toLowerCase() : n;
+        };
+        const c = norm(candidate);
+        const s = norm(scope);
+        return c === s || c.startsWith(s + '/');
+    };
+    for (const a of agentPaths) {
+        for (const p of parentPaths) {
+            // The overlap of two nested scopes is the narrower one.
+            const narrower = within(a, p) ? a : within(p, a) ? p : undefined;
+            if (narrower !== undefined) {
+                const key = process.platform === 'win32' ? narrower.toLowerCase() : narrower;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out.push(narrower);
+                }
+            }
+        }
+    }
+    return out.sort();
+}
+/**
+ * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
+ *
+ * `maxDepth` precedence (most specific wins):
+ *   1. `agent.maxDepth` (if set on the definition)
+ *   2. `extra.maxDepth` (parent / CLI cap)
+ * `model` is propagated only when the agent declares one; we do not silently
+ * override a parent's chosen model.
+ */
+export function resolveCapabilities(input) {
+    const resolved = resolveAgentTools(input);
+    const allowed = new Set(resolved.allowed);
+    const model = input.agent.model;
+    const maxDepth = input.agent.maxDepth ?? input.maxDepth;
+    // Default matches resolveAgentTools: the root agent (parentTools === null)
+    // may spawn; children strip spawn tools unless explicitly enabled.
+    const canSpawn = input.canSpawnOverride ?? input.agent.canSpawn ?? (input.parentTools === null);
+    const allowedPaths = intersectAllowedPaths(input.parentAllowedPaths, input.agent.allowedPaths);
+    return {
+        allowed,
+        dropped: resolved.dropped,
+        ...(model !== undefined ? { model } : {}),
+        maxDepth,
+        readonly: input.agent.readonly ?? false,
+        canSpawn,
+        ...(allowedPaths !== undefined ? { allowedPaths } : {}),
+    };
+}
+/** Sensible defaults for "what counts as a write tool" if a caller doesn't override. */
+export const DEFAULT_WRITE_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'multi_edit',
+    'apply_patch',
+    'shell_exec',
+    'memory_write',
+    'todo_write',
+]);
+/** Default spawn tools — removed from children by default. */
+export const DEFAULT_SPAWN_TOOLS = new Set([
+    'spawn_agent',
+]);
+/** Default deny-list — these are NEVER allowed, even if explicitly requested. */
+export const DEFAULT_DENIED_TOOLS = new Set([
+// Add dangerous tools here. Empty by default — extend as policy matures.
+]);

package/dist/agent/child-worker.d.ts

@@ -0,0 +1,104 @@
+/**
+ * G2 — Process isolation for sub-agents (V1: headless/CLI children).
+ *
+ * This module is the *child-process* end of spawn_agent. The orchestrator
+ * forks this file with `node` (never shares a process), passing a
+ * JSON-serializable payload on STDIN (not argv — the system prompt + memory
+ * can exceed argv/command-line length limits, which would fail the spawn with
+ * E2BIG). The child rebuilds a minimal but self-sufficient `RuntimeDeps`,
+ * runs the task through `run()`, emits ONE JSON `ChildResult` line on stdout,
+ * and exits 0/1.
+ *
+ * Isolation contract: a child that OOMs, segfaults, or enters an infinite
+ * loop fails ONLY this process — the parent harness survives and reports
+ * `CHILD_CRASH` exactly as it does for an in-process throw.
+ *
+ * V1 scope (documented honestly):
+ *   - Headless children only. TUI children stay in-process because the Ink
+ *     approval bridge is inherently tied to the parent terminal.
+ *   - The child runs a system-prompt STRING (already assembled by the parent,
+ *     so KLYRO.md + memory + trust decisions match) with a file-system tool
+ *     subset and DenyAll approval — no MCP server forwarding, no live prompt.
+ *   - Grandchild spawning is not forwarded: a process-isolated child rebuilds
+ *     its own agent bridge-less deps, so its tools see NO_ORCHESTRATOR (same
+ *     as a pre-bridge child). V2 may thread a task handle back via a socket.
+ *
+ * Secrets never cross the process boundary via argv/env leaks: the child
+ * reads its provider key/baseURL from the SAME env the parent CLI uses
+ * (KLYRO_API_KEY, KLYRO_BASE_URL), so credentials stay in-process/env,
+ * never in the payload.
+ */
+import type { RunOptions, RunResult, RuntimeDeps } from './runtime.js';
+export interface ChildWorkerPayload {
+    /** Working dir the child operates in (may be a worktree). */
+    cwd: string;
+    /** The task prompt. */
+    task: string;
+    /** Model string (drives adapter selection + rate table). */
+    model: string;
+    /** Pre-assembled system prompt (stable + volatile already spliced). */
+    systemPrompt: string;
+    /** Agent id, for the system prompt identity. */
+    agentId: string;
+    /** Cap caps. */
+    maxSteps?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+    maxTokens?: number;
+}
+/** The one-line result the child prints to stdout on success. */
+export type ChildResult = Pick<RunResult, 'status' | 'steps' | 'toolCalls' | 'finalText' | 'hasEdits' | 'usage'>;
+/**
+ * Differently-phrased crash, distinct from an in-process throw the parent
+ * would catch. The child either exited non-zero without a parseable result
+ * line, or produced a malformed result. Carries the raw stdout/stderr tail.
+ */
+export declare class ChildCrashError extends Error {
+    readonly likelyCause: 'exit' | 'oom' | 'timeout';
+    readonly stderrTail?: string | undefined;
+    constructor(message: string, likelyCause: 'exit' | 'oom' | 'timeout', stderrTail?: string | undefined);
+}
+/**
+ * Resolve the compiled child-worker entry that *this* module's neighboring
+ * build (src or dist) produced. Both dev (tsx, .ts) and packaged (dist, .js)
+ * layouts live beside this file, so we probe for whichever exists.
+ */
+export declare function workerEntryPath(): string;
+export interface ForkChildOptions {
+    /** Abort the child process when this fires (wired to the parent signal). */
+    signal?: AbortSignal;
+    /** Abort+kill the child after this long (defaults to 10 min). */
+    timeoutMs?: number;
+    /** Capture point for stderr (for diagnostics, already included in error). */
+    onStderr?: (chunk: string) => void;
+}
+/**
+ * Fork the child-worker as a real OS process and await its single JSON
+ * ChildResult line. Secrets never reach argv: the payload rides stdin, the
+ * provider key/baseURL come from the inherited env. Non-zero exit / missing
+ * line → rejects with ChildCrashError so the orchestrator maps it to
+ * CHILD_CRASH exactly as an in-process throw does.
+ */
+export declare function forkChild(entry: string, payload: ChildWorkerPayload, opts?: ForkChildOptions): Promise<ChildResult>;
+/**
+ * Rebuild a minimal RuntimeDeps from the payload + inherited env. Centralized
+ * so tests can call it directly. Errors on missing provider config.
+ */
+export declare function buildChildDeps(payload: ChildWorkerPayload): Promise<{
+    deps: RuntimeDeps;
+    options: RunOptions;
+}>;
+/**
+ * Read the JSON payload. Payloads arrive on stdin (the parent writes the JSON
+ * then ends stdin), never argv — large system prompts would otherwise fail
+ * the spawn with E2BIG on both Windows (32K cmdline) and Linux (MAX_ARG_STRLEN).
+ * Callers who must use argv (tests) can route through `runChildFromString`.
+ */
+export declare function readPayloadFromStdin(): Promise<string>;
+/**
+ * Main entry. Reads payload from stdin, runs, prints ONE JSON ChildResult
+ * line, exits 0 on complete, 1 on failure/crash (so the parent knows to mark
+ * CHILD_CRASH). Intended to be the sole behavior of this file when invoked as
+ * a real process.
+ */
+export declare function main(): Promise<void>;