@theokit/agents 14.5.1 → 15.0.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # @theokit/agents
 
+## 15.0.0
+
+### Major Changes
+
+- d4c00bb: **Breaking:** `CheckpointOptions` is narrowed to `{ resumeSignal?: boolean }`. `storage`, `strategy`,
+  `maxCheckpoints` and `ttl` are removed, along with the `CheckpointStorage` and `CheckpointStrategy`
+  types.
+
+  The option read as a durable-checkpoint configuration and was a signalling flag: four fields
+  declared, exactly one ever read, as an `=== 'filesystem'` equality deciding whether a
+  `checkpoint_saved` event is emitted. `'drizzle'` and `'redis'` were indistinguishable from
+  `'memory'` in every code path.
+
+  The warning that pushed authors toward `'filesystem'` is gone. It said that value "selects the SDK's
+  durable conversation store"; the SDK persists every session to its transcript regardless, so it
+  selected nothing — and on a pod with no volume it named the one storage that is unreachable.
+
+  **Migration:** delete the removed fields; they configured nothing. `storage: 'filesystem'` becomes
+  `resumeSignal: true` if you want the `checkpoint_saved` event. Resume itself is a property of the
+  SDK's session transcript and needs no option.
+
+### Minor Changes
+
+- c3d677d: An SDK that cannot read a foreign configuration root is now refused with a typed
+  `CompatRootUnsupportedError`, instead of warned about.
+
+  `compatSources` landed in `@theokit/sdk@5.0.0`. Below it the option is accepted and ignored, so every
+  `.claude/` surface is unavailable while the package resolves, compiles and runs. A `console.warn`
+  stood there, and its own text named the condition that kept it a warning: "Until this package's floor
+  can name a stable 5.x". The floor is `^5.3.0`, so the only way to reach that branch is an override —
+  and an override that silently disables every foreign surface is what a refusal is for.
+
+  Separate from `CompatImportUnsupportedError`, which is about narrowing a root the SDK can already
+  read (5.4.0). Reusing it would name the wrong version and send the reader to the wrong upgrade.
+
+- fb80f7d: `createPermissionsPlugin` now requires a gate for the `ask` verdict, and `AgentBuilder` gained
+  `.subagents()`.
+
+  The gate is mandatory rather than optional because its absence had a silent, catastrophic default:
+  `PermissionEngine` answers `ask` for a tool no rule matches, and the SDK turns that into a hard block
+  when nothing answers it. Wiring the engine without a gate made every tool an operator had not
+  enumerated stop working, the moment they wrote any `permissions` block at all.
+
+  `.subagents()` supplies subagent definitions by name, reaching `AgentOptions.agents`. It is distinct
+  from `settingSources`, which discovers them: the framework reads `.claude/agents/<name>.md` and takes
+  the prompt from the file, so a caller that enriched a definition — `applySubagentMemory` folding in a
+  `MEMORY.md` is the measured case — had nowhere to put the result and it was silently discarded.
+
+- b81957c: `FOREIGN_KEY_DECISIONS` records what this package does with each `.claude/settings.json` key its
+  diagnostics name, and why — `honoured` or `refused`, each with a reason about this product rather
+  than about the reference.
+
+  `model` and `cleanupPeriodDays` join the settings schema as honoured keys. Reporting a key as "not
+  implemented here" says the code does not act on it; it never says whether that is a refusal or an
+  omission, and an author reading it cannot tell whether to stop writing the key or to wait for it.
+
+### Patch Changes
+
+- 4aa6602: Documents that a subagent's `memory:` declaration needs `@theokit/sdk@5.9.0`, and pins it
+  with a test.
+
+  `applySubagentMemory` shipped in 14.5.0 reading a declaration the SDK parses off subagent
+  frontmatter. Before 5.9.0 that parse REFUSES the key — measured against the published
+  tarballs, with a control that declares no `memory:` and loads on both:
+
+      5.3.0   ConfigurationError: Subagent note-taker.md: unknown frontmatter field "memory"
+              (accepted: name, description, model, tools, reasoning_effort, mcp, sandbox)
+      5.9.0   loads both; `memory: "project"` survives
+
+  The failure was never silent. What misleads is where it points: naming the field reads as a
+  typo, so the line an author meant to write gets deleted instead of the SDK upgraded.
+
+  **The range is unchanged at `^5.3.0`, and there is no runtime guard.** Both were tried and
+  both were refused by gates that were right. Raising the floor is refused by
+  `the-declared-sdk-range-delivers-what-the-code-assumes.test.ts`, which holds that a gap
+  announcing itself is guarded rather than closed by the range — closing it strands every
+  consumer, including those who never write `memory:`. A guard is refused by the bundle
+  budget: wiring one into `listSubagentNames` cost **161 bytes** of a root barrel with 72 of
+  headroom, and the cost is the COUPLING rather than the code — four different bodies produced
+  byte-identical bundles, and a dedicated module was worse at 40 403 because it duplicated
+  `createRequire`.
+
+  So the requirement is documented where someone hits it, and a test fails if it stops being
+  true. `applySubagentMemory` itself needs no particular SDK: it reads `node:fs`, takes an
+  object, and works on any version — the requirement belongs to the parser.
+
+- f6a5526: Two rows of the foreign-surfaces table were false, and a test now checks the class they
+  belong to.
+
+  `agent-memory/` read _"Measured 2026-09-15: no consumer does yet"_ while `apps/theocode`
+  imported `applySubagentMemory` and applied it in `delegation/role-discovery.ts:84-85`. The
+  measurement was true when taken — the consumer could not call it, because the function was
+  not in the version it pinned, and its own source says so: _"the one line that wires it does
+  not compile here yet"_. The integration was written, tested, and left disconnected, waiting
+  on a publish. Nothing about either side changed; the consumer moved into this repository and
+  the import resolved.
+
+  `themes/*.json` read _"nobody reads it, in any of the three packages"_ and never said which
+  three. Naming them took one edit and the sentence failed immediately: `apps/theocode`
+  resolves `~/.claude/themes/` in `tui/src/theme/custom-theme.ts`, with three reads in that one
+  file. It is the same shape as `keybindings.json` — out of scope HERE, read by the consumer —
+  which this section had explicitly denied.
+
+  **A claim nobody can check is not a weaker claim; it is a claim that has never been tested.**
+
+  `an-absence-is-a-decision-or-it-is-a-gap.test.ts` now confronts any row asserting an absence
+  of consumption with the consumer's own source, and fails naming both. It reads TABLE ROWS
+  rather than the file — the first version matched the prose explaining the old claim, which is
+  the mistake that file already records one block below. Positive controls on both rows: each
+  restored claim fails the test with the reason.
+
+- 3d73fd2: Every text-bearing channel a client receives now reflects the declared output guards.
+
+  `DoneEvent.result` was not moderated: with a redactor declared, one turn delivered `text_delta ->
+"here: [R]"` and `done.result -> "here: sk-abc123"`, so a client rendering the terminal frame got the
+  secret the guard existed to remove. It is now rebuilt from the round's own moderated deltas — which is
+  exact rather than approximate, because the frame carries the visible text of its own round.
+
+  `task_progress.text` — the fourth channel — takes an ordinary third `moderateOutputStream` pass on
+  both the runner and the served path. It is not a mirror of anything: it carries text the model writes
+  through `task-tools`, and a milestone naming a secret is the same disclosure as a delta naming it.
+
+- Updated dependencies [54d87cf]
+  - @theokit/presenter@0.10.0
+
 ## 14.5.1
 
 ### Patch Changes

