@theokit/agents 7.6.0 → 8.1.0

package/dist/{bridge-entry-CvmBrmc9.d.ts → bridge-entry-BEniSXWE.d.ts}

@@ -1,178 +1,12 @@
 import { ExecutionContext } from '@theokit/http';
-import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, PreToolCallContext, PreToolCallDecision, PostToolCallContext, ToolResultTransformContext, TransformContext, SessionLifecycleContext, PreUserSendContext, PreUserSendResult, PostAssistantReplyContext, CustomTool, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, RunEventSink, TrustPosture } from '@theokit/sdk';
-import { z } from 'zod';
+import { d as AgentOptions, T as ToolOptions, z as ProjectContextOptions, C as CompiledAgentOptions, H as HumanInTheLoopOptions, A as AgentDefinition, a as CompiledTool, R as ReasoningEffort, G as Guardrail, p as SkillsSelection, S as SettingSourcesSelection, l as McpServersMap, M as MainLoopMeta } from './define-agent-3Kuf6iKM.js';
+import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings } from '@theokit/sdk';
+import { SandboxPosture } from '@theokit/sdk/sandbox';
 import { WireChunk } from '@theokit/presenter/wire';
-import { RetryOptions } from '@theokit/sdk/retry';
+import { z } from 'zod';
+import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-
-/**
- * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
- * `(string & {})` accepts provider-specific values forward-compat (mirrors `AgentRunErrorCode`) — the
- * SDK validates the value against the model's catalog. Defined in this leaf module so every layer
- * (`@Agent` config, compiler, runner, sdk-adapter) imports it without an import cycle.
- */
-type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | (string & {});
-/** Scalar agent configuration. */
-interface AgentOptions {
-    /** Unique agent name (kebab-case). */
-    name: string;
-    /** HTTP route prefix (e.g., '/api/agents/support'). */
-    route: string;
-    /** LLM model identifier (e.g., 'claude-sonnet-4-5-20250929'). */
-    model?: string;
-    /** Extended-thinking effort; mapped to the SDK `ModelSelection.params` so the provider reasons. */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Opt-in (default false): convert inline `<think>…</think>` in the text stream into `thinking`
-     * events (M2) — for models that emit reasoning as inline tags (qwen/deepseek) rather than via a
-     * native reasoning param. Off by default since a code assistant may emit literal `<think>` in text.
-     */
-    parseThinkTags?: boolean;
-    /**
-     * Opt-in (default false): strip a leaked Hermes `<function=…></tool_call>` tool-call dialect out of
-     * the visible text (theocode#32) — for models (qwen/qwen3-coder) that intermittently emit tool calls
-     * as text instead of native `tool_calls`. Off by default since a code assistant may emit a literal
-     * `<function=` in answer/code text. Sibling of {@link parseThinkTags}.
-     */
-    stripToolDialect?: boolean;
-    /**
-     * Opt-in (default false): recover a leaked Hermes `<function=…></tool_call>` tool-call dialect so the
-     * call actually EXECUTES (theokit#58 follow-up). Where {@link stripToolDialect} only hides the leaked
-     * block from the visible text, this enables the SDK's `extractToolCallsFromContent` on the chat route,
-     * so a `chat_completions` finish with ZERO native `tool_calls` has its text scanned for the dialect and
-     * any recovered calls are dispatched by the loop. For models (qwen/qwen3-coder via OpenRouter) that
-     * leak tool calls as text. Off by default (a code assistant may print a literal `<function=`); fail-open.
-     * Has effect only when {@link AgentOptions} routes a provider via `providers.routes`. Sibling of
-     * {@link stripToolDialect} — typically enabled together.
-     */
-    recoverLeakedToolCalls?: boolean;
-    /** Enable SSE streaming (default: true). */
-    stream?: boolean;
-    /** Maximum loop iterations before forcing a terminal response. */
-    maxIterations?: number;
-    /** Timeout in milliseconds for the entire agent run. */
-    timeoutMs?: number;
-    /**
-     * System prompt for the agent. Either a static string OR a
-     * {@link SystemPromptResolver} computed per request (V4-L.1, Axis-B) — the SDK
-     * invokes the resolver each send with the run's `SystemPromptContext` (cwd, etc.).
-     */
-    systemPrompt?: string | SystemPromptResolver;
-}
-/** Configuration stored by @MainLoop() decorator. */
-interface MainLoopOptions {
-    /** Execution strategy. */
-    strategy?: 'simple-chat' | 'plan-act-reflect' | 'react';
-    /** Maximum iterations for this loop. */
-    maxIterations?: number;
-    /** Timeout in milliseconds. */
-    timeoutMs?: number;
-}
-/** Internal representation of a resolved @MainLoop. */
-interface MainLoopMeta {
-    propertyKey: string | symbol;
-    strategy: 'simple-chat' | 'plan-act-reflect' | 'react';
-    maxIterations?: number;
-    timeoutMs?: number;
-}
-/** Configuration stored by @Toolbox() decorator. */
-interface ToolboxOptions {
-    /** Namespace prefix for all tools in this toolbox (e.g., 'support'). */
-    namespace?: string;
-}
-/** Configuration stored by @Tool() decorator. */
-interface ToolOptions {
-    /** Tool name (surfaced to LLM). */
-    name: string;
-    /** LLM-facing description. */
-    description: string;
-    /** Zod input schema — compiled to JSON Schema via defineTool(). */
-    input: z.ZodType;
-    /** Risk level (informational — feeds manifest + UI). */
-    risk?: 'low' | 'medium' | 'high';
-}
-/** Budget configuration for @Budget() decorator. */
-interface BudgetOptions {
-    /** Maximum cost in USD for this scope. */
-    maxCostUsd: number;
-    /** Rolling window for budget tracking. */
-    window?: 'daily' | 'monthly';
-}
-/** Approval configuration for @RequiresApproval() decorator. */
-interface ApprovalOptions {
-    /** Reason shown to the approver. */
-    reason: string;
-}
-/** Policy handler function type. */
-type PolicyHandler = (user: {
-    roles: string[];
-}) => boolean;
-/**
- * M53 — moved here from the `@HumanInTheLoop` decorator, which is being deleted: the type is
- * consumed by `compileHitlGates` and the toolbox capability, not by the decorator alone.
- */
-type TimeoutAction = 'abort' | 'proceed' | 'retry';
-interface HumanInTheLoopOptions {
-    /** Question shown to the human approver. */
-    question: string;
-    /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */
-    timeout?: number;
-    /** Action when timeout expires (default: 'abort'). */
-    onTimeout?: TimeoutAction;
-    /** Show the tool input to the approver (default: true). */
-    showInput?: boolean;
-    /**
-     * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited
-     * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI
-     * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).
-     */
-    payloadSchema?: Record<string, unknown>;
-}
-
-type McpServersMap = Record<string, McpServerConfig>;
-/** M53 — moved from the `@ProjectContext` decorator being deleted; read by the compiler. */
-type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
-type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
-interface ProjectContextOptions {
-    /** Files that mark the project root (searched upward from cwd). */
-    rootMarkers?: string[];
-    /** How to index the codebase for structural understanding. */
-    indexStrategy?: IndexStrategy;
-    /** Maximum files to include in context per request. */
-    maxFilesInContext?: number;
-    /** How to rank file relevance when selecting context. */
-    relevanceStrategy?: RelevanceStrategy;
-    /** Glob patterns to exclude from indexing and context. */
-    ignorePatterns?: string[];
-    /** File extensions to include in indexing (default: all text files). */
-    includeExtensions?: string[];
-}
-type CheckpointStrategy = 'after-tool-call' | 'after-iteration' | 'manual';
-type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis';
-interface CheckpointOptions {
-    /** Where to persist checkpoints. */
-    storage?: CheckpointStorage;
-    /** When to auto-checkpoint (default: 'after-tool-call'). */
-    strategy?: CheckpointStrategy;
-    /** Maximum checkpoints to retain per run (rolling window). */
-    maxCheckpoints?: number;
-    /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */
-    ttl?: number;
-}
-type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0';
-type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global';
-interface MemoryOptions {
-    /** Memory provider backend. */
-    provider?: MemoryProvider;
-    /** Enable semantic search via embeddings. */
-    embeddings?: boolean;
-    /** Enable full-text search (FTS5). */
-    fts?: boolean;
-    /** Memory isolation scope (default: 'per-user'). */
-    scope?: MemoryScope;
-    /** Maximum facts to retain per scope (0 = unlimited). */
-    maxFacts?: number;
-}
+import { RetryOptions } from '@theokit/sdk/retry';
 
 /**
  * AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
@@ -200,215 +34,6 @@ declare function createAgentExecutionContext(base: ExecutionContext, agent: Agen
 /** Narrow an ExecutionContext to AgentExecutionContext if it is one. */
 declare function isAgentContext(ctx: ExecutionContext): ctx is AgentExecutionContext;
 
