@theokit/sdk 5.0.0-next.1 → 5.0.0-next.2

package/dist/index.d.ts

@@ -2,15 +2,15 @@ import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01n
 export { a as ErrorCode } from './errors-base-B5g01neU.js';
 import { F as RunEvent, j as CostBreakdown, at as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as RunEventSink$1, S as SDKMessage } from './run-CTAdRU3U.js';
 export { A as AgentConversationTurn, e as AssistantMessage, f as CompletionCheck, g as CompletionCheckResult, h as ConversationStep, i as ConversationTurn, j as CostBreakdown, k as CostSource, l as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, m as GenerateRunResult, I as ImageBlock, n as InputProcessorContext, o as InteractionUpdate, p as McpAuthConfig, q as McpHttpServerConfig, r as McpOAuthConfig, s as McpStdioServerConfig, t as MessageOrigin, u as ModelParameterValue, O as OutputProcessorContext, v as PartialToolCallUpdate, w as ProcessorControls, x as ProcessorTripwire, y as ProcessorViolation, z as RunCompactBoundaryEvent, B as RunCompletionCheckEvent, E as RunErrorDetail, F as RunEvent, H as RunGitInfo, J as RunMemoryDegradedEvent, K as RunOperation, L as RunPermissionDeniedEvent, N as RunRateLimitEvent, Q as RunStatus, U as RunTaskCompletedEvent, V as RunTaskStartedEvent, W as RunTaskUpdatedEvent, X as RunTimelineEvent, Y as RunToCompletionOptions, Z as RunToCompletionResult, _ as RunToolProgressEvent, $ as RunTripwireEvent, a0 as SDKAssistantMessage, a1 as SDKImage, a2 as SDKImageDimension, a3 as SDKObjectDelta, a4 as SDKRequestMessage, a5 as SDKStatusMessage, a6 as SDKSystemMessage, a7 as SDKTaskMessage, a8 as SDKThinkingMessage, a9 as SDKToolUseMessage, aa as SDKUserMessage, ab as SDKUserMessageEvent, ac as SendOptions, ad as ShellCommand, ae as ShellConversationTurn, af as ShellOutput, ag as ShellOutputDeltaUpdate, ah as StepCompletedUpdate, ai as StepStartedUpdate, aj as StreamToCompletionResult, ak as SummaryCompletedUpdate, al as SummaryStartedUpdate, am as SummaryUpdate, an as TextBlock, ao as TextDeltaUpdate, ap as ThinkingCompletedUpdate, aq as ThinkingDeltaUpdate, ar as ThinkingMessage, as as TokenDeltaUpdate, at as TokenUsage, au as ToolCall, av as ToolCallCompletedUpdate, aw as ToolCallStartedUpdate, ax as ToolContextMessage, ay as ToolResult, az as ToolResultGuardOptions, aA as ToolUseBlock, aB as TurnEndedUpdate, aC as UserMessage, aD as UserMessageAppendedUpdate } from './run-CTAdRU3U.js';
-import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-CdYJfKr6.js';
-export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CreateSkillSpec, H as HookName, y as MemoryProviderAgentRef, z as MemoryProviderFactory, D as MemoryProviderHandle, E as MemoryProviderInitOptions, F as PluginContext, J as PluginHookDisposer, K as PostAssistantReplyContext, N as PostToolCallContext, O as PreToolCallContext, Q as PreUserSendContext, R as PreUserSendResult, T as ProviderTransform, U as ProviderTransformContext, V as RecordSessionSummaryArgs, W as SessionLifecycleContext, X as SessionRecord, Y as SessionStore, Z as SettingSource, _ as Skill, $ as SkillsResolver, a0 as SkillsResolverContext, a1 as SystemPromptContext, a2 as SystemPromptMemoryFact, a3 as TelemetrySettings, a4 as ToolCallSummary, a5 as ToolResultTransformContext, a6 as TransformContext } from './agent-CdYJfKr6.js';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-CvmTR9uf.js';
+export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-CvmTR9uf.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-CLOAyuiv.js';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, T as TaskNotFoundError, U as UnknownAgentError, o as UnsupportedBudgetOperationError, p as UnsupportedRunOperationError, q as UnsupportedTaskOperationError, r as isTransientError } from './errors-CLOAyuiv.js';
-import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-ldzpyAaF.js';
-export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-ldzpyAaF.js';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-DJv9oXSZ.js';
+import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-D4a_BR_6.js';
+export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-D4a_BR_6.js';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-crfMMdAw.js';
 import { StepResult } from './workflow.js';
 export { Workflow, agentStep, fn } from './workflow.js';
 