package/README.md

@@ -98,10 +98,10 @@ configuration that had no effect.
 | `skills/`, `agents/`, `commands/`, `plugins/` | read when the dialect is declared |
 | `.mcp.json` | read; a field this runtime does not carry is reported |
 | `output-styles/*.md` | read, selected by `settings.json` |
-| `agent-memory/` | **resolvable** — the SDK carries the declaration, `applySubagentMemory` applies it, and the host decides whether to call it. Measured 2026-09-15: no consumer does yet |
+| `agent-memory/` | **read** — `applySubagentMemory` applies a subagent's `memory:` declaration, and `apps/theocode` calls it (`apps/theocode/packages/agent/src/delegation/role-discovery.ts`). The host still decides: nothing here calls it for you |
 | `workflows/*.js` | **refused**, and reported. Every other surface is data; a workflow is code, and executing JavaScript found under a caller-supplied directory is a decision that belongs to you |
 | `keybindings.json` | **out of scope HERE** — read by the consumer, see below |
-| `themes/*.json` | **out of scope** — nobody reads it, in any of the three packages |
+| `themes/*.json` | **out of scope HERE** — read by the consumer, like `keybindings.json`. `apps/theocode` resolves `~/.claude/themes/` in `apps/theocode/packages/tui/src/theme/custom-theme.ts`; this package and `@theokit/tui` read neither |
 | `~/.claude.json` — OAuth state, UI toggles | **out of scope** — a CLI's own state |
 | `~/.claude.json` — personal-scope MCP servers | **read** — `loadPersonalMcpServers` |
 