-/**
- * M9 (theokit-ai-first) — guardrail contract + typed errors.
- *
- * ADR-0040 § D2: guardrails are a HOME/BOUNDARY concern (filter user input before the SDK,
- * filter model output before the client). They REUSE the SDK runtime — this module makes zero
- * LLM calls. A guard reports one of three actions; the pipeline (`pipeline.ts`) enforces them.
- */
-/** What a guard decided for a piece of text. */
-type GuardrailAction = 'allow' | 'block' | 'redact';
-/**
- * The result of a single guard check.
- * - `allow`  — text passes untouched.
- * - `block`  — the pipeline throws {@link GuardrailViolationError}; the run stops fail-fast.
- * - `redact` — the pipeline replaces the text with {@link GuardrailResult.text} and continues.
- */
-interface GuardrailResult {
-    action: GuardrailAction;
-    /** Human-readable reason — required in spirit for `block`, surfaced in the thrown error. */
-    reason?: string;
-    /** The transformed text — present (and used) only when `action === 'redact'`. */
-    text?: string;
-}
-/**
- * A guardrail. A guard MAY inspect input (before the model), output (after the model), or both.
- * A guard that omits a phase hook is skipped for that phase.
- */
-interface Guardrail {
-    readonly name: string;
-    checkInput?(text: string): GuardrailResult | Promise<GuardrailResult>;
-    checkOutput?(text: string): GuardrailResult | Promise<GuardrailResult>;
-}
-/** Which boundary phase a violation happened in. */
-type GuardrailPhase = 'input' | 'output';
-/** Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md. */
-declare class GuardrailViolationError extends Error {
-    readonly guardName: string;
-    readonly phase: GuardrailPhase;
-    readonly reason: string;
-    constructor(guardName: string, phase: GuardrailPhase, reason: string);
-}
-/** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
-declare class CostBudgetExceededError extends Error {
-    readonly usedTokens: number;
-    readonly maxTokens: number;
-    constructor(usedTokens: number, maxTokens: number);
-}
-
-/**
- * M13 (theokit-ai-first) — per-request skills resolution (ADR-0040 § D2, home/boundary concern).
- *
- * The static `skills.enabled` filter already works (`compile-skills` maps `include` → the SDK's
- * `enabled`). This adds a PER-REQUEST resolver so multi-tenant apps expose different skill sets to
- * different users. A selection is either a static list or a function of the request context (the M7
- * run-context). Discovery + injection stay in the SDK; this only CHOOSES the enabled set per call.
- */
-
-/** The request context handed to a skills resolver (the M7 run-context — opaque per-request data). */
-type SkillsRequestContext = Record<string, unknown>;
-/**
- * How the skill set is chosen:
- * - a static array of `string` (filesystem skill NAMES → `skills.enabled`) and/or `InlineSkill`
- *   objects from `createSkill` (code-defined skills → `skills.inline`, injected into the `<skills>`
- *   block). A mixed list is split at compile time.
- * - a function — resolved per request from the {@link SkillsRequestContext} (sync or async). The
- *   resolver returns filesystem skill NAMES (inline skills are static — declared on the agent).
- */
-type SkillsSelection = readonly (string | InlineSkill)[] | ((ctx: SkillsRequestContext) => readonly string[] | Promise<readonly string[]>);
-/**
- * Resolve the enabled skill names for a request. Returns `undefined` when no selection is given (the
- * SDK then enables every discovered skill). Fails fast if a resolver returns a non-array. The static
- * array is compiled ahead of time (see `compileSkillsSelection`), so this is exercised for the
- * resolver form; a static array is defensively narrowed to its string (name) members.
- */
-declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ctx: SkillsRequestContext): Promise<string[] | undefined>;
-
-/**
- * Agent compiler — transforms decorator metadata into SDK calls.
- *
- * Per ADR D1: @Agent is a macro over Agent.create().
- * Per ADR D3: @Tool compiles to defineTool().
- *
- * EC-3: throws if toolbox instance is missing from the instances map.
- */
-
-/**
- * M53 — the input shape `compileTools`/`compileHitlGates` consume, declared WITH them now that the
- * metadata walk that used to own it is gone. `ToolboxCapability` builds this from a class'
- * `static tools` declaration.
- */
-/** A guard/interceptor class token — identity only (the DI container instantiates it). */
-type ClassToken = abstract new (...args: never[]) => object;
-interface ToolWalkResult {
-    propertyKey: string | symbol;
-    config: ToolOptions;
-    guards: ClassToken[];
-    approval?: ApprovalOptions;
-    capabilities?: string[];
-    budget?: BudgetOptions;
-    trace: boolean;
-    audit: boolean;
-    /** HITL config when the tool is gated (M4); absent ⇒ not gated. */
-    hitl?: HumanInTheLoopOptions;
-}
-interface ToolboxWalkResult {
-    /** The toolbox class — used as the identity key into `toolboxInstances`. */
-    class: ClassToken;
-    namespace: string;
-    tools: ToolWalkResult[];
-    guards: ClassToken[];
-}
-/** Minimal interface matching defineTool() result shape. */
-interface CompiledTool {
-    name: string;
-    description: string;
-    inputSchema: unknown;
-    /**
-     * M7 — the optional 2nd `ctx` arg carries the SDK run context: `ctx.context` is the
-     * `defineAgent({ context })` / per-run value, `ctx.signal` the abort signal. Optional so the
-     * decorator `@Tool` handlers (which ignore it) stay assignable. The SDK calls the tool with
-     * both args; a handler that needs run-context (e.g. a filesystem tool reading `projectRoot`)
-     * reads `ctx?.context`.
-     */
-    handler: (input: unknown, ctx?: {
-        signal?: AbortSignal;
-        context?: unknown;
-    }) => string | Promise<string>;
-}
-/**
- * Compile @Tool metadata into tool definitions.
- *
- * @param toolboxes - Walked toolbox metadata
- * @param toolboxInstances - Map of Toolbox class → instantiated object (for `this` binding)
- */
-declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<ClassToken, object>): CompiledTool[];
-/** Compiled sub-agent definition matching SDK AgentDefinition shape. */
-interface CompiledSubAgent {
-    model?: string;
-    /**
-     * V4-L.1: typed as the union for consistency with `AgentOptions.systemPrompt`,
-     * so `compileSubAgents` carries whatever the sub-agent declared. Sub-agent
-     * resolver EXECUTION is out of scope this slice (ADR D3): `compiled.agents` is
-     * not spread into `Agent.create` by `createSdkAgentStream`; a resolver here is
-     * carried, not invoked. Top-level agent resolvers are the supported path.
-     */
-    systemPrompt?: string | SystemPromptResolver;
-}
-/** Compiled agent options ready for SDK Agent.create(). */
-interface CompiledAgentOptions {
-    model?: string;
-    /** Extended-thinking effort; mapped to SDK ModelSelection.params. */
-    reasoningEffort?: ReasoningEffort;
-    /** Opt-in `<think>`-tag extraction (M2); wraps the stream when true. */
-    parseThinkTags?: boolean;
-    /** Opt-in tool-dialect stripping (theocode#32); strips leaked `<function=…></tool_call>` from text when true. */
-    stripToolDialect?: boolean;
-    /** Opt-in leaked-dialect recovery (theokit#58); enables the SDK route's `extractToolCallsFromContent` so leaked tool calls EXECUTE when true. */
-    recoverLeakedToolCalls?: boolean;
-    /** Static prompt OR a per-request {@link SystemPromptResolver} (V4-L.1, Axis-B). */
-    systemPrompt?: string | SystemPromptResolver;
-    /**
-     * theokit-file-based-config — opt-in `.theokit/` file-based config roots (`"project"`/`"user"`/…).
-     * Projected into `Agent.create({ local: { settingSources } })` by `assembleM8CreateOptions`
-     * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
-     */
-    settingSources?: readonly SettingSource[];
-    /** Code `Plugin` objects forwarded to `Agent.create({ plugins })` (lifecycle-hook seam). */
-    plugins?: readonly unknown[];
-    tools: CompiledTool[];
-    agents: Record<string, CompiledSubAgent>;
-    memory?: MemoryOptions | MemorySettings;
-    skills?: SkillsSettings;
-    context?: ContextSettings;
-    /**
-     * M7 — run-context injected into every tool handler's `ctx.context` by the theokit adapter
-     * (`buildSdkTools` wrapper). Populated by `defineAgent({ context })` (functional surface).
-     * NAME NOTE: distinct from the context-window `context` (`ContextSettings`) above — this is
-     * per-run user data for tools, not token-budget config.
-     */
-    runContext?: Record<string, unknown>;
-    /** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
-    projectContext?: ProjectContextOptions;
-    mcpServers?: McpServersMap;
-    maxIterations?: number;
-    timeoutMs?: number;
-    stream: boolean;
-    /**
-     * HITL gate map (M4): runtime tool name → `@HumanInTheLoop` config. Absent/empty ⇒ no gated
-     * tools. The harness (`mountAgent`) turns this into the `pre_tool_call` pause wiring.
-     */
-    hitl?: Map<string, HumanInTheLoopOptions>;
-    /**
-     * `@Checkpoint` config (M4): when present the harness emits `checkpoint_saved` and selects the
-     * durable SDK conversation storage (`storage: 'filesystem'`) so a same-`sessionId` request resumes.
-     */
-    checkpoint?: CheckpointOptions;
-    /**
-     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
-     * Input guards run on the user message BEFORE the SDK runtime sees it (fail-fast on `block`).
-     * They REUSE the runtime; they never reimplement it. Absent/empty ⇒ no guards.
-     */
-    guardrails?: readonly Guardrail[];
-    /**
-     * M13 — per-request skills resolver (from `defineAgent({ skills: (ctx) => [...] })`). The request
-     * path resolves it against the run-context (`resolveEnabledSkills`) and sets `skills.enabled`
-     * before the SDK runs. Not consumed by the SDK directly (it reads `skills`). Absent ⇒ no resolver.
-     */
-    skillsResolver?: SkillsSelection;
-}
-
 /**
  * M8-3 — compile `@Skills` metadata into the SDK's `SkillsSettings`.
  *
@@ -448,22 +73,12 @@ declare function compileSkills(options: SkillsOptions): SkillsSettings;
  * (ADR D2) instead of silently dropping them (G10 — honest enforcement).
  */
 
