@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/internal/persistence/paths.d.cts

@@ -26,6 +26,7 @@
  *
  * @internal
  */
+import { type CompatSourceDeclaration, type CompatSurface } from "../runtime/compat/foreign-config-sources.js";
 /**
  * Resolve the directory cwd-anchored SDK state lives in.
  *
@@ -48,12 +49,31 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * The project's own configuration root: `<cwd>/.theokit`, always — never `THEOKIT_HOME`.
+ *
+ * `THEOKIT_HOME` relocates cwd-anchored SDK STATE (sessions, credentials). A project's
+ * CONFIGURATION belongs to the repository: hooks, MCP servers, context sources, subagents, the
+ * personality a project declares, all committed to git and shared by a team. Following the
+ * override for any of them would move where a project's declared capabilities come from — a
+ * behaviour change wearing the costume of a refactor, which is exactly what this function exists
+ * to make impossible to do by accident: every config-class reader calls this instead of writing
+ * `join(cwd, ".theokit")` by hand.
+ *
+ * NOT for the `.claude/`-style foreign roots {@link adaptersForSurface} adds — those are additive,
+ * opt-in, and each has its own directory name.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function theokitConfigRoot(cwd: string): string;
 /**
  * Every directory a project's configuration may be read from, in precedence order.
  *
- * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
- * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
- * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ * `.theokit` first — via {@link theokitConfigRoot}, so it is NEVER affected by `THEOKIT_HOME` for
+ * the reason documented there — then `.claude`. The order is the whole contract: a project that
+ * declares a skill, agent or rule in both means the explicit namespace to win, and a caller merging
+ * these roots must therefore keep the FIRST occurrence of a name rather than the last.
  *
  * `.claude` is read because the formats already agree and only the location did not. Measured
  * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
@@ -63,19 +83,12 @@ export declare function getTheokitHome(cwd: string): string;
  * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
  * working — which is why this returns a LIST and not a single resolved answer.
  *
- * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
- * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
- * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
- * loaders that read these directories have always anchored on `cwd` directly. Honouring the
- * override here would silently move where a project's agents and skills come from, which is a
- * behaviour change wearing the costume of a refactor.
- *
  * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
  *
  * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
  * declares in `exports` but does NOT cover with its semver contract.
  */
-export declare function projectConfigRoots(cwd: string): string[];
+export declare function projectConfigRoots(cwd: string, sources: readonly CompatSourceDeclaration[], surface: CompatSurface): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +102,7 @@ export declare function projectConfigRoots(cwd: string): string[];
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string): string[];
+export declare function pluginBundleRoots(cwd: string, sources: readonly CompatSourceDeclaration[]): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/persistence/paths.d.ts

@@ -26,6 +26,7 @@
  *
  * @internal
  */
+import { type CompatSourceDeclaration, type CompatSurface } from "../runtime/compat/foreign-config-sources.js";
 /**
  * Resolve the directory cwd-anchored SDK state lives in.
  *
@@ -48,12 +49,31 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * The project's own configuration root: `<cwd>/.theokit`, always — never `THEOKIT_HOME`.
+ *
+ * `THEOKIT_HOME` relocates cwd-anchored SDK STATE (sessions, credentials). A project's
+ * CONFIGURATION belongs to the repository: hooks, MCP servers, context sources, subagents, the
+ * personality a project declares, all committed to git and shared by a team. Following the
+ * override for any of them would move where a project's declared capabilities come from — a
+ * behaviour change wearing the costume of a refactor, which is exactly what this function exists
+ * to make impossible to do by accident: every config-class reader calls this instead of writing
+ * `join(cwd, ".theokit")` by hand.
+ *
+ * NOT for the `.claude/`-style foreign roots {@link adaptersForSurface} adds — those are additive,
+ * opt-in, and each has its own directory name.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function theokitConfigRoot(cwd: string): string;
 /**
  * Every directory a project's configuration may be read from, in precedence order.
  *
- * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
- * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
- * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ * `.theokit` first — via {@link theokitConfigRoot}, so it is NEVER affected by `THEOKIT_HOME` for
+ * the reason documented there — then `.claude`. The order is the whole contract: a project that
+ * declares a skill, agent or rule in both means the explicit namespace to win, and a caller merging
+ * these roots must therefore keep the FIRST occurrence of a name rather than the last.
  *
  * `.claude` is read because the formats already agree and only the location did not. Measured
  * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
@@ -63,19 +83,12 @@ export declare function getTheokitHome(cwd: string): string;
  * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
  * working — which is why this returns a LIST and not a single resolved answer.
  *
- * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
- * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
- * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
- * loaders that read these directories have always anchored on `cwd` directly. Honouring the
- * override here would silently move where a project's agents and skills come from, which is a
- * behaviour change wearing the costume of a refactor.
- *
  * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
  *
  * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
  * declares in `exports` but does NOT cover with its semver contract.
  */