@@ -124,8 +124,10 @@ in `terminal-io/keybindings.ts`, against a format it measured against the publis
 Naming the toolkit as the owner sent a reader to the package that does the least with it — and the
 row said `out of scope` without saying out of scope FOR WHOM, which is the half that misleads.
 
-`themes/*.json` is read by nobody, in any of the three packages. That is a genuine gap rather than a
-delegation, and it is stated here rather than implied by an ownership that does not exist.
+`themes/*.json` is read by the CONSUMER, exactly as `keybindings.json` is: `apps/theocode` resolves
+`~/.claude/themes/` in `apps/theocode/packages/tui/src/theme/custom-theme.ts` and selects one through `/theme custom:<slug>`.
+This package reads it in 0 files and so does `@theokit/tui` — measured 2026-09-17 against the
+installed 0.80.0.
 
 **`~/.claude.json` is two things under one name, and the split is the point.** Its OAuth state and UI
 toggles are a CLI's own state — that file is written by a specific program about its own session, and
@@ -148,9 +150,16 @@ The registry entry that prompted this counts four decisions across three files,
 
 ### `themes/*.json`
 
-Read by none of the three packages, measured 2026-09-15. After `keybindings.json` turned out to be
-read by the consumer rather than by the package it was attributed to, the obvious next move was to
-treat this as the same finding. It is not.
+Read by the consumer, measured 2026-09-17. After `keybindings.json` turned out to be read by
+`apps/theocode` rather than by the package it was attributed to, the obvious next move was to treat
+this as the same finding — and it **is** the same finding, which this document denied until the
+three packages were named.
+
+The denial is worth keeping, because it shows what an unfalsifiable sentence costs. This section
+read *"nobody reads it, in any of the three packages"* and never said which three. A reader could
+not check a set they could not enumerate, so nobody did; naming them took one edit, and the sentence
+was false the moment it became checkable — `apps/theocode` resolves `~/.claude/themes/` in
+`apps/theocode/packages/tui/src/theme/custom-theme.ts`, with three reads in that one file.
 
 This package has no colour at all — a grep for `color`, `chalk` or `theme` across its source returns
 nothing, the one apparent hit being `ansi` inside `stateTransitionHistory`. It produces text and tool
@@ -207,15 +216,28 @@ and not applied, so nobody believes it took effect.
 **200 lines, capped at 25KB**, of its `MEMORY.md` — both caps apply, and truncation is reported
 rather than silent.
 
-**The host calls it. Nothing here calls it for you, and `memory:` in subagent frontmatter does not
-reach it.** Measured 2026-09-15: `resolveAgentMemory` has no caller in this repository outside its
-own tests, and `@theokit/sdk` — which is the package that loads `.claude/agents/*.md`, and does not
-depend on this one — lists `memory` among the fields it refuses, so a file declaring it is skipped
-with a diagnostic rather than granted a directory.
+**The host calls it. Nothing here calls it for you** — and that sentence is the whole contract: this
+package exposes the reader, an application wires it.
+
+One does. `apps/theocode` imports `applySubagentMemory` from `@theokit/agents/config` and applies it
+to both role sets in `apps/theocode/packages/agent/src/delegation/role-discovery.ts:84`; that reaches `resolveAgentMemory`
+through `agent-memory.ts:231`. So the chain runs end to end, and this document says **read** rather
+than **resolvable**.
+
+It said the opposite until 2026-09-16, and the reason is worth keeping because it is the failure
+mode this table exists to prevent. The measurement behind *"no consumer does yet"* was true when
+taken: the consumer could not call it. Its own source says why — *"`applySubagentMemory` … is NOT in
+the published 14.4.0 this project pins, so the one line that wires it does not compile here yet"*.
+The integration was written, tested, and left disconnected, waiting on a publish.
+
+What changed is not the code on either side. `apps/theocode` joined this repository, `@theokit/agents`
+resolves through the workspace, and the line compiled. **A capability can be published, correct, and
+unreachable** — and a document that reports the reachable state as the real one is reporting a
+delivery problem as a design decision.
 
