@theokit/agents 14.5.1 → 15.0.1

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # @theokit/agents
 
+## 15.0.1
+
+### Patch Changes
+
+- 80509ca: Docblock-only: the three-target parity rule is cited at the path this repository versions.
+
+  The comment in `in-process-turn.ts` pointed at the kit-relative form of that path <!-- rule-citation-ok: naming the stale form here is what the entry is about -->, which resolves
+  nowhere for anyone who clones — `.claude/` is gitignored. The document it means is
+  `docs/program/three-target-parity.md`, tracked and 102 lines. No behaviour changes and no export
+  moves; the patch exists because the changeset gate reads a changed publishable package and cannot
+  tell a comment from a contract, which is the right default for it to have.
+
+## 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
@@ -138,19 +140,32 @@ and only that key, and returns empty on a malformed file rather than throwing, b
 in a shared home file must not break every project on the machine.
 
 Both MCP readers are called by the host, not from inside this package — `loadMcpJson` has no internal
-caller either, and a library with no `main()` cannot have one. That is why both rows say **read** while
-`agent-memory/` says **resolvable**: the difference is not who calls, it is whether the chain is intact.
-A `memory:` declaration was DROPPED by `@theokit/sdk` before any reader could see it; nothing drops an
-MCP server.
+caller either, and a library with no `main()` cannot have one. That is why both rows say **read**: the
+criterion is not who calls, it is whether the chain is intact. Nothing drops an MCP server.
+
+`agent-memory/` said **resolvable** under the same criterion, and for a real reason — a `memory:`
+declaration was DROPPED by `@theokit/sdk` before any reader could see it, so the applier could be called
+and still govern nothing. **That is no longer true**, which is why its row says `read` now. The SDK
+carries the declaration, `packages/agents/tests/integration/the-sdk-version-that-parses-memory.test.ts`
+pins the half that was dangerous, and `apps/theocode/packages/agent/src/delegation/role-discovery.ts:84-85`
+is the join. The sentence above outlived the fix for two days, which is the shape this whole section
+exists to catch: the table was corrected and the paragraph explaining it was not.
 
 The registry entry that prompted this counts four decisions across three files, because
 `~/.claude.json` is split. That is the count, stated so nobody goes looking for a fourth file.
 
 ### `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 +222,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 +298,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-DMQcLHIs.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,213 @@ 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. 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 +561,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 +581,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 +695,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.d.ts

@@ -71,27 +71,22 @@ declare class AuthProvider {
  * round-trip that stores nothing. The `AuthProvider` docblock instructed exactly that:
  * *"the caller persists them via `AuthProvider.persist`"*.
  *
- * ## The design came from measuring three peers, and it refuted the original proposal
- *
- * - **`codex`** — `codex-rs/login/src/device_code_auth.rs:234` has `run_device_code_login`, which
- *   returns `()`: **nothing** comes out for the caller to persist, and the two granular halves stay
- *   public. `loginWithDevice` copies that shape.
- * - **`opencode`** — every provider is an object with `methods: [{ label, type, authorize }]`, and
- *   three providers written by different authors converge on **3 labelled methods** each. The label
- *   is what the UI shows: it turns a protocol choice into a choice between readable phrases.
- * - **REJECTED — a `kind` discriminant.** None of the three discriminates protocol by field. The
- *   measurement that closes the case: in `opencode`, Codex's browser and headless methods carry the
- *   **same** `type: 'oauth'` — so `type` classifies the **kind of credential**, not the protocol. A
- *   `kind` with internal dispatch would be a `switch`, exactly the defect this milestone removes
- *   from the consumer. Here, each method points at **its own** function.
+ * ## The shape, and the discriminant that was rejected
+ *
+ * `loginWithDevice` returns `()` — nothing comes out for the caller to persist, and the two granular
+ * halves stay public. A provider is an object with `methods: [{ label, type, authorize }]`, and the
+ * label is what the UI shows: it turns a protocol choice into a choice between readable phrases.
+ *
+ * **REJECTED — a `kind` discriminant.** `type` classifies the **kind of credential**, not the
+ * protocol: a browser method and a headless one can both be `type: 'oauth'`. A `kind` with internal
+ * dispatch would be a `switch`, exactly the defect this milestone removes from the consumer. Here,
+ * each method points at **its own** function.
  *
  * ## Why the public identity lives HERE
  *
- * `codex` exports `CLIENT_ID` from the crate that implements the flow (`login/src/lib.rs:32`) and
- * the CLI **imports** it; `opencode` declares it inside the plugin. The two arrived at the same
- * place independently — and with the same value the consumer had copied. As long as it lived in the
- * consumer, every project wanting Codex would copy four public constants: a DRY violation across the
- * boundary, with two owners of the same fact.
+ * The client identity belongs beside the flow that uses it rather than in the consumer, so a surface
+ * cannot hold a stale copy of it.
+ *
  */
 /**
  * A labelled way of obtaining a credential within a provider.
@@ -128,10 +123,9 @@ interface DeviceAuthProvider {
     readonly methods: readonly AuthMethod[];
 }
 /**
- * Environment override for `clientId` — adopted from `codex`, which exports `CLIENT_ID` **and**
- * `CLIENT_ID_OVERRIDE_ENV_VAR` (`login/src/lib.rs:32-33`). It dissolves the false dilemma between a
- * fixed constant (inflexible) and a mandatory parameter (which hands the copy back to the consumer):
- * a default in the package, an escape for whoever needs one.
+ * Environment override for `clientId`. It dissolves the false dilemma between a fixed constant
+ * (inflexible) and a mandatory parameter (which hands the copy back to the consumer): a default in
+ * the package, an escape for whoever needs one.
  */
 declare const CODEX_CLIENT_ID_ENV_VAR = "THEOKIT_CODEX_CLIENT_ID";
 /**
@@ -157,10 +151,9 @@ interface LoginWithDeviceOptions {
  * Authorizes **and** persists, in one call. Returns where the credential landed and the account it
  * was attributed to — **never** token material.
  *
- * The shape comes from `run_device_code_login` (`codex`), which returns `()`: if nothing comes out
- * for the caller, there is no step it can forget. The two halves stay public on `AuthProvider`
- * (`deviceLogin` / `persist`) for whoever needs the granularity — the same choice `codex` makes by
- * keeping `request_device_code` and `complete_device_code_login` public alongside the facade.
+ * Nothing comes out for the caller, so there is no step it can forget. The two halves stay public on
+ * `AuthProvider` (`deviceLogin` / `persist`) for whoever needs the granularity, alongside this
+ * facade.
  *
  * It delegates verbatim: `method.authorize` runs the flow and `AuthProvider.persist` writes. Copying
  * the sequence instead of calling it would create a second oracle over the same fact, and two oracles

package/dist/auth.js

@@ -1,13 +1,13 @@
 import {
   readSecureJson,
   writeSecureJson
-} from "./chunk-D2EFYZBV.js";
+} from "./chunk-4ULFP7GK.js";
 import {
   debugLog
 } from "./chunk-M5J3Q6YC.js";
 import {
   ConfigurationError
-} from "./chunk-U72XTMYB.js";
+} from "./chunk-Q65ZIFNK.js";
 import {
   currentOperatorPolicy
 } from "./chunk-2SP5BB6U.js";