-export declare function projectConfigRoots(cwd: string): string[];
+export declare function projectConfigRoots(cwd: string, sources: readonly CompatSourceDeclaration[], surface: CompatSurface): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +102,7 @@ export declare function projectConfigRoots(cwd: string): string[];
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string): string[];
+export declare function pluginBundleRoots(cwd: string, sources: readonly CompatSourceDeclaration[]): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/persistence/transcript-ops.d.cts

@@ -27,10 +27,19 @@ import { TheokitAgentError } from "../../errors.js";
  *
  * Typed rather than a bare `Error` because the caller must distinguish "this session is protected"
  * from "the disk is full": the first is a correct refusal, the second is an incident.
+ *
+ * RENAMED from `LiveSessionError` (2026-09-01). `session-guard.ts` exports a DIFFERENT class of that
+ * name from the root barrel, with an incompatible shape — `(sessionId, reason)` and a `reason`
+ * field, against this one's `(path)` and `code: "live_session_protected"` — and `.` and
+ * `./persistence` are both declared subpaths, so one consumer can hold both. `instanceof` never
+ * crossed the pair, so a `catch` checking the root import silently missed this one and ran its
+ * fallback for a condition it believed it handled; `err.name` matched BOTH, so a name check looked
+ * right and then read `err.reason`, which only the other one has. The names now say what each
+ * refusal is about: destroying a SESSION, versus overwriting a TRANSCRIPT file.
  */