-/** How to compact the transcript when `maxTokens` is exceeded. */
-type ContextCompactionStrategy = 'truncate-oldest' | 'summarize-oldest' | 'sliding-window' | 'priority-based';
 /**
  * M53 — declared here, with its conversion, instead of on the decorator being deleted.
  */
 interface ContextWindowOptions {
     /** Maximum tokens before compaction triggers. */
     maxTokens?: number;
-    /** How to compact when maxTokens is exceeded. */
-    compactionStrategy?: ContextCompactionStrategy;
-    /** Always preserve the system prompt during compaction (default: true). */
-    preserveSystemPrompt?: boolean;
-    /** Number of recent messages to always keep intact (default: 10). */
-    preserveLastN?: number;
-    /** Keep all tool results even during compaction (default: true). */
-    preserveToolResults?: boolean;
 }
 interface CompiledContextWindow {
     /** SDK-shaped context budget passed to `Agent.create({ context })`. */
@@ -786,6 +401,31 @@ interface HitlWiring {
     awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
 }
 
+/**
+ * M96 U1 — the approval posture: what a surface does when a gated tool asks for approval.
+ *
+ * ## Why a closed type, and why mandatory
+ *
+ * The defect this module closes was one of TYPE, not of behaviour. The "no HITL" posture was not
+ * representable as a value, so it was expressed as ABSENCE — and an absence has no exhaustive
+ * `match`, appears in no log, and fails no test. `toAgentFactory` compiled the `compiled.hitl` map
+ * that `.approvals({…})` produces and threw it away, with the discard admitted in writing in the
+ * JSDoc, while the sibling bridge REFUSED for the same definition.
+ *
+ * The permissive posture remains entirely expressible — as a NAMED VALUE, with a written reason.
+ * What stops existing is the omission.
+ *
+ * ## Os peers
+ *
+ * `codex` models the posture as a four-variant `enum AskForApproval` in the protocol crate, and
+ * makes forgetting it a compile error through the `ToolRuntime: Approvable + Sandboxable` supertrait;
+ * a mandatory field is the closest this type system gets to that. `codex` also resolves the
+ * ambiguity of omission in the safe direction (`GranularApprovalConfig`: an absent field is
+ * auto-REJECTED, never auto-approved), and names the human's stand-in rather than inferring it from
+ * the absence of one (`ApprovalReviewer::{Guardian, User}`). `opencode` does the same inside out:
+ * an absent rule resolves to `ask`.
+ */
+
 /**
  * What this surface does when a gated tool asks for approval. Four variants, none of them
  * "omission" — each with a concrete consumer and a written reason.
@@ -803,8 +443,26 @@ type ApprovalPosture = {
     /** Resolves the human decision; execution stays paused until this settles. */
     awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
 } | {
-    /** Nobody asks and the tool runs. Legitimate when something else confines the execution. */
+    /** Nobody asks and the tool runs. Legitimate only when something else confines the execution. */
     kind: 'auto-approve';
+    /**
+     * M77 — the EVIDENCE that something else confines the execution. Not optional, and not a
+     * string.
+     *
+     * This is the most consequential decision a coding agent makes — "run commands without
+     * asking" — and until M77 its type asked only for a `reason: string`. A string is
+     * unverifiable at the seam: nothing could tell "confined by bwrap, kernel-enforced" from
+     * "I'm sure it's fine". So the consumer implemented the refusal itself, TWICE
+     * (`shouldAutoApprove` in the TUI, `resolveHeadlessApproval` in the headless path), with the
+     * same rule in both — an absent posture counts as unconfined. A security rule duplicated
+     * across two call sites is a rule that will eventually disagree with itself (G12).
+     *
+     * `SandboxPosture` is the SDK's own honest answer to "am I kernel-enforced right now?", and
+     * it carries `detail` so a refusal can say WHY rather than just "unconfined". Requiring it
+     * makes the unconfined case unrepresentable at the type level; {@link applyPosture} refuses
+     * it at runtime for the caller who casts past the type.
+     */
+    confinedBy: SandboxPosture;
     reason: string;
 } | {
     /** Nobody asks and the tool does NOT run — the safe reading of omission (codex `GranularApprovalConfig`). */
@@ -821,185 +479,6 @@ type ApprovalPosture = {
     reason: string;
 };
 
-/**
- * M82 — the typed shape of `AgentBuilder.create().hooks({...})`.
- *
- * ## Why this type lives here
- *
- * Until M82 the signature was `Readonly<Record<string, unknown>>`: any key was accepted and every
- * handler received `ctx: unknown`. A consumer that wanted types had to declare its own — and that is
- * exactly what agent-builder did, with a local alias of five handlers, four of them carrying
- * `ctx: unknown` because there was nowhere to import the contexts from.
- *
- * It is the same class M81 closed with `discoverSubagents`: framework knowledge reimplemented in the
- * app because the framework did not publish it. The type is born where the knowledge lives.
- *
- * ## About `transform_tool_result`
- *
- * This is the ONLY tool-stage channel whose return value the SDK applies — `#runTransform` folds the
- * returned value in; `#runFireAndForget`, used by `post_tool_call`, discards it. Since M82 its
- * context carries `toolCalls`, so a scoped policy (by tool name) can ACT on the result rather than
- * merely observe it.
- */
-
-/**
- * Lifecycle handlers keyed by `HookName`.
- *
- * Every field is optional: an agent registers only the events it cares about. `.hooks()` accepts the
- * UNION of this type with the earlier loose shape (M82's ADR-4), so no implicit index signature is
- * needed for the value to pass at the call site — the narrowing is gradual, not a break.
- */
-interface HookHandlers {
-    /**
-     * Runs BEFORE the tool. Returning `{ block: true, message }` VETOES the call — the only hook with
-     * veto power.
-     */
-    pre_tool_call?: (ctx: PreToolCallContext) => Promise<PreToolCallDecision | undefined> | PreToolCallDecision | undefined;
-    /**
-     * Runs AFTER the tool, with `{name, args, result}`. Fire-and-forget: the return value is
-     * **discarded** by the SDK. To ACT on the result use {@link transform_tool_result}.
-     */
-    post_tool_call?: (ctx: PostToolCallContext) => Promise<void> | void;
-    /**
-     * Folds the turn's tool results before they go up to the model. Since M82 the context brings
-     * `toolCalls` — plural, because the seam receives the turn's BATCH; correlate by
-     * `toolUseId === id`.
-     */
-    transform_tool_result?: <T>(results: T, ctx: ToolResultTransformContext) => Promise<T> | T;
-    /** Folds the model's text before it is consumed. No tool call involved. */
-    transform_llm_output?: (output: string, ctx: TransformContext) => Promise<string> | string;
-    on_session_start?: (ctx: SessionLifecycleContext) => Promise<void> | void;
-    on_session_end?: (ctx: SessionLifecycleContext) => Promise<void> | void;
-    pre_user_send?: (ctx: PreUserSendContext) => Promise<PreUserSendResult | undefined> | PreUserSendResult | undefined;
-    post_assistant_reply?: (ctx: PostAssistantReplyContext) => Promise<void> | void;
-}
-
-/**
- * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
- *
- * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
- * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
- * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
- * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
- *
- * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
- * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
- * core, preserving the agents → (nothing) dependency direction (G1).
- */
-
-/**
- * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
- * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
- * brand-check then works regardless of which copy created the definition.
- */
-declare const AGENT_BRAND: unique symbol;
-/** Config accepted by {@link defineAgent}. */
-interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
-    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
-    input?: TInput;
-    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
-    model?: string;
-    /** Static system prompt. */
-    system?: string;
-    /** Extended-thinking effort. */
-    reasoningEffort?: ReasoningEffort;
-    /**
-     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
-     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
-     * normalized to the internal {@link CompiledTool} shape at compile time.
-     */
-    tools?: readonly CustomTool[];
-    /**
-     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
-     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
-     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
-     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
-     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
-     */
-    context?: Record<string, unknown>;
-    /**
-     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
-     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
-     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
-     * `unicodeNormalizer`, `outputModeration`).
-     */
-    guardrails?: readonly Guardrail[];
-    /**
-     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
-     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
-     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
-     * compile time.
-     */
-    approvals?: Record<string, HumanInTheLoopOptions>;
-    /**
-     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
-     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
-     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
-     */
-    skills?: SkillsSelection;
-    /**
-     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
-     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
-     * `"project"` = `<cwd>/.theokit/`, `"user"` = `~/.theokit/`. Absent ⇒ inline (code) config only.
-     * SECURITY: enabling `"project"` enables shell-executing hooks from `.theokit/hooks.json` — this
-     * is opt-in because `.theokit/` is the app's own repo (informed consent). The SDK owns discovery
-     * + execution (G2 / ADR-0040); theokit only wires this into `Agent.create({ local.settingSources })`.
-     */
-    settingSources?: readonly SettingSource[];
-    /**
-     * M49 — durable memory (the SDK's `.theokit/memory/` subsystem: `Remember:` capture, MEMORY.md
-     * store, auto-injected `<memory>` block, `memory_search`/`memory_get` tools). The shape is the
-     * SDK's own `MemorySettings` — the canonical runtime contract. Projected into
-     * `Agent.create({ memory })` by `assembleM8CreateOptions`.
-     */
-    memory?: MemorySettings;
-    /**
-     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
-     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
-     */
-    plugins?: readonly unknown[];
-    /**
-     * Lifecycle hooks keyed by `HookName` (`pre_tool_call` may veto via `{ block, message }`). Set by
-     * the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
-     * under this name — the plugin is the TRANSPORT, this is the contract callers write against.
-     */
-    hooks?: HookHandlers | Readonly<Record<string, unknown>>;
-    /**
-     * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
-     * decorator. Each key is a server name; the value is the server configuration. Forwarded
-     * unchanged to `Agent.create({ mcpServers })` (the SDK owns MCP execution). Absent ⇒ no MCP.
-     */
-    mcpServers?: McpServersMap;
-}
-/**
- * A branded agent definition — the value {@link defineAgent} returns.
- *
- * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `AgentBuilder.create()` builder
- * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
- * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
- * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
- * names). Never present at runtime.
- */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
-    readonly [AGENT_BRAND]: true;
-    readonly __toolNames?: TTools;
-};
-/** Infer the request type of an agent definition from its `input` Zod schema. */
-type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
-/**
- * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
- * with the `AgentBuilder.create()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
- * whose tools array carries no literal names.
- */
-type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
-/** Brand-check: is `value` a {@link defineAgent} result? */
-declare function isAgentDefinition(value: unknown): value is AgentDefinition;
-/**
- * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
- * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
- */
-declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
-
 /**
  * A definition, or a THUNK that produces one per session.
  *
@@ -1324,6 +803,26 @@ interface ToolContextError<TRequired> {
 }
 /** The agent context before `.context()` is called — satisfies only tools with no requirement. */
 type EmptyContext = Record<never, never>;