-Saying "read" in the table above, as this document did until that measurement, put this surface in
-the same column as `CLAUDE.md` and implied a wiring that does not exist. The reader is real and the
-three roots below are real; what an author supplies is the call.
+`@theokit/sdk` before 5.9.0 refuses `memory:` in frontmatter entirely, naming the field rather than
+the version — `agent-memory.ts` carries that measurement, and
+`the-sdk-version-that-parses-memory.test.ts` pins it.
 
 | `memory:` | Root | Who can see it |
 |---|---|---|
@@ -270,6 +292,13 @@ which is a worse failure than never having documented it.
   Those are the SDK's, and a PR that adds one here is rejected on sight.
 - It does **not** depend on the `theokit` web framework. The dependency runs the other way.
 - Web Standards over Node APIs inside `src/` — `Request`/`Response`, `fetch`, `crypto.randomUUID`.
+  Two `node:crypto` imports remain and both are measured rather than overlooked: `createHash` in
+  `packages/agents/src/hooks/hook-fingerprint.ts`, because the Web equivalent is async and this
+  function is not, and `randomBytes` in `packages/agents/src/hooks/hook-spec.ts`, where
+  `getRandomValues` would buy conformance at the cost of a hand-written hex conversion. A third
+  was removed on 2026-09-17: `randomUUID` had no such defence — the global is the API this line
+  names, and three other files in the package were already using it.
+  File reads keep `node:fs`: there is no Web Standard to prefer.
   Node APIs live in adapters.
 
 ## Who decides policy

package/dist/{agent-compiler-D7-Xd6Zh.d.ts → agent-compiler-DEMJlZNS.d.ts}