package/dist/index.js

@@ -8,15 +8,15 @@ import { Workflow, agentStep } from './chunk-HFEJE7AC.js';
 export { Workflow, agentStep, fn } from './chunk-HFEJE7AC.js';
 import './chunk-GBCVPKHE.js';
 import './chunk-HY66GLM6.js';
-export { Cron } from './chunk-6HIACV34.js';
-import { MEMORY_EMBEDDING_ADAPTERS, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-NCGWJ3HS.js';
-export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-NCGWJ3HS.js';
+export { Cron } from './chunk-ZH26RNQA.js';
+import { MEMORY_EMBEDDING_ADAPTERS, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-KDR53EO7.js';
+export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-KDR53EO7.js';
 import { configure, submit, list, get, cancel, subscribe } from './chunk-K2VMFZQ5.js';
 export { emitRunEvent } from './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
 import './chunk-2ZLVT7H3.js';
-import './chunk-IJM7UGS5.js';
+import './chunk-XJZEBGXD.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.js';
@@ -55,8 +55,8 @@ import { withCwdMutex } from './chunk-Q5EWJPRY.js';
 export { withCwdMutex } from './chunk-Q5EWJPRY.js';
 export { TASK_RESERVED_PREFIXES, isValidTaskId } from './chunk-EIQFAOFD.js';
 import { replaceFileAtomic } from './chunk-3JHIFQ4I.js';
-import './chunk-XCCGNU3D.js';
-import './chunk-JTZ74HFD.js';
+import './chunk-4S5TWFIZ.js';
+import './chunk-67ADYSTW.js';
 import './chunk-JNAA4G4H.js';
 import { estimateTokens, CHARS_PER_TOKEN } from './chunk-6M2OIS4Y.js';
 export { estimateTokens } from './chunk-6M2OIS4Y.js';
@@ -1743,7 +1743,7 @@ function isBuiltAgent(m) {
   return typeof m.send === "function";
 }
 async function materialize(def, index) {
-  const { Agent: Agent2 } = await import('./agent-XMKRP27S.js');
+  const { Agent: Agent2 } = await import('./agent-Y24I5JBM.js');
   return Agent2.create({
     // `AgentDefinition.model` admits the sentinel `'inherit'`, which is not a model id. Inheriting
     // here means "declare nothing and let the default apply" — forwarding the literal would create

package/dist/internal/persistence/index.cjs

@@ -7,7 +7,7 @@ var chunkDQZU7JK6_cjs = require('../../chunk-DQZU7JK6.cjs');
 var chunkBJUJT5ED_cjs = require('../../chunk-BJUJT5ED.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkJLRLCBJ4_cjs = require('../../chunk-JLRLCBJ4.cjs');
-var chunkCEILSTWB_cjs = require('../../chunk-CEILSTWB.cjs');
+var chunkGGZ5GPE3_cjs = require('../../chunk-GGZ5GPE3.cjs');
 require('../../chunk-J7J7J2GN.cjs');
 require('../../chunk-6LHQPOMI.cjs');
 var promises = require('fs/promises');
@@ -111,15 +111,15 @@ Object.defineProperty(exports, "replaceFileAtomic", {
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.displayTheokitHome; }
+  get: function () { return chunkGGZ5GPE3_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.getProfilesRoot; }
+  get: function () { return chunkGGZ5GPE3_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.getTheokitHome; }
+  get: function () { return chunkGGZ5GPE3_cjs.getTheokitHome; }
 });
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;

package/dist/internal/persistence/index.js

@@ -5,7 +5,7 @@ export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from '..
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-TA3K7SBK.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-3JHIFQ4I.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-JTZ74HFD.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-67ADYSTW.js';
 import '../../chunk-ALUN2B4W.js';
 import '../../chunk-CZJ6Q7CW.js';
 import { open } from 'fs/promises';

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, sources?: readonly 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, sources?: readonly strin
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string, sources?: readonly 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, sources?: readonly 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, sources?: readonly strin
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string, sources?: readonly 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/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

@@ -34,6 +34,36 @@ export declare const CLAUDE_CODE_SOURCE: ConfigSourceAdapter;
  * 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.
@@ -83,4 +113,4 @@ export declare function undefinedVariablesIn(command: string, supplied: Readonly
  *
  * 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;
+export declare function reportUndeclaredSources(cwd: string, declared: readonly CompatSourceDeclaration[]): void;

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). */
@@ -39,7 +40,7 @@ export declare class HooksExecutor {
     private config;
     constructor(cwd: string, 
     /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */
-    compatSources?: readonly string[]);
+    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/plugin-loader/plugin-bundles.d.ts

@@ -6,6 +6,7 @@
  *
  * @internal
  */
+import type { CompatSourceDeclaration } from "../compat/foreign-config-sources.js";
 /**
  * Every plugin folder under the project's plugin roots.
  *
@@ -18,4 +19,4 @@
  */
 export declare function pluginBundleDirs(cwd: string, 
 /** Declared foreign dialects (#524). Empty reads `.theokit/plugins` only. */
-compatSources?: readonly string[]): Promise<string[]>;
+compatSources?: readonly CompatSourceDeclaration[]): Promise<string[]>;

package/dist/{sdk-agent-Dxjb0IfM.d.cts → sdk-agent-BOiKqOgL.d.cts}

@@ -613,10 +613,27 @@ interface GoalOptions {
 interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -660,6 +677,16 @@ interface SDKAgentSkills {
 interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when

package/dist/{sdk-agent-ldzpyAaF.d.ts → sdk-agent-D4a_BR_6.d.ts}

@@ -613,10 +613,27 @@ interface GoalOptions {
 interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -660,6 +677,16 @@ interface SDKAgentSkills {
 interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when

package/dist/subagents-loader-TPZLTXYZ.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkSYVWE64W_cjs = require('./chunk-SYVWE64W.cjs');
+require('./chunk-GGZ5GPE3.cjs');
+require('./chunk-HW7SEELD.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkSYVWE64W_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-TPZLTXYZ.cjs.map
+//# sourceMappingURL=subagents-loader-TPZLTXYZ.cjs.map

package/dist/{subagents-loader-YWFE7KYE.cjs.map → subagents-loader-TPZLTXYZ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-YWFE7KYE.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-TPZLTXYZ.cjs"}

package/dist/subagents-loader-Y6JFYXAY.js

@@ -0,0 +1,7 @@
+export { loadSubagents } from './chunk-4S5TWFIZ.js';
+import './chunk-67ADYSTW.js';
+import './chunk-JNAA4G4H.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=subagents-loader-Y6JFYXAY.js.map
+//# sourceMappingURL=subagents-loader-Y6JFYXAY.js.map

package/dist/{subagents-loader-LSKM2UIK.js.map → subagents-loader-Y6JFYXAY.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-LSKM2UIK.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-Y6JFYXAY.js"}

package/dist/subagents-loader.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkG4ZGYKJG_cjs = require('./chunk-G4ZGYKJG.cjs');
-require('./chunk-CEILSTWB.cjs');
+var chunkSYVWE64W_cjs = require('./chunk-SYVWE64W.cjs');
+require('./chunk-GGZ5GPE3.cjs');
 require('./chunk-HW7SEELD.cjs');
 var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
 require('./chunk-6LHQPOMI.cjs');
@@ -23,7 +23,7 @@ function resolveSources(options) {
 }
 async function discoverSubagents(cwd, options) {
   const sources = resolveSources(options);
-  return chunkG4ZGYKJG_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
+  return chunkSYVWE64W_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.d.cts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-CgNzshyV.cjs';
-import './sdk-agent-Dxjb0IfM.cjs';
+import { a as AgentDefinition } from './agent-C3KO5LKm.cjs';
+import './sdk-agent-BOiKqOgL.cjs';
 import './run-CTAdRU3U.cjs';
 import 'zod';
 

package/dist/subagents-loader.d.ts

@@ -1,5 +1,5 @@
-import { a as AgentDefinition } from './agent-CdYJfKr6.js';
-import './sdk-agent-ldzpyAaF.js';
+import { a as AgentDefinition } from './agent-CvmTR9uf.js';
+import './sdk-agent-D4a_BR_6.js';
 import './run-CTAdRU3U.js';
 import 'zod';
 

package/dist/subagents-loader.js

@@ -1,5 +1,5 @@
-import { loadSubagents } from './chunk-XCCGNU3D.js';
-import './chunk-JTZ74HFD.js';
+import { loadSubagents } from './chunk-4S5TWFIZ.js';
+import './chunk-67ADYSTW.js';
 import './chunk-JNAA4G4H.js';
 import { ConfigurationError } from './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';

package/dist/types/agent.d.ts

@@ -30,7 +30,39 @@ export type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "a
  *
  * @public
  */
-export type CompatSource = "claude-code";
+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.
@@ -176,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>>;
     /**