@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/providers.js

@@ -1,10 +1,10 @@
-export { getProviderProfile, listProviders } from './chunk-UTSRIDKZ.js';
-import './chunk-WLQNMXQE.js';
-import './chunk-2QDYBS2A.js';
-import './chunk-C3NT3PVE.js';
-import './chunk-3OR54XG4.js';
-import './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+export { getProviderProfile, listProviders } from './chunk-XYFGKVZ7.js';
+import './chunk-VWUXIVEI.js';
+import './chunk-AGACYRJ2.js';
+import './chunk-JMDDYA22.js';
+import './chunk-V22DZIXO.js';
+import './chunk-NJWYQWDL.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=providers.js.map
 //# sourceMappingURL=providers.js.map

package/dist/registry-BZQFYRTL.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+var chunkKVSAY6NZ_cjs = require('./chunk-KVSAY6NZ.cjs');
+require('./chunk-BUUUWQMB.cjs');
+require('./chunk-KTTHHYEW.cjs');
+require('./chunk-HCT4HPCL.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "__getSubscribersCountForTests", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.__getSubscribersCountForTests; }
+});
+Object.defineProperty(exports, "__resetTaskRegistryForTests", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.__resetTaskRegistryForTests; }
+});
+Object.defineProperty(exports, "cancel", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.cancel; }
+});
+Object.defineProperty(exports, "configure", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.configure; }
+});
+Object.defineProperty(exports, "get", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.get; }
+});
+Object.defineProperty(exports, "list", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.list; }
+});
+Object.defineProperty(exports, "submit", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.submit; }
+});
+Object.defineProperty(exports, "subscribe", {
+  enumerable: true,
+  get: function () { return chunkKVSAY6NZ_cjs.subscribe; }
+});
+//# sourceMappingURL=registry-BZQFYRTL.cjs.map
+//# sourceMappingURL=registry-BZQFYRTL.cjs.map