+/**
+ * The union of literal tool names in a tuple of {@link ContextualTool}s.
+ *
+ * Written as a distributed conditional rather than `TList[number]['name']` so an EMPTY list yields
+ * `never` (which unions away, leaving `TTools` untouched) instead of `string` (which would widen the
+ * accumulated union and silently destroy the type-state for the rest of the chain).
+ */
+type ToolNamesOf<TList> = TList extends readonly (infer TElement)[] ? TElement extends ContextualTool<infer TName> ? TName : never : never;
+/**
+ * The combined run-context every tool in the tuple requires.
+ *
+ * The singular `.tool()` guards one `TRequired` against the agent's `TContext`; a list has to guard
+ * ALL of them, so this intersects them. Without it, `.tools([...])` would be a hole in the exact
+ * check `.tool()` performs — a batch API that quietly accepts what the single-item API rejects is
+ * worse than no batch API.
+ *
+ * Intersection, not union: satisfying every element means the agent's context must have what each
+ * one needs. `unknown` (a plain tool) intersects away, so a list of plain tools stays unconstrained.
+ */
+type ToolContextOf<TList> = (TList extends readonly (infer TElement)[] ? TElement extends ContextualTool<string, infer TRequired> ? (required: TRequired) => void : never : never) extends (required: infer TIntersection) => void ? TIntersection : never;
 /**
  * A tool that MAY declare, at the type level, the run-context shape it needs. A plain
  * {@link CustomTool} (`TRequired = unknown`) is satisfied by any agent context. Build one that
@@ -1380,6 +879,38 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * satisfy — set it first with `.context()`.
      */
     tool<TName extends string, TRequired>(tool: ContextualTool<TName, TRequired>, ...guard: TContext extends TRequired ? [] : [error: ToolContextError<TRequired>]): AgentBuilder<TInput, TModel, TContext, TTools | TName>;
