@theokit/agents 13.0.0-next.9 → 13.1.0

package/README.md

@@ -90,6 +90,37 @@ shipped the symbol is the answer — every entry names the version it landed in.
 - Web Standards over Node APIs inside `src/` — `Request`/`Response`, `fetch`, `crypto.randomUUID`.
   Node APIs live in adapters.
 
+## Who decides policy
+
+**An operator who did not write the code can impose policy on it.** That is a decision, recorded
+here because it is the one a team evaluating this framework for deployment needs before anything
+else.
+
+It was not always true. Hooks, MCP servers, permissions and skill execution were each a value the
+*programmer* passed at build time — a constructor argument, decided in code, by whoever wrote the
+agent. That is a defensible design for a framework and an indefensible one for anything an
+organisation deploys: it means the person responsible for what an agent may do on a machine has no
+way to say so.
+
+Policy is read from disk, and the layers have a fixed precedence:
+
+| Layer | Who writes it | Wins against |
+|---|---|---|
+| `managed-settings.json` | the operator / the organisation | everything below |
+| `.claude/settings.json`, `.theokit/settings.json` | the project | the code |
+| `defineAgent({ … })` | the programmer | nothing |
+
+A programmer can still decide everything, and in a single-author project nothing above them exists.
+What changed is that they are no longer the *only* one who can.
+
+Two consequences worth stating, because they are the cost:
+
+- A value declared in code can be **overridden by a file the programmer does not control**. That is
+  the point, and it means a build-time guarantee is not one.
+- An operator restriction is refused loudly rather than silently narrowed. A policy that quietly
+  did less than it said would be worse than none — the failure this repository keeps finding under
+  other names.
+
 ## Licence
 
 See `LICENSE`.

package/dist/{agent-compiler-DZorqtK2.d.ts → agent-compiler-B_Z3OZel.d.ts}

