@theokit/sdk 4.63.3 → 5.0.0-next.1

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

@@ -1,6 +1,8 @@
+import { TheokitAgentError } from "../../errors.js";
 /** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */
-export declare class JsonlParseError extends Error {
+export declare class JsonlParseError extends TheokitAgentError {
     readonly line: number;
+    readonly name = "JsonlParseError";
     constructor(message: string, line: number);
 }
 /**

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

@@ -1,6 +1,8 @@
+import { TheokitAgentError } from "../../errors.js";
 /** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */
-export declare class JsonlParseError extends Error {
+export declare class JsonlParseError extends TheokitAgentError {
     readonly line: number;
+    readonly name = "JsonlParseError";
     constructor(message: string, line: number);
 }
 /**

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

@@ -75,7 +75,7 @@ export declare function getTheokitHome(cwd: string): string;
  * 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 string[]): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +89,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 string[]): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

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

@@ -75,7 +75,7 @@ export declare function getTheokitHome(cwd: string): string;
  * 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 string[]): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +89,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 string[]): 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/foreign-config-sources.d.ts

@@ -0,0 +1,86 @@
+/** 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. */
+export interface ConfigSourceAdapter {
+    /** Stable identifier, and what a consumer names to opt in. */
+    readonly kind: string;
+    /** The project-relative directory the dialect keeps its configuration in. */
+    readonly dirName: string;
+    /**
+     * Variables the dialect's own runtime defines for commands it executes.
+     *
+     * Empty for the native source: a `.theokit/` hook is written against THIS runtime and inherits it
+     * already. Non-empty is what makes a foreign command runnable rather than silently broken.
+     */
+    runtimeEnv(cwd: string): Record<string, string>;
+}
+/** The native source. Always read, never opted into, always first for precedence. */
+export declare const NATIVE_SOURCE: ConfigSourceAdapter;
+/**
+ * Claude Code.
+ *
+ * `CLAUDE_PROJECT_DIR` is the documented way for a hook command in `settings.json` to reach a file
+ * in the project. Only that one variable is supplied: `$CLAUDE_PLUGIN_ROOT` and the rest of that
+ * runtime's surface are NOT defined here, because supplying a name whose value this SDK would have
+ * to invent is worse than leaving it unset — an invented root sends a script somewhere real and
+ * 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[];
+/**
+ * The adapter whose directory an absolute config path sits under, or `undefined` for a path that
+ * belongs to no registered dialect.
+ *
+ * Matched on the path SEGMENT rather than with `includes`, so a workspace that happens to live under
+ * `/home/me/.claude-backups/repo` does not read as a Claude Code source.
+ */
+export declare function adapterForConfigPath(path: string): ConfigSourceAdapter | undefined;
+/**
+ * Variable references in a shell command that nothing will define.
+ *
+ * The second half of #522, and the half that cost the debugging session. `sh` expands an unset
+ * variable to the empty string and says nothing, so the failure surfaces ten characters later as a
+ * path: `bash: /.claude/hooks/guard.sh: No such file or directory` — which reads as "your script is
+ * missing" while the script is present and executable. Nothing in that message contains the name of
+ * the variable that was actually missing, so the reader looks in the wrong place.
+ *
+ * Checked against BOTH the process environment and the variables the dialect supplies, because
+ * either is a legitimate source: a hook may reasonably use `$HOME`.
+ *
+ * ## What it deliberately does not try to be
+ *
+ * This is not a shell parser. It finds `$NAME` and `${NAME}` outside single quotes, which is the
+ * shape a config file's hook commands take. It does NOT understand `${NAME:-default}` (a default
+ * makes the variable optional, so it is not reported), assignments earlier in the same command, or
+ * variables a sourced script exports. A false NEGATIVE there costs the old behaviour — the confusing
+ * path error — and a false positive would deny a hook that would have worked, so the parse errs
+ * 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 string[]): 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

@@ -4,6 +4,15 @@ export interface HookCommand {
     matcher?: string;
     /** Optional timeout in ms; defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookDecision {
     decision: "allow" | "deny" | "feedback";
@@ -25,8 +34,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 string[]);
     initialize(settingSourcesIncludeProject: boolean): Promise<void>;
     /** Fire every hook registered for `event` and aggregate the decisions. */
     run(payload: HookPayload): Promise<HookExecutionResult>;

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

@@ -20,6 +20,15 @@ export interface HookCommand {
     command: string;
     matcher?: string;
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookConfig {
     hooks?: Partial<Record<HookEvent, HookCommand[]>>;

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";

package/dist/internal/runtime/{plugins → plugin-loader}/plugin-bundles.d.ts

@@ -16,4 +16,6 @@
  * A missing root is not an error: most projects carry no plugins, and treating their absence as a
  * failure would make "none installed" indistinguishable from "the directory could not be read".
  */
-export declare function pluginBundleDirs(cwd: string): Promise<string[]>;
+export declare function pluginBundleDirs(cwd: string, 
+/** Declared foreign dialects (#524). Empty reads `.theokit/plugins` only. */
+compatSources?: readonly string[]): Promise<string[]>;

package/dist/internal/runtime/processors/wrap-output-run.d.ts

@@ -9,7 +9,7 @@
  * @internal
  */
 import type { Run } from "../../../types/run.js";
-import { type RunEventSink } from "../../../types/run-events.js";
+import type { RunEventSink } from "../../../types/run-events.js";
 export declare function wrapRunWithOutputProcessors(args: {
     run: Run;
     processors: readonly Processor[];

package/dist/internal/runtime/registry/live-agent-registry.d.ts

@@ -120,5 +120,13 @@ export declare class LiveAgentRegistry {
     /** Ids of cached agents, newest first (by lastUsedAt). */
     ids(): readonly string[];
 }
-/** Process-wide singleton (ADR D310). */
+/**
+ * Process-wide singleton (ADR D310).
+ *
+ * Through `globalSingleton`, not a bare module-level `const`. A module-level const is a singleton per
+ * MODULE INSTANCE, and a package can be loaded more than once in a process — two copies in
+ * `node_modules`, ESM and CJS side by side, a monorepo with distinct versions. This is the PUBLIC one
+ * of the package's module-level singleton states, so two copies of it mean two views of which agents
+ * are live, and a caller reading the wrong one sees none.
+ */
 export declare const liveAgentRegistry: LiveAgentRegistry;

package/dist/internal/runtime/system-prompt/local-assembly.d.ts

@@ -1 +1,2 @@
-export {};
+import type { SystemPromptAssemblyContext } from "./types.js";
+export declare function buildAssemblyContext({ inputs, userText, baseSystemPrompt, memoryFacts, activeMemorySummary, contextPaths, }: AssemblyRequest): Promise<SystemPromptAssemblyContext>;

package/dist/internal/scorers/llm-judge.d.ts

@@ -23,6 +23,18 @@ export interface LlmJudgeOptions {
     readonly rubric?: "continuous" | "discrete";
     readonly providers?: ProviderRoutingSettings;
 }
+/**
+ * The parser, exposed for tests. NOT re-exported from any barrel — `_...ForTests` is this repo's
+ * convention for a seam that exists so a test can call production code instead of copying it
+ * (`_redactAttrValueForTests`, `__resetSnapshotStoresForTests`).
+ *
+ * It exists because the alternative was measured and was worse: the judge's only test file declared
+ * its own copy of `SCORE_REGEX` under the comment "Mirror the one in llm-judge.ts", and six of its
+ * eight cases exercised the copy. Byte-identical today, which is exactly why the drift would have
+ * been invisible — changing the production regex broke nothing there. Testing a mirror tests the
+ * mirror.
+ */
+export declare function _parseScoreForTests(text: string, rubric: "continuous" | "discrete"): Score;
 export declare function llmJudgeScore(options: LlmJudgeOptions & {
     output: string;
     expected?: unknown;