+    /**
+     * M69 — add MANY tools at once, accumulating the union of their names.
+     *
+     * The chain only had the singular `.tool()`, so a tool set computed at runtime — the normal case,
+     * since which tools an agent gets depends on sandbox mode, surface profile and trust — could not
+     * be expressed in the chain. The measured workaround was a fold outside it:
+     *
+     *     allTools.reduce((acc, tool) => acc.tool(tool), chain)
+     *
+     * That works and loses the type-state: the accumulated name union collapses, so
+     * `InferAgentToolNames` stops seeing the literal names the generated client is built from. The
+     * escape hatch cost exactly the guarantee the builder exists for.
+     *
+     * An empty list is a typed no-op — `never` unions away, so `TTools` is untouched rather than
+     * widened.
+     */
+    tools<const TList extends readonly ContextualTool[]>(list: TList, ...guard: TContext extends ToolContextOf<TList> ? [] : [error: ToolContextError<ToolContextOf<TList>>]): AgentBuilder<TInput, TModel, TContext, TTools | ToolNamesOf<TList>>;
+    /**
+     * M69 — apply a sub-chain only when `condition` holds, preserving the type-state either way.
+     *
+     * `.use(preset)` composes a whole sub-chain but cannot skip a link in the MIDDLE of one, which is
+     * what a conditional element needs.
+     *
+     * The condition is a plain `boolean`, already computed — never a predicate with access to
+     * context. A predicate would make this a door for business logic inside the authoring chain (the
+     * milestone's named risk); a boolean keeps the decision where the caller made it.
+     *
+     * The returned type is the same on both branches, because the condition is a runtime value and a
+     * type cannot depend on it: the union is what the branch COULD add. That is what lets `.when` sit
+     * mid-chain without collapsing what came before.
+     */
+    when<TResult extends AgentBuilder<TInput, TModel, TContext, string>>(condition: boolean, apply: (builder: AgentBuilder<TInput, TModel, TContext, TTools>) => TResult): TResult;
     /** M9 — add one input/output guardrail (appends). Runs at the framework boundary before the SDK. */
     guardrail(g: Guardrail): AgentBuilder<TInput, TModel, TContext, TTools>;
     /** M9 — set the full guardrail list (replaces any previously added). */
@@ -1401,11 +932,16 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
     skills(selection: SkillsSelection): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
-     * MCP, context, cron), discovered by the SDK from the app root (`"project"` = `<cwd>/.theokit/`,
-     * `"user"` = `~/.theokit/`). Unset ⇒ inline (code) config only. SECURITY: `"project"` enables
-     * shell-executing hooks from `.theokit/hooks.json` — opt-in because `.theokit/` is your own repo.
+     * MCP, context, cron), discovered by the SDK from the app root (`project` = `<cwd>/.theokit/`,
+     * `user` = `~/.theokit/`). Unset ⇒ inline (code) config only.
+     *
+     * SECURITY (M68): takes a {@link SettingSourcesSelection}, not a string array. `project` reads
+     * `.theokit/hooks.json`, which **executes shell**, so it requires a `TrustPosture` as evidence;
+     * `user` is a plain boolean because `~/.theokit/` is the operator's own machine. The previous
+     * signature called `project` "opt-in because `.theokit/` is your own repo" — true for a web app
+     * whose `cwd` is its own deploy, false for an agent pointed at a repository someone else wrote.
      */
-    settingSources(sources: readonly SettingSource[]): AgentBuilder<TInput, TModel, TContext, TTools>;
+    settingSources(selection: SettingSourcesSelection): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * M49 — enable the SDK's durable memory for this agent (`.theokit/memory/` in the run cwd:
      * `Remember:` capture with secret redaction, auto-injected recall, memory tools). Takes the SDK's
@@ -1474,23 +1010,17 @@ declare const AgentBuilder: {
     create(): AgentBuilder;
 };
 
+/** Thrown when an `agents/` file default-exports neither a `defineAgent` value nor an `@Agent` class. */
 /**
- * M2 (theokit-ai-first) — the file-convention runtime bridge.
- *
- * Turns a loaded `agents/<name>.ts` module into the M0/M1 canonical `UIMessageStream`:
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`.
  *
- *   module (defineAgent value | @Agent class) ──compileAgentModule──▶ CompiledAgentOptions
- *   CompiledAgentOptions ──createSdkAgentStream──▶ AgentStreamEvent* ──translate──▶ UIMessageChunk*
- *
- * Both agent surfaces converge here (ADR-B1): a `defineAgent` value lowers via
- * `compileAgentDefinition`, an `@Agent`-decorated class lowers via `compileAgent`
- * (which requires the full `@MainLoop` decoration — its existing errors surface for
- * DI-heavy classes). Neither runs an LLM directly — `@theokit/sdk` stays the sole
- * runtime (G2 / sdk-runtime.md); this module only wires its output onto the wire.
+ * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
+ * INVISIBLE to it and the only recourse left to a consumer is matching on message text. `code` is
+ * stable across a rename; `isRetryable` is DECLARED, because a default would be a retry policy
+ * nobody chose.
  */