@@ -1,6 +1,8 @@
-import { InlineSkill, TrustPosture, SettingSource, SystemPromptResolver, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
+import { InlineSkill, SystemPromptResolver, SessionStore, PermissionGate, MemorySettings, SkillsSettings, ContextSettings, TelemetrySettings } from '@theokit/sdk';
+import { AgentDefinition } from '@theokit/sdk/subagents-loader';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 import { R as ReasoningEffort, a as MemoryOptions, P as ProjectContextOptions, M as McpServersMap, H as HumanInTheLoopOptions, C as CheckpointOptions, T as ToolOptions, A as ApprovalOptions, B as BudgetOptions } from './types-C16Wuh9E.js';
+import { G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-DFu51i50.js';
 
 /**
  * M9 (theokit-ai-first) — guardrail contract + typed errors.
@@ -35,23 +37,87 @@ interface Guardrail {
 }
 /** 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. */
 /**
- * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ * A guard declared `redact` and supplied no replacement text.
  *
- * `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 — a regex
- * over an eight-level `cause` chain, which is what one actually wrote. `code` is stable across a
- * rename of the class; `isRetryable` is DECLARED rather than defaulted, because a default would be a
- * retry policy nobody chose.
+ * Distinct from {@link GuardrailViolationError} on purpose: that one says the guard REFUSED
+ * something, which is a decision working as designed. This says the guard is MALFORMED — it asked
+ * for a redaction and gave nothing to redact with, so nothing was redacted.
+ *
+ * Until B-008 this condition was silent: `pipeline.ts` tested `r.text !== undefined` and moved on, so
+ * the caller received the original text and believed a guard had run on it. That is the shape this
+ * package's hook engine calls "worse than no hook at all" — a belief in a protection that is not
+ * there. Throwing is fail-fast per `rules/error-handling.md § 2`, and the alternative was leaving
+ * unredacted output to reach a model because a guard was written wrong.
+ *
+ * `''` is NOT this case. An empty replacement is a guard choosing to erase everything, which is the
+ * strongest redaction available, and treating it as absent would invert the defect.
+ */
+/**
+ * The base every guardrail error shares, so the seams that must treat them alike can do so BY
+ * CONSTRUCTION rather than by remembering a list.
+ *
+ * The list is how B-020 happened. `run-reflective-loop.ts` let `GuardrailViolationError` pass
+ * through unwrapped, and its sibling in this same file was not added — so a malformed result was
+ * wrapped in a `DelegationError`, whose message interpolates its cause and whose code is on the
+ * delegate tool's message allowlist. The guard's name crossed to the model, and a guard DEFECT was
+ * reported as a delegation failure.
+ *
+ * A base is not airtight on its own: a new class can still extend `TheokitAgentError` directly.
+ * `tests/unit/a-guardrail-defect-does-not-name-its-guard.test.ts` walks this module's barrel and
+ * fails on any exported error class that skipped it. The two together are the construction; either
+ * alone is a convention.
+ *
+ * Abstract because there is nothing to throw at this level — every guardrail failure is one of the
+ * specific kinds below, and a bare `GuardrailError` would say only that something guard-shaped
+ * happened.
+ */
+declare abstract class GuardrailError extends TheokitAgentError {
+}
+declare class MalformedGuardrailResultError extends GuardrailError {
+    readonly guardName: string;
+    readonly phase: GuardrailPhase;
+    readonly name = "MalformedGuardrailResultError";
+    constructor(guardName: string, phase: GuardrailPhase);
+}
+/**
+ * Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md.
+ *
+ * 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 — a regex over an eight-level `cause` chain, which
+ * is what one actually wrote. `code` is stable across a rename of the class; `isRetryable` is
+ * DECLARED rather than defaulted, because a default would be a retry policy nobody chose.
  */
-declare class GuardrailViolationError extends TheokitAgentError {
+declare class GuardrailViolationError extends GuardrailError {
     readonly guardName: string;
     readonly phase: GuardrailPhase;
     readonly reason: string;
     readonly name = "GuardrailViolationError";
     constructor(guardName: string, phase: GuardrailPhase, reason: string);
 }
+/**
+ * A text-carrying event arrived with a `content` that is not text.
+ *
+ * Distinct from the two above on purpose: they say a guard REFUSED something or was WRITTEN WRONG.
+ * This says the STREAM is malformed — the event announces itself as text and carries something a
+ * guard cannot read.
+ *
+ * Until B-021 this was silent. Both extractors tested `typeof e.content === 'string'` and returned
+ * `undefined` otherwise, which `moderateOutputStream` reads as "this event carries no text" — so the
+ * payload was never accumulated, never shown to a guard, and yielded VERBATIM. The failure direction
+ * is DELIVER: a guard declared to stop that payload never saw it, and the run reported green.
+ *
+ * Refused rather than coerced. Coercing would moderate `"[object Object]"` — a guard consulted about
+ * a string the model never produced, returning a verdict about nothing, while the real payload rides
+ * along underneath. That is the redaction-computed-and-discarded shape with an extra step.
+ */
+declare class UnreadableTextPayloadError extends GuardrailError {
+    readonly eventType: string;
+    readonly received: unknown;
+    readonly name = "UnreadableTextPayloadError";
+    constructor(eventType: string, received: unknown);
+}
 /** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
 /**
  * M80 — extends {@link TheokitAgentError}, not plain `Error`.
@@ -62,7 +128,7 @@ declare class GuardrailViolationError extends TheokitAgentError {
  * rename of the class; `isRetryable` is DECLARED rather than defaulted, because a default would be a
  * retry policy nobody chose.
  */
-declare class CostBudgetExceededError extends TheokitAgentError {
+declare class CostBudgetExceededError extends GuardrailError {
     readonly usedTokens: number;
     readonly maxTokens: number;
     readonly name = "CostBudgetExceededError";
@@ -98,181 +164,39 @@ type SkillsSelection = readonly (string | InlineSkill)[] | ((ctx: SkillsRequestC
 declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ctx: SkillsRequestContext): Promise<string[] | undefined>;
 
 /**
- * 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;
-    /**
-     * `<cwd>/.claude/` — a FOREIGN configuration dialect, read only once declared
-     * (`usetheokit/theokit-sdk#524`).
-     *
-     * ## Two questions, and which half of this field answers each
-     *
-     * The SDK's docblock separates them, and the separation is the whole point of `compatSources`:
-     * a trust gate answers *"do I trust the code in this directory?"*; importing another product's
-     * configuration answers *"do I want it imported into this one?"*. They come apart in the ordinary
-     * case, because `.claude/` is populated in exactly the repository one trusts most — for a
-     * different tool, by a teammate who never heard of this runtime.
-     *
-     * So the two are answered by two different things here, and it matters which:
-     *
-     * | Question | Answered by |
-     * |---|---|
-     * | do I want the foreign dialect imported? | **declaring this field at all** — omitting is not enabling |
-     * | do I trust this directory's code to run? | the `TrustPosture` inside the grant |
-     *
-     * ## Why the grant is `ProjectSettingsGrant` and not a vocabulary of its own
-     *
-     * Not because the two questions are the same — they are not. Because a separate grant could not
-     * carry the distinction even if it existed: `TrustPosture.allows` is `Record<K, boolean>` and the
-     * SDK documents every value as moving together with the level, so a `'foreignDialects'` capability
-     * beside `'projectSettings'` would promise an operator they can grant one and withhold the other,
-     * and `resolveTrustPosture` would hand back the same boolean for both. That is precisely the
-     * failure ADR 0065 exists to prevent, and inventing the second name would commit it while looking
-     * like rigour.
-     *
-     * The consent half is therefore carried by the declaration, which is a real and sufficient
-     * boundary: an operator who trusts a repository completely still reads no `.claude/` until they
-     * write this field. What the grant adds on top is stricter than the SDK — there, listing a dialect
-     * is enough — and the extra strictness is deliberate: this reads a `hooks.json` that executes
-     * shell out of a directory that usually arrived with the clone.
-     */
-    readonly claudeCode?: ProjectSettingsGrant & {
-        /**
-         * #686 — WHICH surfaces of the foreign root to import. Absent means all of them, which is what
-         * every caller before this meant and still means.
-         *
-         * The distinction is the reason the grant exists. `.claude/` usually arrives with the clone and
-         * its `hooks.json` executes shell, so "take the skills, refuse the hooks" is the ordinary thing
-         * to want — and before this the only choices were all of it or none of it.
-         *
-         * Requires `@theokit/sdk >= 5.4.0`, which is where the narrowed form landed. On an older SDK the
-         * runtime drops an unrecognised shape in SILENCE, so declaring it there would import nothing at
-         * all rather than importing less — refused at resolve time instead.
-         */
-        readonly import?: readonly CompatSurface[];
-    };
-}
-/**
- * The surfaces a foreign configuration root can contribute.
- *
- * Written out rather than imported, for the same reason as the `claude-code` literal below:
- * `CompatSurface` does not exist in `@theokit/sdk@4.52.1`, this package's declared floor, and a gate
- * that cannot build against its own minimum dependency is worse than a constant that has been
- * checked. Verified against the published 5.4.0 `.d.ts`, where the union is
- * `"hooks" | "plugins" | "skills" | "subagents"` — note `subagents`, not `agents`.
- */
-type CompatSurface = 'hooks' | 'plugins' | 'skills' | 'subagents';
-/** What `resolveCompatSources` returns: the whole root, or the root narrowed to some surfaces. */
-type ResolvedCompatSource = 'claude-code' | {
-    readonly kind: 'claude-code';
-    readonly import: readonly CompatSurface[];
-};
-/**
- * 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.
+ * The shape this layer registers with the SDK's lifecycle-hook seam.
  *
- * 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.
+ * Deliberately structural and minimal: the SDK owns the full `Plugin` contract, and restating it
+ * here would be a second declaration to drift from. What this needs to know is the one thing that
+ * tells a code plugin from a bundle reference.
  */
-declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly SettingSource[];
 /**
- * The foreign configuration dialects this layer forwards, once the posture authorises them.
- *
- * ## Why it is a separate function and the same vocabulary
- *
- * Separate because the SDK takes them on a separate option (`local.compatSources`); the same
- * `ProjectSettingsGrant` because the thing being authorised is identical — reading a `hooks.json`
- * that executes shell out of a directory the operator does not necessarily control.
+ * A code plugin, in any of the three kinds `@theokit/sdk`'s `Plugin` union defines.
  *
- * ## What it deliberately does NOT do
+ *   `general`         `register(ctx)`     registers tools, commands, hooks
+ *   `model-provider`  `profile`           supplies a model provider
+ *   `memory`          `createProvider`    supplies a memory adapter
  *
- * Validate the source NAME. The SDK DROPS an unrecognised name rather than turning it into
- * `<cwd>/<name>`, so a typo fails closed there; turning that into a throw here would convert a safe
- * default into a crash. This gate decides authorisation, never vocabulary.
+ * The first version of this type required `register`, which accepted the first kind and refused the
+ * other two — while the docblock on `AgentBuilder.plugins`, written in the same commit, already
+ * described all three. A real consumer found it: on `@theokit/agents@13.0.0` a `model-provider`
+ * plugin failed to compile with "Property 'register' is missing". A guard written to refuse the
+ * FILESYSTEM-bundle form was refusing two thirds of the CODE form instead.
  *
- * @throws {UntrustedSettingSourceError} when a source is requested and the posture does not grant it.
+ * Modelled here as name-plus-one-capability rather than by importing the SDK union, for the reason
+ * the module header gives: this layer must not depend on the SDK's value side, and the published
+ * floor is `^4.52.1` where the union's shape is not guaranteed identical. The capability keys ARE
+ * the discriminator, so the refusal below stays exact.
  */
-declare function resolveCompatSources(selection: SettingSourcesSelection | undefined): readonly ResolvedCompatSource[];
+type CodePlugin = {
+    readonly name: string;
+} & ({
+    readonly register: (...args: never[]) => unknown;
+} | {
+    readonly profile: unknown;
+} | {
+    readonly createProvider: (...args: never[]) => unknown;
+});
 
 /**
  * Project the M8 fields from `CompiledAgentOptions` into `Agent.create()` arguments. Only the async
@@ -325,6 +249,33 @@ declare class HookGateUnsupportedError extends TheokitAgentError {
     readonly name = "HookGateUnsupportedError";
     constructor(version: string | undefined);
 }
+/**
+ * A narrowed `import` on an SDK that cannot read it.
+ *
+ * Refuses rather than warns, and the asymmetry with {@link warnIfSdkCannotReadCompatSources} is
+ * deliberate: an unrecognised `compatSources` shape means the foreign root is not read, so a
+ * consumer who asked for "the skills but not the hooks" silently gets NOTHING — strictly further
+ * from what they asked for than the un-narrowed form, which at least reads something. Failing loud
+ * is recoverable; a silent nothing is discovered by wondering why a skill is missing.
+ *
+ * ## The cost, which this file argues against two functions above
+ *
+ * An unreadable version is refused too, on the principle {@link assertSdkCanGateHooks} states:
+ * "cannot tell" and "is supported" must not collapse. The sibling WARNING takes the opposite view
+ * for itself — *"a bundled or vendored SDK may not resolve that subpath, and refusing to create an
+ * agent over a diagnostic would be the cure being worse than the disease."*
+ *
+ * Both are right for what they guard, and the difference is what the check IS. A diagnostic that
+ * cannot read a version should stay quiet; a GATE that cannot read one has not established the
+ * thing it exists to establish. But the cost is real and belongs here rather than in a reviewer's
+ * report: a consumer who bundles the SDK so `@theokit/sdk/package.json` does not resolve cannot
+ * create an agent with a narrowed `import`, even on 5.4.0+. Their exit is to omit `import` and read
+ * the whole root.
+ */
+declare class CompatImportUnsupportedError extends TheokitAgentError {
+    readonly name = "CompatImportUnsupportedError";
+    constructor(version: string | undefined);
+}
 
 /**
  * Agent compiler — transforms decorator metadata into SDK calls.
@@ -385,18 +336,23 @@ interface CompiledTool {
  * @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;
-}
+/**
+ * A compiled sub-agent IS the SDK's own `AgentDefinition`, re-exported here under the name the
+ * public barrel already uses for it.
+ *
+ * It used to be a narrower local type, `CompiledSubAgent { model?, systemPrompt? }`, and ADR D3
+ * deferred projecting it: "a resolver here is carried, not invoked". **That deferral has ended** —
+ * `assembleM8CreateOptions` now projects `agents` into `Agent.create`.
+ *
+ * The narrow type could not have been projected as it stood. `AgentDefinition` requires
+ * `description` and `prompt`, and the local shape carried neither; a sub-agent with no description
+ * is one the parent model has no basis to delegate to. Every other surface already agreed on the
+ * SDK shape — `RuntimeOverrides.agents` (the per-run door that always worked) is
+ * `Record<string, AgentDefinition>`, and the same type crosses the barrel as `SubagentDefinition`.
+ * The local type was referenced in exactly two places, both of them its own declaration and the
+ * field that held it, so adopting the SDK shape removed a mismatch rather than migrating users.
+ */
+type CompiledSubAgent = AgentDefinition;
 /** Compiled agent options ready for SDK Agent.create(). */
 interface CompiledAgentOptions {
     model?: string;
@@ -415,14 +371,14 @@ interface CompiledAgentOptions {
      * Projected into `Agent.create({ local: { settingSources } })` by `assembleM8CreateOptions`
      * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
      */
-    settingSources?: readonly SettingSource[];
+    settingSources?: readonly GatedSettingSource[];
     /**
      * Foreign configuration dialects, already authorised (usetheokit/theokit#634).
      *
      * Resolved at compile time by `resolveCompatSources`, exactly like `settingSources`: a value here
      * can only hold a source some posture granted, so the adapter projects rather than decides.
      */
-    compatSources?: readonly ResolvedCompatSource[];
+    compatSources?: readonly GatedCompatSource[];
     /**
      * #686 — the consumer's pre-spawn approval gate, forwarded to `Agent.create({ local: { hooks } })`.
      *
@@ -432,12 +388,58 @@ interface CompiledAgentOptions {
      */
     hookApproval?: HookApprovalGate;
     /** Code `Plugin` objects forwarded to `Agent.create({ plugins })` (lifecycle-hook seam). */
-    plugins?: readonly unknown[];
+    /**
+     * Code plugins — `{ name, register }` objects registered with the SDK's lifecycle-hook seam.
+     *
+     * `readonly unknown[]` is what let the WRONG shape through silently: a consumer who read the
+     * Claude Code documentation passed `[{ type: 'local', path: './p' }]`, the compiler accepted it,
+     * and the agent ran with the plugin absent. `assertCodePlugins` refuses it at the projection, and
+     * the type says what belongs here.
+     *
+     * NOT the filesystem-bundle form. A bundle is declared by living in a `plugins/` directory under
+     * `.theokit/` or `.claude/`, where its `skills/` and `agents/` are discovered.
+     */
+    plugins?: readonly CodePlugin[];
+    /**
+     * B-060 — an external session store (Postgres / Redis / KV / durable object), used by the SDK as
+     * the PRIMARY session store and resume source.
+     *
+     * Without it a serverless deployment resumed from a filesystem that no longer exists, and a
+     * multi-pod one resumed from whichever host happened to take the request. The only way to reach
+     * it was importing `@theokit/sdk` directly — the one thing this layer's doctrine forbids, so the
+     * doctrine and the capability disagreed and the consumer paid.
+     *
+     * Typed against the SDK's own `SessionStore` rather than restated here: a hand-written copy that
+     * drifts by one method stops fitting, which the mirrored `permissionMode` field measured one item
+     * earlier.
+     */
+    sessionStore?: SessionStore;
+    /**
+     * B-056 — the callback that sees every tool call the earlier steps did not resolve.
+     *
+     * The SDK's engine is fail-closed: an unmatched call resolves to `ask`, and an ABSENT gate blocks
+     * it. So the value of declaring one is not that unresolved calls stop being approved — they never
+     * were — it is that they reach somebody who can decide instead of being refused with nobody to
+     * consult. A tool added after the approvals were written keeps defaulting to asking.
+     *
+     * Typed against the SDK's `PermissionGate`, not restated: its decision shape is veto-or-allow, and
+     * a hand-written copy would be the place an `updatedInput` field gets invented for a seam that
+     * discards it.
+     */
+    canUseTool?: PermissionGate;
     tools: CompiledTool[];
     agents: Record<string, CompiledSubAgent>;
     memory?: MemoryOptions | MemorySettings;
     skills?: SkillsSettings;
     context?: ContextSettings;
+    /**
+     * B-072 — OpenTelemetry settings, projected onto `Agent.create({ telemetry })`.
+     *
+     * Typed against the SDK's `TelemetrySettings` rather than restated, for the reason `canUseTool`
+     * above gives about `PermissionGate`: a hand-written copy is where a field gets invented for a
+     * seam that discards it, and this one has six keys with real defaults behind them.
+     */
+    telemetry?: TelemetrySettings;
     /**
      * M7 — run-context injected into every tool handler's `ctx.context` by the theokit adapter
      * (`buildSdkTools` wrapper). Populated by `defineAgent({ context })` (functional surface).
@@ -475,4 +477,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-export { type CompiledAgentOptions as C, type Guardrail as G, type HookApprovalGate as H, type ProjectSettingsGrant as P, type ResolvedCompatSource as R, type SkillsSelection as S, type ToolWalkResult as T, UntrustedSettingSourceError as U, type SettingSourcesSelection as a, type CompiledTool as b, type CompatSurface as c, CostBudgetExceededError as d, type GuardrailAction as e, type GuardrailPhase as f, type GuardrailResult as g, GuardrailViolationError as h, type HookApprovalRequest as i, HookGateUnsupportedError as j, type SettingSourceCapability as k, type SkillsRequestContext as l, type ToolboxWalkResult as m, compileTools as n, resolveEnabledSkills as o, resolveSettingSources as p, resolveCompatSources as r };
+export { type CodePlugin as C, type Guardrail as G, type HookApprovalGate as H, MalformedGuardrailResultError as M, type SkillsSelection as S, type ToolWalkResult as T, UnreadableTextPayloadError as U, type CompiledAgentOptions as a, type CompiledTool as b, CompatImportUnsupportedError as c, CostBudgetExceededError as d, type GuardrailAction as e, GuardrailError as f, type GuardrailPhase as g, type GuardrailResult as h, GuardrailViolationError as i, type HookApprovalRequest as j, HookGateUnsupportedError as k, type SkillsRequestContext as l, type ToolboxWalkResult as m, compileTools as n, resolveEnabledSkills as r };

package/dist/ask.d.ts

@@ -1,4 +1,5 @@
 import { TheokitAgentError } from '@theokit/sdk/errors';
+export { TheokitAgentError } from '@theokit/sdk/errors';
 
 /**
  * M77 — the ask channel: the agent asks, a human answers, the turn waits.