package/dist/{registry-V7BDQ6QB.cjs.map → registry-BZQFYRTL.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"registry-V7BDQ6QB.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"registry-BZQFYRTL.cjs"}

package/dist/registry-DMWCJKRF.js

@@ -0,0 +1,9 @@
+export { __getSubscribersCountForTests, __resetTaskRegistryForTests, cancel, configure, get, list, submit, subscribe } from './chunk-K2VMFZQ5.js';
+import './chunk-K2BQQ445.js';
+import './chunk-G7BLGBRN.js';
+import './chunk-EIQFAOFD.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=registry-DMWCJKRF.js.map
+//# sourceMappingURL=registry-DMWCJKRF.js.map

package/dist/{registry-75W33OGL.js.map → registry-DMWCJKRF.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"registry-75W33OGL.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"registry-DMWCJKRF.js"}

package/dist/retry.cjs

@@ -1,15 +1,14 @@
 'use strict';
 
-var chunk4PYZ5AX3_cjs = require('./chunk-4PYZ5AX3.cjs');
-require('./chunk-4ZHTIJNE.cjs');
-require('./chunk-XL7Q7HB2.cjs');
-require('./chunk-EG4QM7ZJ.cjs');
+var chunkPRZ3BES7_cjs = require('./chunk-PRZ3BES7.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
 
 
 
 Object.defineProperty(exports, "Retry", {
   enumerable: true,
-  get: function () { return chunk4PYZ5AX3_cjs.Retry; }
+  get: function () { return chunkPRZ3BES7_cjs.Retry; }
 });
 //# sourceMappingURL=retry.cjs.map
 //# sourceMappingURL=retry.cjs.map

package/dist/retry.d.cts

@@ -6,15 +6,30 @@
  * The default retry predicate is `isTransientError`, so retries follow the
  * SDK's own error classification.
  */
-import { type RetryOptions } from "./internal/runtime/retry/with-retry.js";
+import { type RetryOptions } from "./internal/retry/with-retry.js";
 export type { RetryOptions };
 /**
- * SE36 — `Retry.create` replaces `withRetry` (ADR 0015 / ADR-P2). NOTE: `withRetry` is an
- * EXECUTOR, not a constructor — `Retry.create(fn, opts)` RUNS `fn` with retry and resolves to
- * its result (`Promise<T>`), not a `Retry` instance. The `.create` name is the uniformity
- * mandate; the executor semantics are the documented, accepted awkwardness. @public
+ * SE36 — replaces `withRetry` (ADR 0015 / ADR-P2).
+ *
+ * `Retry` is a static NAMESPACE, not a factory: the uniformity mandate spells every public entry
+ * point `X.create(...)` so callers learn one verb, and twelve classes in this package follow it.
+ *
+ * This is the one place the mandate produced a false name, and it is fixed here rather than by
+ * unwinding the mandate — consistency across a published API is worth more than the indirection.
+ * `withRetry` is an EXECUTOR: it RUNS `fn` and resolves to `fn`'s result, so `create` named a
+ * construction that never happens. `run` is the honest spelling and `create` is a deprecated alias,
+ * because removing a published member is a major-version decision and the alias is what carries the
+ * correction to a caller's editor in the meantime.
+ *
+ * @public
  */
 export declare class Retry {
     private constructor();
+    /** Run `fn`, retrying per `options`. Resolves to `fn`'s result. */
+    static run<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * @deprecated Renamed to {@link Retry.run}. This never created anything — it runs `fn` and
+     * resolves to its result — and the name said otherwise. Still honoured; removed in the next major.
+     */
     static create<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 }

package/dist/retry.d.ts

@@ -6,15 +6,30 @@
  * The default retry predicate is `isTransientError`, so retries follow the
  * SDK's own error classification.
  */
-import { type RetryOptions } from "./internal/runtime/retry/with-retry.js";
+import { type RetryOptions } from "./internal/retry/with-retry.js";
 export type { RetryOptions };
 /**
- * SE36 — `Retry.create` replaces `withRetry` (ADR 0015 / ADR-P2). NOTE: `withRetry` is an
- * EXECUTOR, not a constructor — `Retry.create(fn, opts)` RUNS `fn` with retry and resolves to
- * its result (`Promise<T>`), not a `Retry` instance. The `.create` name is the uniformity
- * mandate; the executor semantics are the documented, accepted awkwardness. @public
+ * SE36 — replaces `withRetry` (ADR 0015 / ADR-P2).
+ *
+ * `Retry` is a static NAMESPACE, not a factory: the uniformity mandate spells every public entry
+ * point `X.create(...)` so callers learn one verb, and twelve classes in this package follow it.
+ *
+ * This is the one place the mandate produced a false name, and it is fixed here rather than by
+ * unwinding the mandate — consistency across a published API is worth more than the indirection.
+ * `withRetry` is an EXECUTOR: it RUNS `fn` and resolves to `fn`'s result, so `create` named a
+ * construction that never happens. `run` is the honest spelling and `create` is a deprecated alias,
+ * because removing a published member is a major-version decision and the alias is what carries the
+ * correction to a caller's editor in the meantime.
+ *
+ * @public
  */
 export declare class Retry {
     private constructor();
+    /** Run `fn`, retrying per `options`. Resolves to `fn`'s result. */
+    static run<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * @deprecated Renamed to {@link Retry.run}. This never created anything — it runs `fn` and
+     * resolves to its result — and the name said otherwise. Still honoured; removed in the next major.
+     */
     static create<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 }

package/dist/retry.js

@@ -1,6 +1,5 @@
-export { Retry } from './chunk-RFXWMRFC.js';
-import './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+export { Retry } from './chunk-EFMFILPG.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=retry.js.map
 //# sourceMappingURL=retry.js.map

package/dist/{run-BYSHf58D.d.ts → run-CTAdRU3U.d.cts}

@@ -1,6 +1,10 @@
 import * as zod from 'zod';
 
 /**
+ * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
+ * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
+ * pointing it at a subsystem would name something that does not use it.
+ *
  * Type-leaf — base message types shared between `conversation.ts` and
  * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
  * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06
@@ -21,6 +25,12 @@ interface UserMessage {
     text: string;
 }
 
+/**
+ * Owner: `internal/agent-loop/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+
 /**
  * Single tool call event. The internal `args` and `result` shapes are NOT stable.
  *
@@ -201,148 +211,9 @@ interface ShellOutputDeltaUpdate {
 type InteractionUpdate = TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate;
 
 /**
- * `PermissionEngine` — first-match permission rules for tool invocations.
- *
- * Evaluates a tool name (and optional arguments, #55) against an ordered list
- * of rules. First matching rule wins; when no rule matches the `defaultAction`
- * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
- * engine that cannot positively allow must not silently allow. Opt back into
- * the previous fail-open behavior with `{ defaultAction: "allow" }`.
- */
-type PermissionAction = "allow" | "deny" | "ask";
-/**
- * SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
- * A PURE post-processor of the verdict (no tool-safety metadata needed, so it fits
- * a bring-your-own-tools runtime). Grounded in a peer project (plan agent = deny-all,
- * `dangerously-skip-permissions`) + Codex (`AskForApproval`: `OnRequest` default,
- * `Never`, `UnlessTrusted`). See {@link applyMode} for the exact table.
- *
- * - `default` — verdict as-is (rules decide; unmatched ⇒ `ask`, fail-closed).
- * - `plan` — read-only: `allow` rules pass, everything else ⇒ `deny` (mutations blocked).
- *   NOTE: `plan` gates on the resolved verdict, so an engine configured with
- *   `{ defaultAction: "allow" }` still yields `allow` for UNMATCHED calls under
- *   `plan` — pair `plan` with the default fail-closed engine (`defaultAction: "ask"`)
- *   for full read-only behavior.
- * - `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
- *   `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
- * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
- *   `allow` EXCEPT an explicit `deny` rule. Never asks. a peer project
- *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
- */
-type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
-/**
- * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
- *
- * `explicit` is `true` when the verdict came from a rule that matched by name (and
- * args), `false` when it is the fail-closed default for an unmatched call. The flag
- * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
- * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
- *
- * INVARIANT (both a peer project + Codex): an explicit `deny` is immune to EVERY
- * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
- */
-declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
-/**
- * #55 — an argument matcher. A rule with `args` gates on the tool's argument
- * VALUES, not just its name: an exact string, a RegExp (tested against the
- * stringified value), or a predicate. Every declared arg must match for the
- * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
- * a destructive shell call while leaving `ls` to fall through.
- */
-type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
-/**
- * One entry in a {@link PermissionEngine}'s ordered rule list.
- *
- * Order is the semantics. The engine walks the list and the first rule whose `tool` matches — and
- * whose `args` matchers all pass, when it declares any — decides; nothing after it is consulted. Put
- * the narrow rules first: a catch-all `tool` RegExp placed above a specific deny makes that deny
- * unreachable, and nothing warns you.
- *
- * `args` is what lets one tool name resolve differently depending on what it is asked to do —
- * `{ tool: "shell", args: { command: /rm\s+-rf/ }, action: "deny" }` blocks the destructive call and
- * leaves `ls` to fall through to a later rule. Every declared matcher must pass.
- *
- * **A missing argument is NOT handled uniformly, and the difference bites in the unsafe direction.**
- * For a string or RegExp matcher, an argument the call did not supply fails the matcher, so the rule
- * does not match and evaluation continues. For a PREDICATE matcher the function is called anyway,
- * with `undefined`:
- *
- * ```ts
- * { tool: "shell", args: { command: (v) => v !== "prod" }, action: "allow" }
- * // evaluate("shell", {}) → the predicate gets `undefined`, returns true, the rule MATCHES,
- * // and a call that supplied no arguments at all is authorized.
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
  *
- * { tool: "shell", args: { command: (v) => v.includes("rm") }, action: "deny" }
- * // evaluate("shell", {}) → TypeError thrown out of the permission gate.
- * ```
- *
- * Until that is fixed (issue #367), guard the parameter in every predicate you write —
- * `(v) => typeof v === "string" && v !== "prod"` — rather than relying on the matcher never being
- * reached.
- *
- * A rule that matches yields an EXPLICIT verdict, and that is what makes it survive a permissive
- * `PermissionMode`: `acceptEdits` auto-approves the unmatched default but still honours an explicit
- * `ask` rule, and an explicit `deny` is immune to every mode, `bypass` included.
- */
-interface PermissionRule {
-    /** Tool name (exact string) or pattern (RegExp). */
-    tool: string | RegExp;
-    /**
-     * #55 — optional per-argument matchers. When present, the rule matches only
-     * if the tool name matches AND every declared arg predicate matches the
-     * corresponding call argument. A missing/undefined arg fails its predicate
-     * (the rule does not match) — never throws.
-     */
-    args?: Record<string, ArgMatcher>;
-    /** Action to take when rule matches. */
-    action: PermissionAction;
-}
-/** Options for {@link PermissionEngine}. */
-interface PermissionEngineOptions {
-    /**
-     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
-     * permission engine that cannot positively allow must not silently allow.
-     * Pass `"allow"` to restore the previous fail-open behavior.
-     */
-    readonly defaultAction?: PermissionAction;
-}
-/**
- * Ordered first-match permission rules for tool invocations — the policy object you hand to
- * `PermissionPlugin.create()` to have it enforced.
- *
- * On its own it enforces nothing. `evaluate(toolName, args, mode)` is a pure function returning
- * `"allow" | "deny" | "ask"`, and no part of the SDK calls it until the engine is wrapped in a plugin
- * and that plugin is registered on an agent. The plugin is where a verdict becomes behaviour: `deny`
- * blocks the tool call, `allow` passes it through, and `ask` is routed to the host's `canUseTool`
- * gate — with no gate configured, `ask` blocks. So constructing an engine and never registering it
- * is a policy that does nothing, which is the mistake worth knowing about first.
- *
- * It is fail-closed by default: a call no rule matches resolves to `"ask"`, not `"allow"`, so a tool
- * the rules never mention needs a human — or an explicit `{ defaultAction: "allow" }` — before it
- * runs. Keep that default if you intend to use `PermissionMode: "plan"` for read-only behaviour,
- * because `plan` gates on the RESOLVED verdict: an engine built with `defaultAction: "allow"` still
- * allows every unmatched call under `plan`.
- *
- * The rules array is stored by reference and walked afresh on every `evaluate` call. Mutating the
- * array you passed in therefore changes the policy of a live engine; build a new engine when you
- * want a policy change to be a deliberate, visible event.
- */
-declare class PermissionEngine {
-    #private;
-    private readonly rules;
-    private readonly defaultAction;
-    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
-    /**
-     * Evaluate a tool name (and optional arguments) against the rules. First
-     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
-     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
-     * argument values, so the same tool name can resolve to different actions
-     * depending on what it is asked to do.
-     */
-    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
-}
-
-/**
  * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
  *
  * `Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
@@ -360,7 +231,7 @@ declare class PermissionEngine {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunCompactionFallbackEvent | RunTripwireEvent | RunCompletionCheckEvent | RunMcpServerFailedEvent | RunMcpServerReadyEvent | RunMemoryDegradedEvent;
 /**
  * theokit#188 — an MCP server was configured but its tools could not be listed, so NONE of its
  * tools exist for this run.
@@ -501,19 +372,46 @@ interface RunCompactionFallbackEvent {
     readonly window: number;
 }
 /**
- * SE2 — the opt-in sink for {@link RunEvent}s. Supplied via `SendOptions.onRunEvent`.
- * Synchronous + best-effort: a throwing sink must never break the run (the emitter
- * try-catches it), so keep it fast (push to a queue, don't await).
+ * A memory stage failed and the run continued without it.
+ *
+ * The same shape of gap {@link RunMcpServerFailedEvent} closed for MCP, in the module next door.
+ * `initLoopContext` had three bare `catch { <field> = <empty> }` blocks: an init failure meant no
+ * memory tool was registered, a `buildTools` failure meant no provider tools, and a `runActivePass`
+ * failure meant no recalled context in the system prompt. The agent then answered without the memory
+ * it was configured with, and nothing recorded it — not stderr, not this sink, not the span in scope.
+ *
+ * Degrading to a working agent is the right BEHAVIOUR. This event exists because the degradation was
+ * unobservable, so a host UI showed a healthy run.
+ *
+ * Emitted once per failing stage per run.
+ *
+ * @public
  */
-type RunEventSink = (event: RunEvent) => void;
+interface RunMemoryDegradedEvent {
+    readonly type: "memory_degraded";
+    /** Which stage failed: `init`, `buildTools`, or `activePass`. */
+    readonly stage: string;
+    /** Why it failed, as the provider reported it. */
+    readonly message: string;
+}
 /**
- * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
- * observability can never break the run (fail-safe, mirrors the EventBus EC-2
- * contract). No-op when the sink is absent.
+ * Receives every {@link RunEvent} a run emits, in emission order.
+ *
+ * Wired through `onRunEvent` on the run options. The sink is observability, never control flow: it
+ * cannot cancel, alter, or delay the run, and {@link emitRunEvent} swallows anything it throws — a
+ * broken sink degrades what you can see, never what the agent does.
+ *
+ * Synchronous by signature, so a slow sink slows the run. Hand work off rather than awaiting inside
+ * it; returning a promise here would be ignored, not awaited.
+ *
+ * @public
  */
-declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
+type RunEventSink = (event: RunEvent) => void;
 
 /**
+ * Owner: `internal/runtime/processors/` (3 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
  * the user message (input) or the model's final text (output). Processors run in
  * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
@@ -599,6 +497,9 @@ interface ProcessorTripwire {
 }
 
 /**
+ * Owner: `src/` (2 of 7 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Leaf module for content-block types shared by `messages.ts` (assistant/user
  * content) and `agent-prims.ts` (`CustomTool` handler results). Kept
  * import-free so both can depend on it WITHOUT the `agent-prims ↔ messages`
@@ -647,6 +548,9 @@ interface ImageBlock {
 type ToolResultContentBlock = TextBlock | ImageBlock;
 
 /**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
  * (audit `architecture-output/final_report.md`) per plan
@@ -762,6 +666,30 @@ interface CustomTool {
         threadId?: string;
     }) => string | ToolResultContentBlock[] | Promise<string | ToolResultContentBlock[]>;
 }
+/**
+ * How the permission engine treats the UNMATCHED verdict.
+ *
+ * - `default` — ask.
+ * - `plan` — read-only.
+ * - `acceptEdits` — auto-approve the unmatched verdict, but still honour an explicit `ask` rule.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything allowed EXCEPT an
+ *   explicit `deny`. Never asks.
+ *
+ * G7 / DIP — defined in this type leaf rather than in `permission-engine.ts`, which is a RUNTIME
+ * module. `types/agent.ts`, `types/run.ts` and `types/plugin.ts` all need the union, and each one
+ * used to reach into the engine for it: three of the nine violations the `types-dont-import-runtime`
+ * rule reported the moment it was able to see type-only edges at all. The engine re-exports it, so
+ * `import type { PermissionMode } from "@theokit/sdk"` is unchanged.
+ *
+ * @public
+ */
+type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+
+/**
+ * Owner: `internal/agent-loop/` (4 of 8 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 
 /**
  * Plain assistant message in a conversation history.
@@ -884,6 +812,9 @@ type ConversationTurn = {
 };
 
 /**
+ * Owner: `sandbox/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Child-process environment policy contract (#54).
  *
  * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`
@@ -902,6 +833,12 @@ type ConversationTurn = {
  */
 type EnvPolicy = "inherit-scrubbed" | "core" | "all";
 
+/**
+ * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+
 /**
  * MCP server configuration accepted by `Agent.create()` and `agent.send()`.
  *
@@ -987,6 +924,12 @@ type McpHttpServerConfig = {
  */
 type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
 
+/**
+ * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
+
 /**
  * Tool invocation block emitted by the assistant.
  *
@@ -1142,6 +1085,9 @@ interface SDKObjectDelta {
 type SDKMessage = SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage | SDKObjectDelta;
 
 /**
+ * Owner: `internal/budget/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for token usage + cost tracking (ADRs D376-D379).
  *
  * Surfaces via `RunResult.usage` + `RunResult.cost` after every Run.
@@ -1184,7 +1130,7 @@ type CostSource = "openrouter_api" | "litellm_snapshot" | "user_override" | "sub
 /**
  * Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
  * `amountUsd` is `undefined` — DO NOT default to 0 (a lie). The UI shows
- * `n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.
+ * `n/a` for unknown, `~$1.23` for estimated, `$1.23` for actual.
  */
 interface CostBreakdown {
     readonly amountUsd: number | undefined;
@@ -1507,6 +1453,28 @@ interface SDKUserMessage {
 /**
  * Per-send overrides and callbacks.
  *
+ * ## Which options do I need?
+ *
+ * Twenty-one optional fields with genuinely different audiences, so most callers read all of them to
+ * find their two. This table is the fix that was chosen; the alternative — nesting the groups under
+ * `observe?` and `toolPolicy?` and carrying the flat keys as deprecated aliases for one major — would
+ * have added surface to remove surface, and the harm here is the READING cost, not a representable
+ * illegal state. There is no measured defect behind this grouping and no consumer census; the fields
+ * and the audiences are what was measured.
+ *
+ * | If you are… | you want |
+ * |---|---|
+ * | rendering a live UI | `onDelta`, `onStep`, `onRunEvent` |
+ * | applying a policy | `permissionMode`, `activeTools`, `toolChoice`, `toolResultGuard`, `perToolTimeoutMs` |
+ * | running an eval or a harness | `maxIterations`, `completionCheck`, `doomLoop`, `signal` |
+ * | orchestrating agents | `origin`, `task`, `context` |
+ * | overriding this one send | `model`, `systemPrompt`, `tools`, `mcpServers`, `contextPaths`, `local` |
+ *
+ * Every field appears in exactly one row, and
+ * `tests/lint/send-options-audience-table.test.ts` fails when one is added without a row — a table
+ * that silently stops covering the type is worse than none, because a reader trusts it and stops
+ * looking.
+ *
  * @public
  */
 interface SendOptions {
@@ -1842,4 +1810,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type RunToCompletionOptions as $, type AgentConversationTurn as A, type ProcessorControls as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorTripwire as E, type ProcessorViolation as F, type GenerateOptions as G, type RunCompactBoundaryEvent as H, type ImageBlock as I, type RunCompletionCheckEvent as J, type RunErrorDetail as K, type RunEvent as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunTimelineEvent as _, type McpServerConfig as a, type RunToCompletionResult as a0, type RunToolProgressEvent as a1, type RunTripwireEvent as a2, type SDKAssistantMessage as a3, type SDKImage as a4, type SDKImageDimension as a5, type SDKObjectDelta as a6, type SDKRequestMessage as a7, type SDKStatusMessage as a8, type SDKSystemMessage as a9, type ToolContextMessage as aA, type ToolResult as aB, type ToolResultGuardOptions as aC, type ToolUseBlock as aD, type TurnEndedUpdate as aE, type UserMessage as aF, type UserMessageAppendedUpdate as aG, applyMode as aH, emitRunEvent as aI, type SDKTaskMessage as aa, type SDKThinkingMessage as ab, type SDKToolUseMessage as ac, type SDKUserMessage as ad, type SDKUserMessageEvent as ae, type SendOptions as af, type ShellCommand as ag, type ShellConversationTurn as ah, type ShellOutput as ai, type ShellOutputDeltaUpdate as aj, type StepCompletedUpdate as ak, type StepStartedUpdate as al, type StreamToCompletionResult as am, type SummaryCompletedUpdate as an, type SummaryStartedUpdate as ao, type SummaryUpdate as ap, type TextBlock as aq, type TextDeltaUpdate as ar, type ThinkingCompletedUpdate as as, type ThinkingDeltaUpdate as at, type ThinkingMessage as au, type TokenDeltaUpdate as av, type TokenUsage as aw, type ToolCall as ax, type ToolCallCompletedUpdate as ay, type ToolCallStartedUpdate as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type RunEventSink as e, type AssistantMessage as f, type CompletionCheck as g, type CompletionCheckResult as h, type ConversationStep as i, type ConversationTurn as j, type CostBreakdown as k, type CostSource as l, type CostStatus as m, type GenerateRunResult as n, type InputProcessorContext as o, type InteractionUpdate as p, type McpAuthConfig as q, type McpHttpServerConfig as r, type McpOAuthConfig as s, type McpStdioServerConfig as t, type MessageOrigin as u, type ModelParameterValue as v, type PartialToolCallUpdate as w, type PermissionAction as x, type PermissionEngineOptions as y, type PermissionRule as z };
+export type { RunTripwireEvent as $, AgentConversationTurn as A, RunCompletionCheckEvent as B, CustomTool as C, DoomLoopThresholds as D, RunErrorDetail as E, RunEvent as F, GenerateOptions as G, RunGitInfo as H, ImageBlock as I, RunMemoryDegradedEvent as J, RunOperation as K, RunPermissionDeniedEvent as L, ModelSelection as M, RunRateLimitEvent as N, OutputProcessorContext as O, Processor as P, RunStatus as Q, RunResult as R, SDKMessage as S, ToolResultContentBlock as T, RunTaskCompletedEvent as U, RunTaskStartedEvent as V, RunTaskUpdatedEvent as W, RunTimelineEvent as X, RunToCompletionOptions as Y, RunToCompletionResult as Z, RunToolProgressEvent as _, McpServerConfig as a, SDKAssistantMessage as a0, SDKImage as a1, SDKImageDimension as a2, SDKObjectDelta as a3, SDKRequestMessage as a4, SDKStatusMessage as a5, SDKSystemMessage as a6, SDKTaskMessage as a7, SDKThinkingMessage as a8, SDKToolUseMessage as a9, ToolUseBlock as aA, TurnEndedUpdate as aB, UserMessage as aC, UserMessageAppendedUpdate as aD, SDKUserMessage as aa, SDKUserMessageEvent as ab, SendOptions as ac, ShellCommand as ad, ShellConversationTurn as ae, ShellOutput as af, ShellOutputDeltaUpdate as ag, StepCompletedUpdate as ah, StepStartedUpdate as ai, StreamToCompletionResult as aj, SummaryCompletedUpdate as ak, SummaryStartedUpdate as al, SummaryUpdate as am, TextBlock as an, TextDeltaUpdate as ao, ThinkingCompletedUpdate as ap, ThinkingDeltaUpdate as aq, ThinkingMessage as ar, TokenDeltaUpdate as as, TokenUsage as at, ToolCall as au, ToolCallCompletedUpdate as av, ToolCallStartedUpdate as aw, ToolContextMessage as ax, ToolResult as ay, ToolResultGuardOptions as az, Run as b, PermissionMode as c, RunEventSink as d, AssistantMessage as e, CompletionCheck as f, CompletionCheckResult as g, ConversationStep as h, ConversationTurn as i, CostBreakdown as j, CostSource as k, CostStatus as l, GenerateRunResult as m, InputProcessorContext as n, InteractionUpdate as o, McpAuthConfig as p, McpHttpServerConfig as q, McpOAuthConfig as r, McpStdioServerConfig as s, MessageOrigin as t, ModelParameterValue as u, PartialToolCallUpdate as v, ProcessorControls as w, ProcessorTripwire as x, ProcessorViolation as y, RunCompactBoundaryEvent as z };