@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/task-store.cjs

@@ -1,24 +1,23 @@
 'use strict';
 
-var chunkRFMBZPOW_cjs = require('./chunk-RFMBZPOW.cjs');
-require('./chunk-UALX2J2Q.cjs');
-require('./chunk-4ZHTIJNE.cjs');
-require('./chunk-XL7Q7HB2.cjs');
-require('./chunk-EG4QM7ZJ.cjs');
+var chunkHCT4HPCL_cjs = require('./chunk-HCT4HPCL.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
 
 
 
 Object.defineProperty(exports, "InMemoryTaskStore", {
   enumerable: true,
-  get: function () { return chunkRFMBZPOW_cjs.InMemoryTaskStore; }
+  get: function () { return chunkHCT4HPCL_cjs.InMemoryTaskStore; }
 });
 Object.defineProperty(exports, "JsonFileTaskStore", {
   enumerable: true,
-  get: function () { return chunkRFMBZPOW_cjs.JsonFileTaskStore; }
+  get: function () { return chunkHCT4HPCL_cjs.JsonFileTaskStore; }
 });
 Object.defineProperty(exports, "getTaskStoreFor", {
   enumerable: true,
-  get: function () { return chunkRFMBZPOW_cjs.getTaskStoreFor; }
+  get: function () { return chunkHCT4HPCL_cjs.getTaskStoreFor; }
 });
 //# sourceMappingURL=task-store.cjs.map
 //# sourceMappingURL=task-store.cjs.map

package/dist/task-store.d.cts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/task-store`.
+ *
  * Public sub-export for the Task store interface + JSON-backed
  * implementation. Used by `@theokit/cli` to read the registry
  * cross-process from disk (ADR D364 + EC-7 best-effort cancel).

package/dist/task-store.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/task-store`.
+ *
  * Public sub-export for the Task store interface + JSON-backed
  * implementation. Used by `@theokit/cli` to read the registry
  * cross-process from disk (ADR D364 + EC-7 best-effort cancel).

package/dist/task-store.js

@@ -1,7 +1,6 @@
-export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-KQRW2GPZ.js';
-import './chunk-2GUYQR5P.js';
-import './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+export { InMemoryTaskStore, JsonFileTaskStore, getTaskStoreFor } from './chunk-EIQFAOFD.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=task-store.js.map
 //# sourceMappingURL=task-store.js.map

package/dist/types/agent-prims.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/agent-loop/` (3 of 11 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
  * (audit `architecture-output/final_report.md`) per plan
@@ -114,3 +117,21 @@ export interface CustomTool {
         threadId?: string;
     }) => string | import("./content-blocks.js").ToolResultContentBlock[] | Promise<string | import("./content-blocks.js").ToolResultContentBlock[]>;
 }
+/**
+ * How the permission engine treats the UNMATCHED verdict.
+ *
+ * - `default` — ask.
+ * - `plan` — read-only.
+ * - `acceptEdits` — auto-approve the unmatched verdict, but still honour an explicit `ask` rule.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything allowed EXCEPT an
+ *   explicit `deny`. Never asks.
+ *
+ * G7 / DIP — defined in this type leaf rather than in `permission-engine.ts`, which is a RUNTIME
+ * module. `types/agent.ts`, `types/run.ts` and `types/plugin.ts` all need the union, and each one
+ * used to reach into the engine for it: three of the nine violations the `types-dont-import-runtime`
+ * rule reported the moment it was able to see type-only edges at all. The engine re-exports it, so
+ * `import type { PermissionMode } from "@theokit/sdk"` is unchanged.
+ *
+ * @public
+ */
+export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";

package/dist/types/agent.d.ts

@@ -1,13 +1,18 @@
+/**
+ * Owner: `src/` (13 of 65 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { BudgetTracker } from "./budget-tracker.js";
 import type { ContextSettings } from "./context.js";
 import type { McpServerConfig } from "./mcp.js";
 import type { MemoryProvider } from "./memory-provider.js";
 import type { PluginsSettings, ProviderRoutingSettings } from "./providers.js";
 export type { CustomTool, ModelParameterValue, ModelSelection, ToolContextMessage, } from "./agent-prims.js";
-import type { CustomTool, ModelSelection } from "./agent-prims.js";
+import type { CustomTool, ModelSelection, PermissionMode } from "./agent-prims.js";
 import type { Plugin } from "./plugin.js";
 import type { InvalidateCacheOptions, PersonalityPreset, SDKAgent, SystemPromptSkillRef } from "./sdk-agent.js";
-export type { SDKAgentPlugins, SDKAgentSkillDetail, SDKAgentSkills, SDKArtifact, SDKPluginMetadata, } from "./sdk-agent.js";
+export type { AgentOperation, SDKAgentPlugins, SDKAgentSkillDetail, SDKAgentSkills, SDKArtifact, SDKPluginMetadata, } from "./sdk-agent.js";
 export type { InvalidateCacheOptions, PersonalityPreset, SDKAgent, SystemPromptSkillRef };
 /**
  * Which on-disk settings layers a local agent loads.
@@ -15,6 +20,49 @@ export type { InvalidateCacheOptions, PersonalityPreset, SDKAgent, SystemPromptS
  * @public
  */
 export type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
+/**
+ * A foreign configuration dialect this SDK can read.
+ *
+ * A DIFFERENT axis from {@link SettingSource}, and collapsing the two would be wrong: that one is
+ * about SCOPE (user vs project, and the trust posture behind it), this one about which product's
+ * format a project wants imported. A project can legitimately want project scope with `.theokit/`
+ * only — which is now the default.
+ *
+ * @public
+ */
+export type CompatSource = "claude-code" | CompatSourceAdapter;
+/**
+ * A surface a foreign configuration source may be admitted to.
+ *
+ * They are named separately because they carry very different risk. A skill is TEXT that enters the
+ * system prompt; a subagent is a definition; a plugin is CODE LOADING; a hook is COMMAND EXECUTION.
+ * Reusing the skills you already wrote for another product is a reasonable thing to want, and it is
+ * not a reason to hand that product's directory the right to run commands.
+ *
+ * @public
+ */
+export type CompatSurface = "hooks" | "plugins" | "skills" | "subagents";
+/**
+ * A foreign source admitted to named surfaces only.
+ *
+ * ```ts
+ * local: { compatSources: [{ kind: "claude-code", import: ["skills", "subagents"] }] }
+ * ```
+ *
+ * `import` is not optional in spirit even though it is in the type: an adapter that omits it
+ * imports NOTHING. That is deliberate and it is the fail-closed rule this whole option exists to
+ * serve — a typo in a surface name must narrow access, never widen it.
+ *
+ * The bare `"claude-code"` string keeps meaning every surface. It is what `5.0.0-next.1` published,
+ * and silently narrowing it would turn a working opt-in into a no-op that says nothing — which is
+ * the defect usetheokit/theokit-sdk#524 reports, one level up.
+ *
+ * @public
+ */
+export interface CompatSourceAdapter {
+    readonly kind: "claude-code";
+    readonly import?: readonly CompatSurface[];
+}
 /**
  * A tool the SDK declares to the model on its own initiative — not one the consumer passed in
  * {@link AgentOptions.tools}, and not one an MCP server exposed.
@@ -59,6 +107,27 @@ export interface LocalOptions {
      */
     cwd?: string | string[];
     settingSources?: SettingSource[];
+    /**
+     * Foreign configuration dialects to import. Default: none — `.theokit/` only.
+     *
+     * `.claude/` used to be read unconditionally across hooks, plugins, skills and subagents, so a
+     * repository that merely had Claude Code set up had its hooks executed, its skills folded into
+     * the system prompt and its subagents registered, having configured nothing for this SDK
+     * (usetheokit/theokit-sdk#524). One consequence was every turn being denied, because those hook
+     * commands are written against a runtime that defines `$CLAUDE_PROJECT_DIR` and this one did not
+     * (#522).
+     *
+     * A trust gate answers "do I trust the code in this directory?". That is a different question
+     * from "do I want another product's configuration imported into this one?", and they come apart
+     * in the ordinary case: a repository you trust completely is exactly where `.claude/` is
+     * populated — for a different tool, by a different contract, often by a teammate who never heard
+     * of this SDK.
+     *
+     * Listing a dialect is all-or-nothing for that dialect, and restores exactly the previous
+     * behaviour. On a name collision `.theokit/` wins: the native definition is the one the project
+     * wrote for this runtime.
+     */
+    compatSources?: CompatSource[];
     sandboxOptions?: {
         enabled: boolean;
     };
@@ -139,6 +208,20 @@ export interface CloudOptions {
 export interface AgentDefinition {
     description: string;
     prompt: string;
+    /**
+     * Absolute path to the `.md` this subagent was read from, when it came from disk.
+     *
+     * ABSENT for a subagent declared in code through {@link AgentOptions.subagents} — "you passed
+     * this one in" is a different fact from "read from disk", and one value for both would trade one
+     * silence for another.
+     *
+     * It exists so a listing can answer which root a subagent came from, which
+     * usetheokit/theokit-sdk#524 asks for by name: a consumer could not tell that an agent arrived
+     * from `.claude/agents/` rather than its own directory, and silent inheritance is what made that
+     * take a debugging session to notice. `HookCommand.sourcePath` and `Skill.source` already
+     * answered it for the other two surfaces.
+     */
+    source?: string;
     model?: ModelSelection | "inherit";
     mcpServers?: Array<string | Record<string, McpServerConfig>>;
     /**
@@ -436,7 +519,7 @@ export interface AgentOptions {
      * `SendOptions.permissionMode` overrides it. Absent ⇒ the plugin's own
      * construction-time mode applies. Local runtime.
      */
-    permissionMode?: import("../permission-engine.js").PermissionMode;
+    permissionMode?: PermissionMode;
     /**
      * Skills configuration. Either a static {@link SkillsSettings} object or —
      * SE22 — a {@link SkillsResolver} evaluated per `send()` to pick skills from
@@ -634,12 +717,18 @@ export interface AgentOptions {
      * inversion). When provided, the agent loop calls `tracker.track(...)`
      * after each LLM completion and `tracker.check()` before each iteration.
      *
-     * **Status (Phase 2 incremental):** the option is wired to the type
-     * surface only. Agent-loop runtime wiring is additive and lands in a
-     * subsequent iteration — for now, the kernel still uses the legacy
-     * `UsageAccumulator` + `IterationBudget` from `internal/budget/`.
-     * Consumers passing a custom tracker today get the type guarantee but
-     * NOT runtime enforcement.
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop.ts:78-81` reads the tracker and
+     * gates the iteration through `evaluateBudgetGate`, `:110` calls
+     * `nextIteration()`, and `:390`/`:397` call `track(...)` per completion;
+     * the option reaches the loop from `AgentOptions` at
+     * `internal/local-agent/real-local-run.ts:342`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement" — and it was wrong in the expensive stale-claim-ok: verbatim quote of the corrected text
+     * direction: a consumer reading the published `.d.ts` was told the SDK would
+     * not enforce their cost ceiling, so the rational response was to build a
+     * second control outside it, or to stop trusting the option.
      *
      * Default impls available today via `@theokit/sdk`:
      *   - `createCounterBudgetTracker({ maxTokens, maxIterations })`
@@ -658,12 +747,17 @@ export interface AgentOptions {
      * pre-LLM to inject recalled facts, and `provider.dispose(...)` on
      * Agent shutdown.
      *
-     * **Status (Phase 1 incremental):** the option is wired to the type
-     * surface only. Agent-loop runtime wiring is additive and lands in
-     * subsequent iterations (T1.4 plumbing, T1.5 runtime hooks). For now,
-     * the kernel still uses the legacy `Memory` class + `internal/memory/*`
-     * runtime files. Consumers passing a custom provider today get the type
-     * guarantee but NOT runtime enforcement.
+     * **Runtime enforcement is live.** Verified against the call graph on
+     * 2026-09-01: `internal/agent-loop/loop-context-init.ts:95` calls
+     * `provider.init(...)`, `:129` surfaces `provider.buildTools(...)` to the
+     * model, `:166` runs `provider.runActivePass(...)`, and
+     * `internal/agent-loop/loop.ts:176`/`:204` call `sync` and `dispose`.
+     *
+     * This paragraph previously said the opposite — "wired to the type surface
+     * only ... NOT runtime enforcement". A stale "not implemented yet" note on a stale-claim-ok: verbatim quote of the corrected text
+     * `@public` symbol is worse than no note: it is believed, it survives the
+     * work it describes, and nothing in this repo compares such a claim against
+     * the call graph.
      *
      * Default impls available today via `@theokit/sdk`:
      *   - `createNoopMemoryProvider()` — degenerate fallback / worked example

package/dist/types/batch.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public types for `Agent.batch` (ADRs D134-D140).
  *
  * Run N prompts in parallel with bounded concurrency. Each prompt gets

package/dist/types/budget-tracker.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/budget/tracker/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `BudgetTracker` — runtime contract for budget/usage tracking in the
  * agent loop (SDK 2.0 Phase 2 / T2.1 — ADR D1 interface inversion).
  *

package/dist/types/budget.d.ts

@@ -1,13 +1,22 @@
 /**
+ * Owner: `internal/budget/` (4 of 6 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Budget enforcement primitive
  * (ADRs D375, D382-D387). The runtime facade lives in `budget.ts`.
  *
  * @public
  */
 /**
- * Scope of a budget — where the charge is attributed. v1 supports
- * `process` (shared global) only; `agent` and `call` reserved for
- * v0.2 multi-tenant scenarios.
+ * Accounting scope for a budget.
+ *
+ * ONLY `"process"` is implemented, and `Budget.create` now REFUSES the other two with
+ * `unimplemented_budget_scope`. It used to accept them: nothing outside the registry read `scope`, so
+ * a caller asking for per-agent accounting silently got process-wide accounting — a cost control
+ * reporting the wrong number, which is worse than the missing feature.
+ *
+ * The union is not narrowed to `"process"` here because that is a breaking change to a published
+ * type and belongs to a major. Widening it back when the scopes are built is non-breaking.
  */
 export type BudgetScope = "agent" | "call" | "process";
 /**

package/dist/types/content-blocks.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (2 of 7 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Leaf module for content-block types shared by `messages.ts` (assistant/user
  * content) and `agent-prims.ts` (`CustomTool` handler results). Kept
  * import-free so both can depend on it WITHOUT the `agent-prims ↔ messages`

package/dist/types/context.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Context manager backend.
  *
  * - `"file"` — Read `.theokit/context.json` from the workspace (local) or the

package/dist/types/conversation.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/agent-loop/` (4 of 8 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { ToolCall } from "./updates.js";
 export type { UserMessage } from "./messages-base.js";
 import type { UserMessage } from "./messages-base.js";

package/dist/types/cron.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/cron/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { Workflow } from "../workflow.js";
 import type { AgentOptions } from "./agent.js";
 import type { SDKUserMessage } from "./run.js";

package/dist/types/env-policy.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `sandbox/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Child-process environment policy contract (#54).
  *
  * The DIP-correct home for the `EnvPolicy` contract type: the domain `types/`

package/dist/types/eval.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/eval/` (5 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for `Eval.create / .run` and the `Scorers` namespace
  * (Adoption Roadmap #2; ADRs D202-D213).
  *

package/dist/types/fork.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/runtime/lifecycle/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Fork primitive public type contracts (T1.2, ADRs D110-D114).
  *
  * Extracted into a leaf type module (arch-review ADR 0001) so the public

package/dist/types/goal-events.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/judge/` (3 of 8 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * M80 — the terminal verdicts a judge can return.
  *
  * `"blocked"` was added here in this milestone. `GoalResult.status` already carried it, but the

package/dist/types/mcp.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/mcp/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { EnvPolicy } from "./env-policy.js";
 /**
  * MCP server configuration accepted by `Agent.create()` and `agent.send()`.

package/dist/types/memory-adapter.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/local-agent/` (2 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public `MemoryAdapter` contract (T1.1, ADRs D141 / D147).
  *
  * The plugin extension point `{ kind: "memory" }` (ADR D98) declares a

package/dist/types/memory-provider.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/memory/storage/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * `MemoryProvider` — kernel-facing port for the memory subsystem
  * (SDK 2.0 Phase 1 / T1.1 — Hexagonal Architecture / Ports & Adapters,
  * SOLID Dependency Inversion).
@@ -10,7 +13,7 @@
  *
  * DIP-correct home (SE46): the port + companion contract types live in the
  * domain `types/` layer; the application-layer module
- * (`internal/runtime/memory/memory-provider.ts`) re-exports them for
+ * (`internal/runtime/memory-glue/memory-provider.ts`) re-exports them for
  * back-compat while the concrete providers live under `internal/`.
  *
  * Layered model (mirrors Budget):
@@ -21,9 +24,26 @@
  *
  * @public — surface-level interface; impls are internal-but-replaceable.
  */
-import type { CustomTool } from "./agent-prims.js";
+import type { CustomTool, ModelSelection } from "./agent-prims.js";
 import type { MemoryAdapter, MemoryFact } from "./memory-adapter.js";
-import type { SDKAgent } from "./sdk-agent.js";
+/**
+ * The agent identity a `MemoryProvider` is given — the whole of it.
+ *
+ * `buildTools` used to declare `agent: SDKAgent`, a 33-member interface, and the agent loop satisfied
+ * it with `{ agentId, model } as SDKAgent`. The cast is what made it compile, and it suppressed
+ * exactly the check that mattered: an implementation reaching for any of the other 31 members —
+ * `send()`, `fork()`, `dispose()` — gets `undefined is not a function` at runtime with no
+ * compile-time signal.
+ *
+ * Two fields is what the port actually offers, so two fields is what it declares. `SDKAgent`
+ * structurally satisfies this, so a caller holding a real agent still passes it, and TypeScript's
+ * bivariant method parameters mean an existing implementation typed `agent: SDKAgent` still compiles.
+ * What changes is that the fabricated ref no longer needs a cast to exist.
+ */
+export interface MemoryProviderAgentRef {
+    readonly agentId: string;
+    readonly model: ModelSelection | undefined;
+}
 /** Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call. */
 export interface ActiveMemoryPassResult {
     /** Compressed memory facts to seed the LLM's context window for this turn. */
@@ -73,7 +93,7 @@ export interface RecordSessionSummaryArgs {
      * rather than optional. An implementation that recomputed it from `cwd` would write the summary
      * into a different directory than the one the rest of the subsystem uses (#463).
      */
-    readonly memoryRoot: import("../internal/memory/storage/memory-root.js").MemoryRoot;
+    readonly memoryRoot: MemoryRoot;
     /** Run id used as the filename key. */
     readonly runId: string;
     /** Agent identity for scope (foldering). */
@@ -121,7 +141,7 @@ export interface MemoryProvider {
     /** Construct or fetch the per-agent handle. Lazy + idempotent. */
     init(opts: MemoryProviderInitOptions): Promise<MemoryProviderHandle>;
     /** Build the LLM-facing tool catalog (memory_search, memory_get, …). */
-    buildTools(handle: MemoryProviderHandle, agent: SDKAgent): ReadonlyArray<CustomTool>;
+    buildTools(handle: MemoryProviderHandle, agent: MemoryProviderAgentRef): ReadonlyArray<CustomTool>;
     /** Run the active-memory pre-LLM pass — recall + compress + format. */
     runActivePass(handle: MemoryProviderHandle, args: ActiveMemoryPassArgs): Promise<ActiveMemoryPassResult>;
     /**
@@ -165,3 +185,22 @@ export interface MemoryProvider {
     /** Release the handle (close index, flush caches). Idempotent + non-throwing. */
     dispose(handle: MemoryProviderHandle): Promise<void> | void;
 }
+/**
+ * A directory that has been RESOLVED as a memory root, distinguished from a bare `cwd`.
+ *
+ * Structural rather than a `unique symbol` brand: a `unique symbol` is identity-based and the d.ts
+ * bundler inlines the declaration into each package that re-exports it, so `@theokit/sdk-memory`
+ * ended up with a `MemoryRoot` its own compiler considered incompatible with the SDK's, on values
+ * that were the same string. A structural tag refuses a bare `string` exactly as well and survives
+ * the package boundary, which is where this type has to work.
+ *
+ * G7 / DIP — defined HERE, in the domain types layer, rather than in
+ * `internal/memory/storage/memory-root.ts`. It was defined in the adapter and reached for from this
+ * file, which made the port depend on the adapter for a field of its own argument type; the runtime
+ * helpers (`resolveMemoryRoot`, `asMemoryRoot`) stay in the adapter and import it from here.
+ *
+ * @public
+ */
+export type MemoryRoot = string & {
+    readonly __memoryRoot: "resolved";
+};

package/dist/types/messages-base.d.ts

@@ -1,4 +1,8 @@
 /**
+ * Owner: `types/` (2 of 2 importers: conversation.ts, updates.ts). The only module in this folder
+ * whose owner IS the layer — it exists to break a type-only cycle BETWEEN two of its siblings, so
+ * pointing it at a subsystem would name something that does not use it.
+ *
  * Type-leaf — base message types shared between `conversation.ts` and
  * `updates.ts`. Extracted to break LOW type-only cycle #6 (audit
  * `architecture-output/final_report.md`) per plan arch-review-fixes-2026-06-06

package/dist/types/messages.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Owner: `internal/agent-loop/` (4 of 16 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ */
 import type { ModelSelection } from "./agent-prims.js";
 import type { TextBlock } from "./content-blocks.js";
 export type { ImageBlock, TextBlock, ToolResultContentBlock } from "./content-blocks.js";

package/dist/types/plugin.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/plugins/` (3 of 3 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Plugin contract types (T1.1, ADRs D97-D101).
  *
  * Discriminated union by `kind`:
@@ -17,7 +20,7 @@
  *
  * @public
  */
-import type { CustomTool } from "./agent-prims.js";
+import type { CustomTool, PermissionMode } from "./agent-prims.js";
 import type { MemoryAdapter } from "./memory-adapter.js";
 import type { ProviderProfile } from "./provider-profile.js";
 /**
@@ -68,7 +71,7 @@ export interface PreToolCallContext {
      * gate per-run rather than at construction time. Absent ⇒ the plugin's own
      * default applies. Ignored by non-permission plugins.
      */
-    permissionMode?: import("../permission-engine.js").PermissionMode;
+    permissionMode?: PermissionMode;
 }
 /**
  * The veto a `pre_tool_call` handler returns to stop a tool call. Returning `undefined` allows it —
@@ -214,6 +217,12 @@ export type CommandHandler = (args: Record<string, unknown>) => Promise<string>
 export interface CommandOptions {
     description?: string;
 }
+/**
+ * Detaches a hook handler attached with {@link PluginContext.on}. Idempotent.
+ *
+ * @public
+ */
+export type PluginHookDisposer = () => void;
 /**
  * The registration surface passed to a `"general"` plugin's `register(ctx)`, and the plugin's only
  * route into the agent. Outside production it is a sealed Proxy that throws when a plugin assigns a
@@ -228,14 +237,33 @@ export interface CommandOptions {
  * has no effect on a programmatic run. And `on` drops a handler that is not a function, with a
  * warning on stderr rather than an error at registration: the gentler failure, and the easier one to
  * miss.
+ *
+ * `on` returns a {@link PluginHookDisposer}: calling it detaches that one handler, and calling it
+ * again is a no-op. A plugin that registers a hook per run and never detaches is the leak this
+ * exists to make fixable.
+ *
+ * @public
  */
 export interface PluginContext {
     /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */
     registerTool(tool: CustomTool): void;
     /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */
     registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;
-    /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */
-    on(hook: HookName, handler: HookHandler): void;
+    /**
+     * Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`.
+     *
+     * Returns a disposer that detaches THIS handler. Calling it twice is a no-op, and a handler the
+     * SDK refused (a non-function, which is warned and ignored) returns a disposer that does nothing —
+     * so the caller never has to branch on whether the registration took.
+     *
+     * It used to return `void`, which made this a one-way door: a plugin registered through
+     * `initialize()` had no removal path and its handlers ran for the life of the process. The one
+     * documented dynamic case — the ACP permission plugin, re-installed on every prompt — worked only
+     * because `#byName` keys the replacement, so re-registering the WHOLE plugin was the only way to
+     * detach one hook. Two observers in this package already return their own disposer
+     * (`FixtureRunBase.onDidChangeStatus`) or offer an explicit removal (`MessageBus.unregister`).
+     */
+    on(hook: HookName, handler: HookHandler): PluginHookDisposer;
     /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */
     injectMessage(content: string, role?: "user" | "system"): void;
 }

package/dist/types/processors.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/runtime/processors/` (3 of 4 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
  * the user message (input) or the model's final text (output). Processors run in
  * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced

package/dist/types/provider-profile.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `internal/providers/` (1 of 1 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * ProviderProfile + ApiMode + AuthType contract types (T3.1, ADR D105).
  *
  * Profile is **data-only** — no methods. Adding a provider is declaring an

package/dist/types/providers.d.ts

@@ -1,4 +1,7 @@
 /**
+ * Owner: `src/` (4 of 9 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Capability slot a provider can fulfill.
  *
  * @public