-
-/** Thrown when an `agents/` file default-exports neither a `defineAgent` value nor an `@Agent` class. */
-declare class AgentDefinitionError extends Error {
+declare class AgentDefinitionError extends TheokitAgentError {
+    readonly name = "AgentDefinitionError";
     constructor(source: string);
 }
 declare function compileAgentModule(mod: unknown, source?: string): CompiledAgentOptions;
@@ -1623,18 +1153,6 @@ type LoopStrategyConfig = z.infer<typeof loopStrategyConfigSchema>;
  */
 declare function resolveLoopStrategy(strategy: string, maxIterations?: number): LoopStrategy;
 
-/**
- * Shared delegation value types + typed errors.
- *
- * Extracted from `agent-orchestrator.ts` so BOTH the orchestrator (`delegate`)
- * and the loop driver (`loop/run-reflective-loop.ts`) can import them WITHOUT a
- * cycle (orchestrator → loop → delegation-types; orchestrator → delegation-types;
- * delegation-types has only a TYPE-ONLY import of `LoopFinishReason` (erased at
- * runtime → no runtime edge; `loop-strategy.ts` is a leaf importing only zod, so
- * no cycle — Acyclic Dependencies Principle, G1).
- * `agent-orchestrator.ts` re-exports these for backward compatibility.
- */
-
 interface DelegationResult {
     response: string;
     toolCalls: {
@@ -1677,10 +1195,19 @@ interface DelegationResult {
  * `subpath-coverage.test.ts` recorded the collision as a `gap` on `./errors`, with the reason written
  * down and the acknowledgement that renaming was breaking and out of M78's scope. M91 paid the bill.
  */
-declare class DelegationBudgetExceededError extends Error {
+/**
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ *
+ * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
+ * INVISIBLE to it and the only recourse left to a consumer is matching on message text. `code` is
+ * stable across a rename; `isRetryable` is DECLARED, because a default would be a retry policy
+ * nobody chose.
+ */
+declare class DelegationBudgetExceededError extends TheokitAgentError {
     readonly agentName: string;
     readonly actualCost: number;
     readonly budgetLimit: number;
+    readonly name = "DelegationBudgetExceededError";
     constructor(agentName: string, actualCost: number, budgetLimit: number);
 }
 /**
@@ -1691,9 +1218,18 @@ declare class DelegationBudgetExceededError extends Error {
 declare const BudgetExceededError: typeof DelegationBudgetExceededError;
 /** @deprecated Use {@link DelegationBudgetExceededError}. */
 type BudgetExceededError = DelegationBudgetExceededError;
-declare class DelegationError extends Error {
+/**
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ *
+ * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
+ * INVISIBLE to it and the only recourse left to a consumer is matching on message text. `code` is
+ * stable across a rename; `isRetryable` is DECLARED, because a default would be a retry policy
+ * nobody chose.
+ */
+declare class DelegationError extends TheokitAgentError {
     readonly agentName: string;
     readonly cause: unknown;
+    readonly name = "DelegationError";
     constructor(agentName: string, cause: unknown);
 }
 
@@ -1804,6 +1340,15 @@ type RoundStreamFactory = (message: string, sessionId: string, opts?: {
  */
 
 interface DelegateOptions {
+    /**
+     * M81 — wall-clock cap for the delegation, in milliseconds. Absent ⇒ no clock cap.
+     *
+     * A DIFFERENT guard from `budget`: money is spent by work that progresses, and a delegation that
+     * HANGS burns clock without spending a cent. A consumer wrote its own timeout race with its own
+     * typed error because this was missing. Exceeding it raises `DelegationTimeoutError`, which —
+     * unlike the budget errors — is marked retryable, because a hang is often transient.
+     */
+    readonly timeoutMs?: number;
     /** Max USD for this sub-agent call. */
     budget?: number;
     /** Parent's remaining budget (for clamping). */
@@ -2043,6 +1588,22 @@ declare function createApiErrorHandler<R = unknown>(policy: ApiErrorPolicy<R>):
  * SubAgent class or an LLM — and so it NEVER re-implements the delegation runtime.
  */
 
+/**
+ * M81 — anything that can run a delegation.
+ *
+ * The reach gap this closes: both wrappers took a `SubAgentSpec` produced by the capability
+ * compiler, so a consumer holding an SDK `SubAgent` or `Squad` could not feed them. That is why the
+ * scoring loop — the layer's highest-value piece — had ZERO adoption in a product that runs an
+ * explicit review pass: it was unreachable from the primitives that product actually holds.
+ *
+ * An SDK `SubAgent` or `Squad` satisfies this by having `run`. So does a test double, which is why
+ * the loop is now testable without a compiler, a class or an LLM.
+ */
+interface DelegationPort {
+    run(message: string): Promise<DelegationResult>;
+}
+/** What both wrappers accept: the compiled spec (unchanged) or the port (M81, additive). */
+type DelegationTarget = SubAgentSpec | DelegationPort;
 /** The delegation primitive both wrappers drive. Defaults to the M12 {@link delegate}. */
 type DelegateFn = (subAgent: SubAgentSpec, message: string, opts?: DelegateOptions) => Promise<DelegationResult>;
 /** A running background delegation the supervisor can await/poll later. */
@@ -2057,7 +1618,7 @@ interface BackgroundDelegation {
  * supervisor keeps working and calls `wait()` when it needs the result. A thin async wrapper over
  * `delegate` — not a scheduler (Top-risk 1). Rejections are still observable via `wait()`.
  */
-declare function delegateBackground(subAgent: SubAgentSpec, message: string, opts?: DelegateOptions & {
+declare function delegateBackground(subAgent: DelegationTarget, message: string, opts?: DelegateOptions & {
     delegateFn?: DelegateFn;
 }): BackgroundDelegation;
 /** A scorer's verdict on a sub-agent result. `feedback` is fed back into the next round on failure. */
@@ -2085,13 +1646,69 @@ interface ScoredDelegation {
  * `maxRounds` is reached. Each round is ONE `delegate` call — no second loop, no new store. Returns
  * the final result (passing, or the last attempt) with the per-round verdict trail.
  */
-declare function delegateWithScoring(subAgent: SubAgentSpec, message: string, opts: DelegateOptions & {
+declare function delegateWithScoring(subAgent: DelegationTarget, message: string, opts: DelegateOptions & {
     scorer: Scorer;
     maxRounds?: number;
     delegateFn?: DelegateFn;
     feedbackTemplate?: (message: string, feedback: string) => string;
 }): Promise<ScoredDelegation>;
 
+/**
+ * M81 — the two gaps around a delegation's LIFE, as opposed to its execution.
+ *
+ * The execution engine was supplied and works. What was missing sits either side of it:
+ *
+ * - **a clock cap.** `budget` is money only, and a delegation that HANGS burns clock, not dollars.
+ *   So a consumer wrote its own timeout race with its own typed error — mechanism, re-derived.
+ * - **disposal with an owner.** `delegate()` never creates disposable agents, so every site that
+ *   does — a squad, an ephemeral reviewer — hand-wrote acquire/dispose. Both of those files carried
+ *   a bug-fix comment about `finally` semantics, which is what "we got this wrong once" looks like
+ *   when the correct version lives nowhere in particular.
+ */
+/**
+ * Raised when a delegation exceeds its wall-clock cap.
+ *
+ * A distinct class from the budget error on purpose: "you spent your dollars" and "you ran out of
+ * time" call for different responses, and a caller that cannot tell them apart retries the one that
+ * will hang again.
+ */
+declare class DelegationTimeoutError extends TheokitAgentError {
+    readonly name = "DelegationTimeoutError";
+    constructor(subAgent: string, timeoutMs: number);
+}
+/**
+ * Race a delegation against a wall clock.
+ *
+ * The timer is cleared on both paths: a pending `setTimeout` keeps the event loop alive, and a CLI
+ * that finishes its work and then sits for thirty seconds looks broken in a way nobody connects back
+ * to a delegation cap.
+ */
+declare function withClockCap<T>(promise: Promise<T>, timeoutMs: number, subAgent: string): Promise<T>;
+/** An agent that must be released, and the release. */
+interface EphemeralAgent<TAgent> {
+    readonly agent: TAgent;
+    readonly dispose: () => void | Promise<void>;
+}
+/**
+ * Run `body` against a freshly created agent and dispose it afterwards, whatever happens.
+ *
+ * ## Why the disposal cannot mask the result
+ *
+ * `Promise.allSettled` semantics, named by the milestone: the body's outcome — value OR error — is
+ * what the caller receives, and a failing `dispose` never replaces it.
+ *
+ * A cleanup that threw over a successful run would report a teardown error for work that actually
+ * succeeded. Worse, a cleanup that threw over a FAILED run would replace the real failure with the
+ * teardown one, and the diagnosis the caller needed is gone. That asymmetry is precisely what the
+ * two hand-written call sites got wrong, each with its own bug-fix comment about `finally`.
+ *
+ * The disposal error is not silently swallowed either — it is reported through `onDisposeError`, so
+ * a leak is observable without competing with the result.
+ */
+declare function withEphemeralAgent<TAgent, TResult>(create: () => EphemeralAgent<TAgent> | Promise<EphemeralAgent<TAgent>>, body: (agent: TAgent) => Promise<TResult>, options?: {
+    readonly onDisposeError?: (error: unknown) => void;
+}): Promise<TResult>;
+
 /**
  * M24 (ADR-0041) — MCP follow-ups, framework-side layer over the `@MCP` config (ADR-0040 § D2).
  *
@@ -2182,100 +1799,6 @@ declare class McpFileError extends TheokitAgentError {
  */
 declare function loadMcpJson(cwd: string, opts?: LoadMcpJsonOptions): McpServersMap;
 
-/**
- * M68 — the trust gate for `settingSources`.
- *
- * ## The defect this module closes
- *
- * `settingSources` enables on-disk config discovery. `'user'` reads `~/.theokit/` — the operator's
- * own machine, which no third party controls. `'project'` reads `<cwd>/.theokit/`, **including
- * `hooks.json`, which executes shell**.
- *
- * The previous API took `readonly SettingSource[]`, and its JSDoc justified the risk this way:
- * *"it is opt-in because `.theokit/` is the app's own repo (informed consent)"*. That premise holds
- * for a web app whose `cwd` is its own deploy. It does **not** hold for the class of product this
- * framework addresses — an agent whose `cwd` is a repository the user just cloned. There `.theokit/`
- * is attacker-controlled content, and enabling `'project'` is remote code execution on the first
- * `build()`.
- *
- * Documenting it did not prevent it. The measured consumer (TheoCode) did not trust the API: it
- * gated from the outside, with a `posture.allows` of its own (`chat.ts:386`, comment B-008). It
- * already **had** the right decision and could not pass it through, because the API only accepted
- * strings. The gate existed on its side and evaporated at the boundary.
- *
- * ## The evidence is the SDK's, not one invented here
- *
- * `TrustPosture` is `@theokit/sdk`'s own trust primitive, and `recordWiring`'s doc says *"a posture
- * is the only thing in this package that retains a capability"*. A bespoke type would make two trust
- * grammars coexist and drift apart (ADR 0063).
- */
-/**
- * The framework's capability vocabulary — deliberately a single name (ADR 0065).
- *
- * `allows` is all-or-nothing in the SDK: every declared `K` gets the same boolean. A finer
- * vocabulary (`hooks`, `skills`, `subagents`, `mcp`) would promise the consumer it can gate one
- * without gating the other, and the primitive does not deliver that. An API that suggests a
- * distinction the runtime does not make teaches the wrong thing, and the error only surfaces when
- * somebody depends on the distinction.
- */
-type SettingSourceCapability = 'projectSettings';
-/** Authorization to read config from the working directory. Requires the posture, never a claim. */
-interface ProjectSettingsGrant {
-    /**
-     * Typically the output of `resolveTrustPosture` — which is what gives it `source` (`'env' |
-     * 'store' | 'default'`) and therefore a refusal that says WHERE the decision came from instead of
-     * merely denying.
-     */
-    readonly trustedBy: TrustPosture<SettingSourceCapability>;
-}
-/**
- * Which on-disk config roots the agent may read.
- *
- * The asymmetry is the design: `user` is a boolean because `~/.theokit/` belongs to the operator;
- * `project` requires evidence because `<cwd>/.theokit/` may not. Omitting a root is not enabling it
- * — never "enabling without a gate". The asymmetry is inherited from the SDK itself, whose
- * `TrustPostureInput.envOverride` documents that `false` and `undefined` both mean "the operator did
- * not turn it on", not "turned it off".
- */
-interface SettingSourcesSelection {
-    /** `~/.theokit/` — the operator's machine. No gate: no third party controls it. */
-    readonly user?: boolean;
-    /** `<cwd>/.theokit/` — controlled by whoever wrote the open repository. Requires evidence. */
-    readonly project?: ProjectSettingsGrant;
-}
-/**
- * Refusal to read the working directory for lack of trust.
- *
- * Descends from `TheokitAgentError` because typed errors are an unbreakable rule here — and because
- * `isTransientError` only sees this hierarchy. A class extending plain `Error` would be invisible to
- * the predicate that separates recoverable from unrecoverable (the defect M67 fixed in five
- * classes).
- */
-declare class UntrustedSettingSourceError extends TheokitAgentError {
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    readonly trustSource: string;
-    /** The refused capability. */
-    readonly capability: SettingSourceCapability;
-    readonly name = "UntrustedSettingSourceError";
-    constructor(message: string, 
-    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
-    trustSource: string, 
-    /** The refused capability. */
-    capability: SettingSourceCapability);
-}
-/**
- * Translate the declared selection into the `SettingSource`s the SDK accepts, refusing what the
- * posture does not authorize.
- *
- * Refuses rather than ignores (ADR 0064). Ignoring would leave the product running in the belief
- * that the repository's hooks are active — a silent failure mode, on the wrong side. The SDK already
- * picked that side for the same problem: `recordWiring` throws `UngatedCapabilityError` when
- * somebody registers a capability the posture does not gate.
- *
- * @throws {UntrustedSettingSourceError} when `project` is requested and the posture does not grant it.
- */
-declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly SettingSource[];
-
 /**
  * Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
  *
@@ -2421,4 +1944,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type DelegateOptions as $, type ApprovalOptions as A, type ApiErrorDecision as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApiErrorPolicy as E, type ApprovalRequiredEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactChunkEvent as I, type ArtifactStartEvent as J, type BackgroundDelegation as K, type LoopStrategy as L, type MainLoopMeta as M, type BeforeToolCallContext as N, BudgetExceededError as O, type BudgetOptions as P, type CheckpointSavedEvent as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, type CompiledContextWindow as U, ContextualTool as V, CostBudgetExceededError as W, DEFAULT_MAX_ITERATIONS as X, type DefineAgentConfig as Y, type DefinitionOrThunk as Z, type DelegateFn as _, type CompiledTool as a, compileSkills as a$, DelegationBudgetExceededError as a0, DelegationError as a1, type DoneEvent as a2, type ErrorEvent as a3, type FileEditEvent as a4, type GuardrailAction as a5, type GuardrailPhase as a6, type GuardrailResult as a7, GuardrailViolationError as a8, type HookHandlers as a9, type SdkMessage as aA, type SdkSendOptions as aB, type SdkTurnHandle as aC, type Segment as aD, type SettingSourceCapability as aE, type SettingSourcesSelection as aF, type SkillsRequestContext as aG, type SkillsSelection as aH, type StateUpdateEvent as aI, type TextDeltaEvent as aJ, type ThinkingEvent as aK, type TimeoutAction as aL, type ToolCallEvent as aM, type ToolCallVeto as aN, type ToolHooks as aO, type ToolHooksPlugin as aP, type ToolResultEvent as aQ, type ToolWalkResult as aR, type ToolboxOptions as aS, type ToolboxWalkResult as aT, UntrustedSettingSourceError as aU, agentsPlugin as aV, buildModelSelection as aW, compileAgentDefinition as aX, compileAgentModule as aY, compileContextWindow as aZ, compileProjectContext as a_, type InferAgentInput as aa, type InferAgentToolNames as ab, type IterationEvent as ac, type LLMCallContext as ad, type LoopFinishReason as ae, type LoopOutcome as af, type LoopStrategyConfig as ag, type MainLoopOptions as ah, type McpApprovalSpec as ai, McpFileError as aj, type McpRegistryConfig as ak, type McpRequestContext as al, type McpSelection as am, type McpServersMap as an, type PartialToolCallEvent as ao, type PolicyHandler as ap, type ProcessInputContext as aq, type ProjectSettingsGrant as ar, type ReflectionContext as as, type ReflectionResult as at, type ReflectionStrategyConfig as au, type RunStartedEvent as av, type ScoreVerdict as aw, type ScoredDelegation as ax, type Scorer as ay, type SdkAgentHandle as az, type ReasoningEffort as b, compileTools as b0, createAgentExecutionContext as b1, createApiErrorHandler as b2, createSdkAgentStream as b3, createThinkTagExtractor as b4, createToolHooksPlugin as b5, delegate as b6, delegateBackground as b7, delegateWithScoring as b8, extractThinkTagStream as b9, streamAgentResponse as bA, toAgentFactory as bB, translateSdkEvent as bC, generateAgentManifest as ba, generateAgentRoutes as bb, isAgentContext as bc, isAgentDefinition as bd, isApprovalRequired as be, isDone as bf, isError as bg, isPartialToolCall as bh, isTextDelta as bi, isToolCall as bj, isToolResult as bk, ladderReflectionStrategy as bl, loadMcpJson as bm, loopStrategyConfigSchema as bn, mcpRegistry as bo, mcpToolApprovals as bp, noopReflectionStrategy as bq, presentUIMessageStream as br, projectContextMetadataOnlyKnobs as bs, reasoningEffortOf as bt, reflectionStrategyConfigSchema as bu, resolveEnabledSkills as bv, resolveLoopStrategy as bw, resolveMcpServers as bx, resolveSettingSources as by, runWithApiErrorHandling as bz, type RoundStreamFactory as c, type ContextWindowOptions as d, type SkillsOptions as e, type AgentManifestEntry as f, type HitlDecision as g, type ApprovalPosture as h, AGENT_BRAND as i, type AfterToolCallContext as j, AgentBuilder as k, type AgentDefinition as l, AgentDefinitionError as m, type AgentExecutionContext as n, type AgentManifest as o, type AgentManifestSource as p, type AgentManifestTool as q, type AgentOptions as r, streamAgentUIMessages as s, type AgentRoute as t, type AgentRouteContext as u, type AgentRunInfo as v, type AgentStreamEvent as w, type AgentTurnMetadata as x, type AgentsPluginOptions as y, type ApiErrorContext as z };
+export { type LoopStrategyConfig as $, type AgentManifestEntry as A, type BackgroundDelegation as B, type ContextWindowOptions as C, type DelegationResult as D, type CompiledContextWindow as E, ContextualTool as F, DEFAULT_MAX_ITERATIONS as G, type HitlDecision as H, type DefinitionOrThunk as I, type DelegateFn as J, type DelegateOptions as K, type LoopStrategy as L, DelegationBudgetExceededError as M, DelegationError as N, type DelegationPort as O, type DelegationTarget as P, DelegationTimeoutError as Q, type ReflectionStrategy as R, type StreamEvent as S, type DoneEvent as T, type EphemeralAgent as U, type ErrorEvent as V, type FileEditEvent as W, type IterationEvent as X, type LLMCallContext as Y, type LoopFinishReason as Z, type LoopOutcome as _, type RoundStreamFactory as a, resolveMcpServers as a$, type McpApprovalSpec as a0, McpFileError as a1, type McpRegistryConfig as a2, type McpRequestContext as a3, type McpSelection as a4, type PartialToolCallEvent as a5, type ProcessInputContext as a6, type ReflectionContext as a7, type ReflectionResult as a8, type ReflectionStrategyConfig as a9, createThinkTagExtractor as aA, createToolHooksPlugin as aB, delegate as aC, delegateBackground as aD, delegateWithScoring as aE, extractThinkTagStream as aF, generateAgentManifest as aG, generateAgentRoutes as aH, isAgentContext as aI, isApprovalRequired as aJ, isDone as aK, isError as aL, isPartialToolCall as aM, isTextDelta as aN, isToolCall as aO, isToolResult as aP, ladderReflectionStrategy as aQ, loadMcpJson as aR, loopStrategyConfigSchema as aS, mcpRegistry as aT, mcpToolApprovals as aU, noopReflectionStrategy as aV, presentUIMessageStream as aW, projectContextMetadataOnlyKnobs as aX, reasoningEffortOf as aY, reflectionStrategyConfigSchema as aZ, resolveLoopStrategy as a_, type RunStartedEvent as aa, type ScoreVerdict as ab, type ScoredDelegation as ac, type Scorer as ad, type SdkAgentHandle as ae, type SdkMessage as af, type SdkSendOptions as ag, type SdkTurnHandle as ah, type Segment as ai, type StateUpdateEvent as aj, type TextDeltaEvent as ak, type ThinkingEvent as al, type ToolCallEvent as am, type ToolCallVeto as an, type ToolHooks as ao, type ToolHooksPlugin as ap, type ToolResultEvent as aq, agentsPlugin as ar, buildModelSelection as as, compileAgentModule as at, compileContextWindow as au, compileProjectContext as av, compileSkills as aw, createAgentExecutionContext as ax, createApiErrorHandler as ay, createSdkAgentStream as az, type SkillsOptions as b, runWithApiErrorHandling as b0, streamAgentResponse as b1, toAgentFactory as b2, translateSdkEvent as b3, withClockCap as b4, withEphemeralAgent as b5, type ApprovalPosture as c, type AfterToolCallContext as d, AgentBuilder as e, AgentDefinitionError as f, type AgentExecutionContext as g, type AgentManifest as h, type AgentManifestSource as i, type AgentManifestTool as j, type AgentRoute as k, type AgentRouteContext as l, type AgentRunInfo as m, type AgentStreamEvent as n, type AgentTurnMetadata as o, type AgentsPluginOptions as p, type ApiErrorContext as q, type ApiErrorDecision as r, streamAgentUIMessages as s, type ApiErrorPolicy as t, type ApprovalRequiredEvent as u, type ArtifactChunkEvent as v, type ArtifactStartEvent as w, type BeforeToolCallContext as x, BudgetExceededError as y, type CheckpointSavedEvent as z };