-export declare class LiveSessionError extends TheokitAgentError {
+export declare class LiveTranscriptError extends TheokitAgentError {
     readonly path: string;
-    readonly name = "LiveSessionError";
+    readonly name = "LiveTranscriptError";
     constructor(path: string);
 }
 /** Options for {@link forkTranscript}. */

package/dist/internal/persistence/transcript-ops.d.ts

@@ -27,10 +27,19 @@ import { TheokitAgentError } from "../../errors.js";
  *
  * Typed rather than a bare `Error` because the caller must distinguish "this session is protected"
  * from "the disk is full": the first is a correct refusal, the second is an incident.
+ *
+ * RENAMED from `LiveSessionError` (2026-09-01). `session-guard.ts` exports a DIFFERENT class of that
+ * name from the root barrel, with an incompatible shape — `(sessionId, reason)` and a `reason`
+ * field, against this one's `(path)` and `code: "live_session_protected"` — and `.` and
+ * `./persistence` are both declared subpaths, so one consumer can hold both. `instanceof` never
+ * crossed the pair, so a `catch` checking the root import silently missed this one and ran its
+ * fallback for a condition it believed it handled; `err.name` matched BOTH, so a name check looked
+ * right and then read `err.reason`, which only the other one has. The names now say what each
+ * refusal is about: destroying a SESSION, versus overwriting a TRANSCRIPT file.
  */
-export declare class LiveSessionError extends TheokitAgentError {
+export declare class LiveTranscriptError extends TheokitAgentError {
     readonly path: string;
-    readonly name = "LiveSessionError";
+    readonly name = "LiveTranscriptError";
     constructor(path: string);
 }
 /** Options for {@link forkTranscript}. */

package/dist/internal/plugins/context.d.cts

@@ -1,13 +1,3 @@
-/**
- * PluginContext implementation + dev-mode seal (T1.2, ADR D99).
- *
- * `createPluginContext()` returns a fresh `{ ctx, registrations }` pair
- * for each plugin. In dev mode (`NODE_ENV !== "production"`) the context
- * is wrapped in a Proxy that throws on `set`/`delete` to catch plugin
- * abuse early. In production the raw impl is returned (zero overhead).
- *
- * @internal
- */
 import type { CommandHandler, HookHandler, HookName, PluginContext } from "./types.js";
 interface CommandEntry {
     name: string;

package/dist/internal/plugins/context.d.ts

@@ -1,13 +1,3 @@
-/**
- * PluginContext implementation + dev-mode seal (T1.2, ADR D99).
- *
- * `createPluginContext()` returns a fresh `{ ctx, registrations }` pair
- * for each plugin. In dev mode (`NODE_ENV !== "production"`) the context
- * is wrapped in a Proxy that throws on `set`/`delete` to catch plugin
- * abuse early. In production the raw impl is returned (zero overhead).
- *
- * @internal
- */
 import type { CommandHandler, HookHandler, HookName, PluginContext } from "./types.js";
 interface CommandEntry {
     name: string;

package/dist/internal/plugins/types.d.cts

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PluginHookDisposer, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

package/dist/internal/plugins/types.d.ts

@@ -11,7 +11,7 @@
  * @public
  */
 import type { Plugin as PluginType } from "../../types/plugin.js";
-export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
+export type { CommandHandler, CommandOptions, HookHandler, HookName, LlmCallContext, MemoryProviderFactory, PluginContext, PluginHookDisposer, PostAssistantReplyContext, PostToolCallContext, PreToolCallContext, PreToolCallDecision, PreUserSendContext, PreUserSendResult, SessionLifecycleContext, ToolCallSummary, ToolContext, ToolResultTransformContext, TransformContext, } from "../../types/plugin.js";
 export type Plugin = PluginType;
 /**
  * Identity helper for plugin authors. TS-only convenience — preserves

package/dist/internal/providers/catalog-schema.d.ts

@@ -105,4 +105,98 @@ export type CatalogModel = z.infer<typeof catalogModelSchema>;
  * the parsed value.
  */
 export type CatalogModelCost = z.infer<typeof costSchema>;
+/**
+ * One provider entry in the vendored catalog.
+ *
+ * LOOSE like `catalogModelSchema` beside it, and for the same reason: this validates a vendored data
+ * file that upstream extends over time, so unknown keys are kept rather than rejected. What it does
+ * NOT do is what the hand-rolled check it replaced did — assert. That check tested nine fields with
+ * `typeof`/`Array.isArray` and then cast the whole object through `as unknown as CatalogEntry`, so
+ * `capabilities`' contents, `aliases`, `modelsUrl`, `hostname`, `extraHeaders` and `models` were
+ * declared and never checked. Standing next to zod — one of this package's three runtime
+ * dependencies — and reimplementing a worse version of it is the Don't-Reinvent rung of
+ * `rules/parsimony-ladder.md`.
+ *
+ * `apiMode` and `authType` are the closed unions from `types/provider-profile.ts`. Enumerating them
+ * here means an entry naming a mode the SDK cannot dispatch is dropped with a WARN at load, instead
+ * of reaching `selectTransport` as a string that matches no branch.
+ */
+export declare const catalogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    displayName: z.ZodString;
+    apiMode: z.ZodEnum<{
+        chat_completions: "chat_completions";
+        anthropic_messages: "anthropic_messages";
+        responses_api: "responses_api";
+        bedrock: "bedrock";
+        bedrock_anthropic: "bedrock_anthropic";
+    }>;
+    authType: z.ZodEnum<{
+        none: "none";
+        api_key: "api_key";
+        oauth_device_code: "oauth_device_code";
+        oauth_external: "oauth_external";
+        aws_sdk: "aws_sdk";
+        aws_bearer: "aws_bearer";
+        gcp_oauth: "gcp_oauth";
+    }>;
+    baseUrl: z.ZodString;
+    envVars: z.ZodArray<z.ZodString>;
+    fallbackModels: z.ZodArray<z.ZodString>;
+    capabilities: z.ZodObject<{
+        supportsToolUse: z.ZodBoolean;
+        supportsVision: z.ZodBoolean;
+        supportsStructuredOutput: z.ZodBoolean;
+        supportsStreaming: z.ZodBoolean;
+        supportsCacheControl: z.ZodBoolean;
+        maxContextTokens: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    modelsUrl: z.ZodOptional<z.ZodString>;
+    hostname: z.ZodOptional<z.ZodString>;
+    extraHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        release_date: z.ZodOptional<z.ZodString>;
+        attachment: z.ZodOptional<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodBoolean>;
+        temperature: z.ZodOptional<z.ZodBoolean>;
+        tool_call: z.ZodOptional<z.ZodBoolean>;
+        structured_output: z.ZodOptional<z.ZodBoolean>;
+        cache_control: z.ZodOptional<z.ZodBoolean>;
+        cost: z.ZodOptional<z.ZodObject<{
+            input: z.ZodNumber;
+            output: z.ZodNumber;
+            cache_read: z.ZodOptional<z.ZodNumber>;
+            cache_write: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        limit: z.ZodOptional<z.ZodObject<{
+            context: z.ZodNumber;
+            input: z.ZodOptional<z.ZodNumber>;
+            output: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        modalities: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                text: "text";
+                image: "image";
+                audio: "audio";
+                video: "video";
+                pdf: "pdf";
+            }>>>;
+            output: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                text: "text";
+                image: "image";
+                audio: "audio";
+                video: "video";
+                pdf: "pdf";
+            }>>>;
+        }, z.core.$loose>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            alpha: "alpha";
+            beta: "beta";
+            deprecated: "deprecated";
+        }>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
 export {};

package/dist/internal/providers/catalog-source-models-dev.d.ts

@@ -63,6 +63,17 @@ export declare function loadCacheIntoIndex(url?: string): number;
  * Explicitly refresh the model catalog from models.dev (the ONLY network trigger in the subsystem).
  * Fail-closed: any failure keeps serving the current index (cache or vendored). Kill-switch:
  * `THEOKIT_DISABLE_MODELS_FETCH`.
+ *
+ * The sequence carried a cognitive-complexity suppression whose reason said splitting it would
+ * "separate a step from the fallback it owns". The four helpers above each KEEP their fallback: the
+ * TTL gate owns "no cache", the fetch owns every network and validation failure, the persist owns
+ * the write and the patch. What is left here is the order they run in, which is what this function
+ * was always for.
+ *
+ * Still true, and NOT fixed by the split: three of the paths return `{ source: "cache" }`, so a
+ * caller cannot tell a timeout from an unparseable body from a patch failure. Distinguishing them
+ * means adding a field to the PUBLIC `RefreshModelCatalogResult`, which is a release decision rather
+ * than a refactor. The `diag` line already names the cause for an operator.
  */
 export declare function refreshModelCatalog(opts?: RefreshModelCatalogOptions): Promise<RefreshModelCatalogResult>;
 /** The enriched per-model view (public via `@theokit/sdk/models`): index lookup by (possibly prefixed) id. */

package/dist/internal/runtime/compat/compat-config-file.d.ts

@@ -0,0 +1,31 @@
+import type { CompatSourceDeclaration } from "./foreign-config-sources.js";
+/**
+ * Read `.theokit/config.json`'s `compat.adapters`, or `[]` when the file is absent, declares no
+ * `compat` section, or is malformed — the last two WARN on the diagnostics channel rather than
+ * failing silently, matching #526's fail-closed-and-say-so precedent for the code option.
+ *
+ * SYNC on purpose: the caller is `Agent`'s constructor, which resolves `compatSources` before any
+ * submanager exists to await a promise. `existsSync` is already how the same constructor checks for
+ * `.theokit`/`.claude`; a once-per-agent read of one small, optional JSON file is the same class of
+ * work, not a new one.
+ */
+export declare function readCompatConfigFile(cwd: string): CompatSourceDeclaration[];
+/**
+ * The one place `local.compatSources` — explicit code — and `.theokit/config.json` — the
+ * project's declared default — are reconciled. Every reader that needs `compatSources` (hooks,
+ * skills, plugins, subagents) calls THIS instead of writing `options.local?.compatSources ?? []`
+ * by hand: that pattern existed at five call sites before this function did, and every one of them
+ * silently meant "the file form doesn't exist" — the same duplication `theokitConfigRoot` closed
+ * one layer down, one layer up.
+ *
+ * PRECEDENCE: explicit code wins. A consumer passing `local.compatSources` made a decision at the
+ * call site; the file is the DEFAULT for callers who did not. This is not specified by #524 — it is
+ * this SDK's choice, made explicit here rather than left to whichever call site happened to be
+ * written first. It means a test or a one-off script can always override the file without editing
+ * or deleting it, which the reverse precedence would not allow.
+ */
+export declare function resolveCompatSources(options: {
+    local?: {
+        compatSources?: readonly CompatSourceDeclaration[];
+    };
+}, cwd: string): readonly CompatSourceDeclaration[];

package/dist/internal/runtime/compat/foreign-config-sources.d.ts

@@ -1,37 +1,3 @@
-/**
- * The foreign configuration dialects this SDK can read, and what each one PRESUMES.
- *
- * ## Why a registry and not a list of directory names
- *
- * `projectConfigRoots` returned `[".theokit", ".claude"]` — two paths — and that shape is what
- * usetheokit/theokit-sdk#522 fell through. A path says WHERE a file lives. It does not say how the
- * file is parsed, and it does not say what runtime the commands inside it were written against.
- *
- * Claude Code defines `$CLAUDE_PROJECT_DIR` for the hook commands in its `settings.json`, and its
- * documentation tells authors to reach project files through it — an absolute path would break for
- * every other person on the team, so the shape that failed here is the shape upstream recommends.
- * This SDK read the file and ran the command without the variable. `sh` expands an unset variable to
- * the empty string, so
- *
- *     bash "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh"   became   bash "/.claude/hooks/guard.sh"
- *
- * which does not exist, which a hook runner correctly reads as a refusal. Every turn denied, in any
- * repository that also had Claude Code set up, with a message naming a file that was present and
- * executable all along.
- *
- * Importing a format means accepting the contract that format presumes. An adapter is where that
- * contract is written down, so the next dialect (`.codex/` is the obvious one) declares its own
- * instead of inheriting a hole.
- *
- * ## What an adapter deliberately does NOT do
- *
- * It does not make the foreign source trusted, and it does not make its hooks permissive: a script
- * that exits non-zero is still a refusal. It supplies the variables the format's authors were
- * entitled to assume, and nothing else — `env` here is merged over the scrubbed inherit policy by
- * `spawnAndCollect`, so it adds names rather than widening what a child can see.
- *
- * @internal
- */
 /** The Claude Code CLI's project configuration directory. */
 export declare const CLAUDE_DIR_NAME = ".claude";
 /** A configuration dialect this SDK understands. `theokit` is native; the rest are foreign. */
@@ -60,6 +26,44 @@ export declare const NATIVE_SOURCE: ConfigSourceAdapter;
  * wrong, where an unset one fails loudly.
  */
 export declare const CLAUDE_CODE_SOURCE: ConfigSourceAdapter;
+/**
+ * The adapters a caller declared, in declaration order, skipping any name that names no adapter.
+ *
+ * An unknown name is DROPPED rather than turned into `<cwd>/<name>`: a typo must fail closed. Making
+ * a directory out of an unrecognised string would import a dialect nothing knows how to parse — and
+ * the whole reason this exists is that a directory name was never enough to describe a dialect.
+ */
+export declare function adaptersFor(kinds: readonly string[]): ConfigSourceAdapter[];
+/**
+ * A surface a foreign source may be admitted to. The four the SDK reads a project directory for.
+ *
+ * They are listed separately because they carry very different risk, which is the whole reason
+ * #524 asks for per-surface control: a skill is text that enters the system prompt, a hook is
+ * command execution, a plugin is code loading. A consumer who wants their skills back has no
+ * reason to be handed the other two along with them.
+ */
+export type CompatSurface = "hooks" | "plugins" | "skills" | "subagents";
+/**
+ * A declared foreign source: a bare kind, or a kind with the surfaces it may be read for.
+ */
+export type CompatSourceDeclaration = string | {
+    readonly kind: string;
+    readonly import?: readonly string[];
+};
+/**
+ * The adapters admitted to ONE surface.
+ *
+ * Three rules, and each one fails closed:
+ *
+ * - A bare string admits every surface. It is what `5.0.0-next.1` published, so narrowing it
+ *   silently would turn a working opt-in into a no-op — the exact defect #524 is about, one level
+ *   up.
+ * - An object with no `import` admits nothing. The issue's own rule, and safe to apply strictly
+ *   because the object form is new and nobody can be depending on it.
+ * - An unrecognised surface name is dropped rather than matched loosely, for the same reason an
+ *   unrecognised KIND is dropped in {@link adaptersFor}: a typo must not silently widen access.
+ */
+export declare function adaptersForSurface(sources: readonly CompatSourceDeclaration[], surface: CompatSurface): ConfigSourceAdapter[];
 /**
  * The adapter whose directory an absolute config path sits under, or `undefined` for a path that
  * belongs to no registered dialect.
@@ -90,3 +94,23 @@ export declare function adapterForConfigPath(path: string): ConfigSourceAdapter
  * toward silence and the check only ever ADDS a name to a failure that already happened.
  */
 export declare function undefinedVariablesIn(command: string, supplied: Readonly<Record<string, string>>, env?: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * Reports a foreign configuration directory that exists in the workspace and was not declared.
+ *
+ * ## Why the flip needs a voice
+ *
+ * Before #524 a `.claude/` was read with no opt-in; after it, the same directory is ignored. From
+ * inside the repository the two states are indistinguishable — the hook file is there, it is
+ * executable, and it does not run. The only remaining way to learn why is a CHANGELOG entry for a
+ * version the reader may not know they crossed.
+ *
+ * ## Why `diag` rather than `diagFailure`
+ *
+ * `diagFailure` falls back to stderr, and this is not a failure: ignoring an undeclared foreign
+ * directory is precisely what #524 asked for. Every repository that has Claude Code set up and does
+ * NOT want it imported would pay a stderr line at every agent start — on a TUI host's render
+ * surface — for behaving as instructed. That is the corruption `diagnostics.ts` exists to prevent.
+ *
+ * So it goes on the interceptable channel, for the reader holding the question it answers.
+ */
+export declare function reportUndeclaredSources(cwd: string, declared: readonly CompatSourceDeclaration[]): void;

package/dist/internal/runtime/compression/compression-model-registry.d.ts

@@ -34,7 +34,7 @@
  *
  * @public
  */
-export declare class CompressionModelUnresolvedError extends Error {
+export declare class CompressionModelUnresolvedError extends TheokitAgentError {
     readonly name = "CompressionModelUnresolvedError";
     readonly agentModel: string;
     constructor(agentModel: string);

package/dist/internal/runtime/compression/compression-summarizer.d.ts

@@ -17,6 +17,7 @@
  *
  * @internal
  */
+import { TheokitAgentError } from "../../../errors.js";
 export type { CompressibleMessage };
 /**
  * Typed error thrown when the compression LLM call fails or returns
@@ -25,6 +26,9 @@ export type { CompressibleMessage };
  *
  * @public
  */
-export declare class CompressionFailedError extends Error {
+export declare class CompressionFailedError extends TheokitAgentError {
     readonly name = "CompressionFailedError";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }

package/dist/internal/runtime/fixtures/fixture-events.d.ts

@@ -1,5 +1,5 @@
 import type { SDKAssistantMessage, SDKRequestMessage, SDKStatusMessage, SDKSystemMessage, SDKTaskMessage, SDKThinkingMessage, SDKToolUseMessage, SDKUserMessageEvent } from "../../../types/messages.js";
-import type { FixtureRequest } from "./fixture-types.js";
+import type { FixtureRequest } from "./types.js";
 export declare function systemEvent(request: FixtureRequest, tools: string[]): SDKSystemMessage;
 export declare function userEvent(request: FixtureRequest): SDKUserMessageEvent;
 export declare function assistantText(request: FixtureRequest, text: string): SDKAssistantMessage;

package/dist/internal/runtime/fixtures/fixture-mode.d.ts

@@ -11,20 +11,14 @@
  * or a real Theo PaaS instance), the SDK always performs real HTTP
  * requests — fixture mode is short-circuited.
  *
- * @internal
- */
-/**
- * The provider credentials `shouldUseRealLocalRuntime` consults by name.
  *
- * Exported so the "Missing API key" refusal can name the ones the caller actually set (#338 item
- * 5). The list used to live only inside the predicate below, which meant a caller with
- * `OPENROUTER_API_KEY` set and `THEOKIT_API_KEY` unset was refused by a message naming neither —
- * the SDK checks this exact variable a few lines down to decide the runtime, so the environment
- * looks configured to the person who set it up. Reported as a three-hour diagnosis.
+ * WHAT THIS FILE NO LONGER ANSWERS. It used to answer three unrelated questions in 229 lines: this
+ * one, "what base URL is configured" (now `internal/base-url.ts`, whose real consumer is the
+ * production HTTP module) and "does this process hold a real provider credential" (now
+ * `internal/auth/credential-availability.ts`, where its dependency already pointed).
+ * `shouldUseRealLocalRuntime` stays here because it COMPOSES the three — it is the decision, not the
+ * policy.
  *
- * One list, two readers: a variable added here is recognised by the predicate AND named by the
- * error on the same commit, which is the only way the two stay in step.
+ * @internal
  */
-export declare const PROVIDER_CREDENTIAL_ENV_VARS: readonly string[];
-/** Those of {@link PROVIDER_CREDENTIAL_ENV_VARS} that are non-empty in this process. */
-export declare function presentProviderCredentialEnvVars(): readonly string[];
+export {};

package/dist/internal/runtime/fixtures/fixture-run-base.d.ts

@@ -2,7 +2,7 @@ import type { ModelSelection } from "../../../types/agent.js";
 import type { ConversationTurn } from "../../../types/conversation.js";
 import type { SDKMessage } from "../../../types/messages.js";
 import type { Run, RunOperation, RunResult, RunStatus, RunTimelineEvent } from "../../../types/run.js";
-import type { FixtureScript } from "./fixture-types.js";
+import type { FixtureScript } from "./types.js";
 export declare abstract class FixtureRunBase implements Run {
     readonly id: string;
     readonly agentId: string;

package/dist/internal/runtime/fixtures/fixture-scripts.d.ts

@@ -1,5 +1,5 @@
-import type { FixtureRequest, FixtureScript } from "./fixture-types.js";
-export { extractMemoryFact, isMemoryWritePrompt } from "../memory/memory-store.js";
+import type { FixtureRequest, FixtureScript } from "./types.js";
+export { extractMemoryFact, isMemoryWritePrompt } from "../memory-glue/memory-store.js";
 export declare function isMemoryRecallPrompt(message: string, request: FixtureRequest): boolean;
 export declare function memoryWriteScript(request: FixtureRequest): FixtureScript;
 export declare function memoryRecallScript(request: FixtureRequest): FixtureScript;

package/dist/internal/runtime/hooks/hooks-executor.d.ts

@@ -1,3 +1,4 @@
+import type { CompatSourceDeclaration } from "../compat/foreign-config-sources.js";
 export interface HookCommand {
     command: string;
     /** Optional matcher restricting the hook to specific tools (regex). */
@@ -34,8 +35,12 @@ export interface HookExecutionResult {
 }
 export declare class HooksExecutor {
     private readonly cwd;
+    /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */
+    private readonly compatSources;
     private config;
-    constructor(cwd: string);
+    constructor(cwd: string, 
+    /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */
+    compatSources?: readonly CompatSourceDeclaration[]);
     initialize(settingSourcesIncludeProject: boolean): Promise<void>;
     /** Fire every hook registered for `event` and aggregate the decisions. */
     run(payload: HookPayload): Promise<HookExecutionResult>;

package/dist/internal/runtime/lifecycle/wrap-completion-check-run.d.ts

@@ -17,7 +17,7 @@
  * @internal
  */
 import type { CompletionCheck, Run } from "../../../types/run.js";
-import { type RunEventSink } from "../../../types/run-events.js";
+import type { RunEventSink } from "../../../types/run-events.js";
 import type { JudgeContext, JudgeOptions } from "../../judge/judge-call.js";
 export interface CompletionCheckDeps {
     judge: (ctx: JudgeContext, opts?: JudgeOptions) => Promise<JudgeResult>;

package/dist/internal/runtime/{memory → memory-glue}/memory-provider.d.ts

@@ -8,4 +8,4 @@
  *
  * @public — surface-level interface; impls are internal-but-replaceable.
  */
-export type { ActiveMemoryPassArgs, ActiveMemoryPassResult, MemoryProvider, MemoryProviderHandle, MemoryProviderInitOptions, RecordSessionSummaryArgs, } from "../../../types/memory-provider.js";
+export type { ActiveMemoryPassArgs, ActiveMemoryPassResult, MemoryProvider, MemoryProviderAgentRef, MemoryProviderHandle, MemoryProviderInitOptions, RecordSessionSummaryArgs, } from "../../../types/memory-provider.js";