@@ -1,8 +1,10 @@
-import { InlineSkill, SystemPromptResolver, SessionStore, PermissionGate, MemorySettings, SkillsSettings, ContextSettings, TelemetrySettings } from '@theokit/sdk';
-import { AgentDefinition } from '@theokit/sdk/subagents-loader';
+import { InlineSkill, CustomTool, MemorySettings, TelemetrySettings, SystemPromptResolver, SessionStore, PermissionGate, SkillsSettings, ContextSettings } from '@theokit/sdk';
+import { AgentDefinition as AgentDefinition$1 } 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-BJJiKq33.js';
+import { R as ReasoningEffort, H as HumanInTheLoopOptions, M as McpServersMap, a as MemoryOptions, P as ProjectContextOptions, C as CheckpointOptions, T as ToolOptions, A as ApprovalOptions, B as BudgetOptions } from './types-CxI2x6mU.js';
+import { z } from 'zod';
+import { S as SettingSourcesSelection, G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-BJJiKq33.js';
+import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 
 /**
  * M9 (theokit-ai-first) — guardrail contract + typed errors.
@@ -277,6 +279,214 @@ declare class CompatImportUnsupportedError extends TheokitAgentError {
     constructor(version: string | undefined);
 }
 
+/**
+ * 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).
+ */
+
+/**
+ * One subagent, as `AgentOptions.agents` in the SDK takes it.
+ *
+ * Declared here rather than imported so the framework states its own contract: the SDK's
+ * `AgentDefinition` carries fields this bridge does not thread, and re-exporting it would promise
+ * every one of them.
+ */
+interface SubagentAgentDefinition {
+    /** What the model reads when choosing this subagent. */
+    readonly description: string;
+    /** The instructions it runs with — the field that carries an applied memory. */
+    readonly prompt: string;
+    /** Tool names it may call. Absent means the framework decides, as it does for a discovered one. */
+    readonly tools?: readonly string[];
+}
+/**
+ * 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;
+    /**
+     * theokit#363 — hard ceiling on the agent's tool-calling turns within ONE run. Reaching it ends
+     * the turn instead of letting the model keep calling tools; absent ⇒ the SDK's own ceiling (8).
+     *
+     * Named `maxIterations`, not `maxSteps`, because the concept already has exactly one name here —
+     * `@Agent({ maxIterations })`, `@MainLoop({ maxIterations })`, `AgentRunner.stream({ maxIterations })`,
+     * `delegate({ maxIterations })` — and one name in the SDK it lowers to (`SendOptions.maxIterations`).
+     * A second name would be the only place needing translation, and the translation is invisible where
+     * it costs most: the SDK rejects an invalid value with a message naming `SendOptions.maxIterations`,
+     * which an author who typed `.maxSteps()` has no way to connect to what they wrote. Familiarity
+     * argues for the ai-sdk spelling, but ai-sdk's own name is `stopWhen: stepCountIs(n)` — borrowing
+     * "steps" would buy recognition of a word, not of an API.
+     */
+    maxIterations?: number;
+    /**
+     * 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;
+    /**
+     * Subagents this agent carries, registered by name — `AgentOptions.agents` in the SDK.
+     *
+     * #825 — distinct from what `settingSources` discovers, and that distinction is the whole reason it
+     * exists. The framework reads `.claude/agents/<name>.md` itself and takes the prompt from the FILE,
+     * so a caller that enriches a definition — `applySubagentMemory` folding in a `MEMORY.md` is the
+     * measured case — had nowhere to put the result. It computed the enriched copy and the framework
+     * used the file's, with nothing reporting a difference.
+     *
+     * A name declared here and also found on disk is the same subagent; the definition given here is
+     * the one that runs, because it is the one an author decided rather than the one a loader guessed.
+     */
+    subagents?: Record<string, SubagentAgentDefinition>;
+    /**
+     * 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 (M68): `project` reads `.theokit/hooks.json`, which **executes shell**, so it requires
+     * a `TrustPosture` rather than a string. This field used to take `readonly SettingSource[]`, and
+     * its own JSDoc justified the risk as *"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
+     * an agent whose `cwd` is a repository the user just cloned, where `.theokit/` is
+     * attacker-controlled content.
+     *
+     * `user` stays a plain boolean — `~/.theokit/` is the operator's own machine. Omitting a root is
+     * not enabling it. The SDK owns discovery + execution (G2 / ADR-0040); theokit resolves the
+     * selection through `resolveSettingSources` and wires the result into
+     * `Agent.create({ local.settingSources })`.
+     */
+    settingSources?: SettingSourcesSelection;
+    /**
+     * #686 — decide whether a hook declared in a config root is spawned at all, BEFORE it runs.
+     *
+     * Covers any root, including a foreign dialect imported through `settingSources.claudeCode`.
+     * Requires `@theokit/sdk >= 5.4.0`: declaring it against an older SDK is REFUSED at assembly
+     * rather than forwarded, because a gate that silently does not gate is worse than none.
+     */
+    hookApproval?: HookApprovalGate;
+    /**
+     * B-054 — `MEMORY.md` here is NOT the Claude Code CLI's auto-memory file. This is the durable
+     * subsystem below: a SQLite+FTS5 store under `.theokit/memory/`, with `memory_search`/`memory_get`
+     * tools and no index cap. The CLI's lives under its own home (`CLAUDE_CONFIG_DIR` or `~/.claude`),
+     * is capped at 200 lines / 25 KB on read, and is swept on `cleanupPeriodDays` — none of which is
+     * implemented here. The SDK READS that directory for interop and does not write to it.
+     *
+     * Same filename, different directory, different semantics. Stated at both ends because a checklist
+     * that greps for `MEMORY.md` finds one and concludes the other exists.
+     *
+     * 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;
+    /**
+     * B-072 — OpenTelemetry for this agent. Forwarded verbatim to `Agent.create({ telemetry })`,
+     * where the SDK emits spans for `agent.send`, `llm.call`, `tool.call` and `memory.search`.
+     *
+     * `{ enabled: true }` is the minimal opt-in. `@opentelemetry/api` is an OPTIONAL peer of the SDK:
+     * without it the whole thing is a silent no-op, which is the usual reason a run reports no spans.
+     */
+    telemetry?: TelemetrySettings;
+    /**
+     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
+     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
+     */
+    /**
+     * Code plugins — `{ name, register }`. NOT the Claude Code filesystem-bundle form, which is
+     * declared by living in a `plugins/` directory rather than by being passed here (B-055).
+     *
+     * `readonly unknown[]` is what let the wrong shape through silently.
+     */
+    plugins?: readonly CodePlugin[];
+    /**
+     * 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;
+
 /**
  * Agent compiler — transforms decorator metadata into SDK calls.
  *
@@ -352,7 +562,7 @@ declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances:
  * 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;
+type CompiledSubAgent = AgentDefinition$1;
 /** Compiled agent options ready for SDK Agent.create(). */
 interface CompiledAgentOptions {
     model?: string;
@@ -372,6 +582,15 @@ interface CompiledAgentOptions {
      * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
      */
     settingSources?: readonly GatedSettingSource[];
+    /**
+     * #825 — subagents the AUTHOR declared, carried through to `AgentOptions.agents`.
+     *
+     * Beside `settingSources` on purpose: that field says which roots the SDK may DISCOVER subagents
+     * in, and this one says which subagents exist with which instructions. A caller that applied a
+     * `MEMORY.md` to a definition has only this field to put the result in — through the other, the
+     * SDK re-reads the file and the enriched copy is lost.
+     */
+    subagents?: Readonly<Record<string, SubagentAgentDefinition>>;
     /**
      * Foreign configuration dialects, already authorised (usetheokit/theokit#634).
      *
@@ -477,4 +696,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-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 };
+export { type AgentDefinition as A, type CompiledAgentOptions as C, type DefineAgentConfig as D, type Guardrail as G, type HookApprovalGate as H, type InferAgentInput as I, MalformedGuardrailResultError as M, type SkillsRequestContext as S, type ToolWalkResult as T, UnreadableTextPayloadError as U, type CompiledTool as a, AGENT_BRAND 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 InferAgentToolNames as l, type SkillsSelection as m, type ToolboxWalkResult as n, compileAgentDefinition as o, compileTools as p, isAgentDefinition as q, resolveEnabledSkills as r, type SubagentAgentDefinition as s, type CodePlugin as t };

package/dist/auth.js

@@ -1,7 +1,7 @@
 import {
   readSecureJson,
   writeSecureJson
-} from "./chunk-D2EFYZBV.js";
+} from "./chunk-4ULFP7GK.js";
 import {
   debugLog
 } from "./chunk-M5J3Q6YC.js";

package/dist/{bridge-entry-kh9JllQT.d.ts → bridge-entry-qz6EGrLd.d.ts}

@@ -1,11 +1,10 @@
 import { ExecutionContext } from '@theokit/http';
-import { c as AgentOptions, T as ToolOptions, P as ProjectContextOptions, H as HumanInTheLoopOptions, R as ReasoningEffort, M as McpServersMap } from './types-C16Wuh9E.js';
-import { a as CompiledAgentOptions, b as CompiledTool, G as Guardrail, S as SkillsSelection, H as HookApprovalGate, C as CodePlugin } from './agent-compiler-D7-Xd6Zh.js';
-import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings, TelemetrySettings } from '@theokit/sdk';
-import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-CH9Mr9NF.js';
+import { c as AgentOptions, T as ToolOptions, P as ProjectContextOptions, H as HumanInTheLoopOptions, R as ReasoningEffort, M as McpServersMap } from './types-CxI2x6mU.js';
+import { C as CompiledAgentOptions, A as AgentDefinition, a as CompiledTool, G as Guardrail, m as SkillsSelection, s as SubagentAgentDefinition, H as HookApprovalGate, t as CodePlugin } from './agent-compiler-DEMJlZNS.js';
+import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings, TelemetrySettings, PermissionRule } from '@theokit/sdk';
+import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-Bbr4zCpR.js';
 import { RetryOptions } from '@theokit/sdk/retry';
 import { SandboxPosture } from '@theokit/sdk/sandbox';
-import { A as AgentDefinition } from './define-agent-y3fsG91f.js';
 import { z } from 'zod';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 import { S as SettingSourcesSelection } from './setting-sources-gate-BJJiKq33.js';
@@ -944,6 +943,14 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * (so a long procedure only enters the prompt when it is actually needed).
      */
     skills(selection: SkillsSelection): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /**
+     * #825 — subagents this agent carries, by name, WITH whatever the caller applied to them.
+     *
+     * Distinct from `settingSources`, which DISCOVERS them: the framework reads the file and takes the
+     * prompt straight from it, so an enriched definition — a `MEMORY.md` folded in by
+     * `applySubagentMemory` is the measured case — had nowhere to go and was silently discarded.
+     */
+    subagents(map: Record<string, SubagentAgentDefinition>): 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/`,
@@ -1292,6 +1299,80 @@ interface ToolHooksPlugin {
  */
 declare function createToolHooksPlugin(hooks: ToolHooks): ToolHooksPlugin;
 
+/**
+ * What an `ask` verdict resolves to, and who decides it.
+ *
+ * MANDATORY, and that is the whole of the #826 fix rather than a detail of it. `PermissionEngine`
+ * answers `ask` for a tool no rule matches, and `PermissionPlugin.create` turns that into a hard
+ * block when no gate is supplied:
+ *
+ *     opts.onAsk ? opts.onAsk(name) : { block: true, message: `requires approval: ${name}` }
+ *
+ * So an absent gate is not "no opinion" — it is the most restrictive opinion available, applied to
+ * every tool the operator did not enumerate, and applied silently.
+ *
+ * The absence being unrepresentable is the point. `approval-posture.ts`, in this same package,
+ * already refuses this shape in writing: "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." A caller that wants everything unmatched to run says so with a gate that allows; what
+ * stops existing is the omission.
+ */
+interface PermissionsPluginOptions {
+    /**
+     * Consulted ONLY on an `ask` verdict — an explicit `allow` never reaches it, and an explicit
+     * `deny` is immune to it. May be asynchronous, so a surface with a human can await the decision.
+     */
+    readonly onAsk: (toolName: string, input: unknown) => {
+        readonly behavior: 'allow';
+    } | {
+        readonly behavior: 'deny';
+        readonly message?: string;
+    } | Promise<{
+        readonly behavior: 'allow';
+    } | {
+        readonly behavior: 'deny';
+        readonly message?: string;
+    }>;
+}
+/**
+ * The `permissions` block of a settings file, as a plugin the run enforces.
+ *
+ * ## Why this exists
+ *
+ * `permissionRulesFromSettings` has rendered that block into `PermissionRule[]` since it was written,
+ * and nothing consumed the result. Measured on 2026-09-17 across the consumer: the field is produced
+ * in `settings-json.ts` and read in no other file, so an operator's `deny` was parsed, reported as
+ * translated, and dropped.
+ *
+ * The cost was measured the same day, beside Claude Code on byte-identical configuration: it refused
+ * a `Read(./off-limits.txt)` deny rule, and this ecosystem answered with the file's contents.
+ *
+ * ## What wiring it cost before the gate was mandatory
+ *
+ * Enforcing the rules without deciding the `ask` verdict traded one defect for a worse one. Measured
+ * on the built binary the same day, with a single project rule allowing `Read(./src/**)`: `skill_read`
+ * came back "Plugin blocked this tool call: requires approval: `skill_read`" for a skill that loads
+ * correctly, and adding `"allow":["skill_read"]` made the identical call return the skill body.
+ * Delegation died the same way — which is why the symptom was first filed as a delegation defect
+ * (#828) and as a plugin-bundled-skill defect (#826), and was neither.
+ *
+ * An allow-list had silently become a whitelist-or-die: the moment an operator wrote any `permissions`
+ * block, every tool they had not enumerated stopped working, with no diagnostic naming the cause.
+ *
+ * ## Why here rather than in the consumer
+ *
+ * `PermissionEngine` and `PermissionPlugin` are SDK classes, and a consumer that names them takes a
+ * dependency on the SDK's shape for a capability it should be able to ask for by name.
+ * `createToolHooksPlugin`, next door, set that precedent.
+ *
+ * ## Why `undefined` rather than an empty plugin
+ *
+ * A plugin over an empty rule set is a gate that can only answer yes. Returning `undefined` lets the
+ * caller omit it, which keeps "no policy was configured" distinguishable from "a policy that permits
+ * everything" — and a diagnostic reading a live gate would report the second as a control in force.
+ */
+declare function createPermissionsPlugin(rules: readonly PermissionRule[], options: PermissionsPluginOptions): Plugin | undefined;
+
 /**
  * M19 (theokit-ai-first) — `processApiError`: app-level fallback around an agent run.
  *
@@ -1664,4 +1745,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { compileLoadedAgentModule as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, type EphemeralAgent as E, type McpSelection as F, type SdkAgentHandle as G, type HitlDecision as H, type SdkMessage as I, type SdkSendOptions as J, type SdkTurnHandle as K, type LLMCallContext as L, type McpApprovalSpec as M, type Segment as N, type ShouldAutoApproveOptions as O, type ProcessInputContext as P, type ToolHooks as Q, type RuntimeOverrides as R, type SkillsOptions as S, type ToolCallVeto as T, type ToolHooksPlugin as U, agentsPlugin as V, WRITE_SCOPED_TOOLS as W, applyPosture as X, buildModelSelection as Y, compileAgentModule as Z, compileContextWindow as _, type ApprovalPosture as a, compileProjectContext as a0, compileSkills as a1, createAgentExecutionContext as a2, createApiErrorHandler as a3, createSdkAgentStream as a4, createThinkTagExtractor as a5, createToolHooksPlugin as a6, extractThinkTagStream as a7, generateAgentManifest as a8, generateAgentRoutes as a9, isAgentContext as aa, loadMcpJson as ab, loadPersonalMcpServers as ac, mcpRegistry as ad, mcpToolApprovals as ae, projectContextMetadataOnlyKnobs as af, reasoningEffortOf as ag, resolveMcpServers as ah, runWithApiErrorHandling as ai, shouldAutoApprove as aj, toAgentFactory as ak, translateSdkEvent as al, withClockCap as am, withEphemeralAgent as an, type AgentModule as b, APPROVAL_MODES 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 AgentsPluginOptions as n, type ApiErrorContext as o, type ApiErrorDecision as p, type ApiErrorPolicy as q, type ApprovalMode as r, streamAgentUIMessages as s, type ApprovalRequest as t, type CompiledContextWindow as u, ContextualTool as v, DelegationTimeoutError as w, McpFileError as x, type McpRegistryConfig as y, type McpRequestContext as z };
+export { compileContextWindow as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, type EphemeralAgent as E, type McpSelection as F, type ProcessInputContext as G, type HitlDecision as H, type SdkAgentHandle as I, type SdkMessage as J, type SdkSendOptions as K, type LLMCallContext as L, type McpApprovalSpec as M, type SdkTurnHandle as N, type Segment as O, type PermissionsPluginOptions as P, type ShouldAutoApproveOptions as Q, type RuntimeOverrides as R, type SkillsOptions as S, type ToolCallVeto as T, type ToolHooks as U, type ToolHooksPlugin as V, WRITE_SCOPED_TOOLS as W, agentsPlugin as X, applyPosture as Y, buildModelSelection as Z, compileAgentModule as _, type ApprovalPosture as a, compileLoadedAgentModule as a0, compileProjectContext as a1, compileSkills as a2, createAgentExecutionContext as a3, createApiErrorHandler as a4, createPermissionsPlugin as a5, createSdkAgentStream as a6, createThinkTagExtractor as a7, createToolHooksPlugin as a8, extractThinkTagStream as a9, generateAgentManifest as aa, generateAgentRoutes as ab, isAgentContext as ac, loadMcpJson as ad, loadPersonalMcpServers as ae, mcpRegistry as af, mcpToolApprovals as ag, projectContextMetadataOnlyKnobs as ah, reasoningEffortOf as ai, resolveMcpServers as aj, runWithApiErrorHandling as ak, shouldAutoApprove as al, toAgentFactory as am, translateSdkEvent as an, withClockCap as ao, withEphemeralAgent as ap, type AgentModule as b, APPROVAL_MODES 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 AgentsPluginOptions as n, type ApiErrorContext as o, type ApiErrorDecision as p, type ApiErrorPolicy as q, type ApprovalMode as r, streamAgentUIMessages as s, type ApprovalRequest as t, type CompiledContextWindow as u, ContextualTool as v, DelegationTimeoutError as w, McpFileError as x, type McpRegistryConfig as y, type McpRequestContext as z };