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

package/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog
 
+## 5.0.0-next.3
+
+### Minor Changes
+
+- ae2a720: `THEO.md` now works at the project root, the way `AGENTS.md`, `GEMINI.md` and `CLAUDE.md` already
+  do — found from the root, and reachable by walking up from any subdirectory.
+  
+  Before this, `THEO.md` was the only context file this SDK knows about that had to live inside
+  `.theokit/` and could not be found from a subdirectory. The miss was silent: a well-formed
+  `THEO.md` at the project root was simply never read, with no warning that it had been ignored.
+  
+  ```
+  project/
+  ├── THEO.md              ← now read, walking up from any subdirectory
+  └── .theokit/
+      └── THEO.md           ← still works exactly as before
+  ```
+  
+  A new `DEFAULT_DISCOVERY_SPECS` entry (`THEO.md.root`, priority 55) is added alongside the
+  existing one — nothing about `.theokit/THEO.md` changes, so a project already using it keeps
+  working unchanged. When both exist, `.theokit/THEO.md` is the later, winning source on conflict —
+  the precedence usetheokit/theokit-sdk#531 asked for.
+  
+  The new entry sets `followImports: true`, unlike `.theokit/THEO.md` (`false`) and unlike
+  `AGENTS.md`. This is deliberate, not an inconsistency: a root-level `THEO.md` is edited by the same
+  people, in the same place, as `CLAUDE.md`/`GEMINI.md` — the two other root-level files, both
+  `followImports: true` — so it belongs in their category rather than `AGENTS.md`'s vendor-neutral,
+  import-free one. Flagged as an open decision in the issue; resolved here because adding a new spec
+  rather than reusing the existing one meant it could be decided on its own merits, with zero
+  behaviour change for existing `.theokit/THEO.md` files either way.
+  
+  Closes usetheokit/theokit-sdk#531.
+
+## 5.0.0-next.2
+
+### Minor Changes
+
+- 88e87d0: A foreign configuration source can now be admitted to some surfaces and not others.
+  
+  `compatSources: ["claude-code"]` was all-or-nothing: declaring it admitted `.claude/` to hooks,
+  plugins, skills AND subagents at once. The four carry very different risk — a skill is text that
+  enters the system prompt, a plugin is code loading, a hook is command execution — so a consumer who
+  wanted to reuse the skills they had already written was handed arbitrary command execution along
+  with them, and had no way to say otherwise.
+  
+  ```ts
+  local: {
+    compatSources: [{ kind: "claude-code", import: ["skills", "subagents"] }],
+  }
+  ```
+  
+  Hooks and plugins then resolve `.theokit/` alone. `CompatSurface` and `CompatSourceAdapter` are
+  exported.
+  
+  Three rules, each failing closed:
+  
+  - **The bare `"claude-code"` string still admits every surface.** It is what `5.0.0-next.1`
+    published, and narrowing it silently would turn a working opt-in into a no-op that says nothing —
+    the defect this option exists to fix, one level up.
+  - **An adapter with no `import` list admits nothing.** Safe to apply strictly because the object
+    form is new and nobody can be relying on it yet.
+  - **An unrecognised surface name is dropped**, exactly as an unrecognised `kind` already is. A typo
+    must narrow access, never widen it.
+  
+  The `plugins` surface governs reading a foreign plugin directory even when the caller wants the
+  SKILLS a bundle carries: a bundle is code, and its skills arrive attached to it, so admitting
+  `skills` alone must not reach inside one. Otherwise the narrower permission would silently grant
+  the wider one.
+  
+  Closes the per-surface half of usetheokit/theokit-sdk#524. The visibility half — skills, subagents
+  and plugins carrying the root they came from, the way hooks already carry `sourcePath` — and the
+  declarative `.theokit/config.toml` form are not in this change.
+- 33aa170: A project can now declare its foreign compat sources in `.theokit/config.json`, instead of only in
+  code.
+  
+  ```json
+  {
+    "compat": {
+      "adapters": [{ "kind": "claude-code", "import": ["skills", "subagents"] }]
+    }
+  }
+  ```
+  
+  The DECLARATIVE half usetheokit/theokit-sdk#524 asked for, in a `## Sketch` written against TOML.
+  It ships as JSON: this SDK already reads JSON everywhere a project declares something
+  (`settings.json`, `mcp.json`, `context.json`) and carries no TOML parser or dependency for one —
+  adding one for a single optional section would be the opposite of what #522/#524 are about, reading
+  in a new format nobody asked this SDK to speak. The shape is unchanged: `compat.adapters` accepts
+  exactly what `local.compatSources` already does in code — a bare kind string, or `{ kind, import }`.
+  
+  **Precedence, decided here because the issue does not state it:** explicit `local.compatSources` in
+  code wins over the file. The file is the default for a caller who declared nothing. A test or a
+  one-off script can therefore always override the file without editing or deleting it.
+  
+  Read with `readFileSync`, not this package's usual async reader: the caller is `Agent`'s
+  synchronous constructor, which resolves `compatSources` before any submanager exists to await a
+  promise. `existsSync` already runs in the same constructor for the same reason.
+  
+  One resolver, `resolveCompatSources(options, cwd)`, replaces five call sites that each wrote
+  `options.local?.compatSources ?? []` by hand — the same duplication `theokitConfigRoot` closed one
+  layer down, closed here one layer up, so the file form reaches all four surfaces (hooks, skills,
+  plugins, subagents) through the one place rather than needing five separate edits that could drift.
+  
+  Closes the declarative half of #524. `#524` itself stays open until it is verified in an installed
+  release, per this project's issue-lifecycle convention.
+- e7cf2dd: A skill, subagent or plugin now says which directory it was read from.
+  
+  usetheokit/theokit-sdk#524 asks for it in one line — *"whatever is imported should be reportable […]
+  silent inheritance is what made this take a debugging session to notice"* — and a consumer listing
+  its own skills could not tell that one had arrived from `.claude/skills/` rather than the project's
+  own directory.
+  
+  What is new is not the data. It existed on all three and did not reach the caller:
+  
+  - `Skill.source` was already the absolute path to the `SKILL.md`, and the projection that builds
+    `agent.skills` mapped it away along with the body. The projection is right to drop the BODY —
+    that is what `get()` is for — and dropping the PATH with it answered a question nobody asked.
+  - `agent.plugins.list()` has always returned `source` at runtime; the internal type's own docblock
+    says it carries provenance "so callers can audit where the plugin came from". `SDKPluginMetadata`
+    simply never declared it, so the caller received the field and the compiler denied it existed.
+  - `readSubagentsFrom` computes the file path on the line it reads the file, then dropped it.
+    `AgentDefinition.source` keeps it.
+  
+  `source` is optional on all three, and absence means something specific: declared in code, not read
+  from disk. A subagent passed through `AgentOptions.subagents` has no file and `source` is absent.
+  An inline `createSkill` skill has no file either, but already carried the synthetic `inline://<name>`
+  marker before this change (`create-skill.ts`) — so a skill's `source` is now populated for every
+  entry `list()` returns, either a disk path or that marker, and a first version of this fix wrongly
+  described it as absent for that case. An existing regression test (`agent-skills-get.test.ts`,
+  SE21) asserted `list()` must NOT carry `source` at all; it predates #524 and is updated here to
+  assert the marker instead, while still proving the skill's body and references never leak.
+  
+  `SkillsHandle.list` is now typed as the public `SystemPromptSkillRef` instead of restating
+  `{ name; description }` inline. The two had drifted, and an internal handle declaring a narrower
+  shape than the contract it serves silently deletes fields the projection produces — which is exactly
+  how `source` reached the caller at runtime while not existing to the compiler.
+  
+  Closes the visibility half of #524. The declarative `.theokit/config.toml` form is not in this
+  change.
+
+### Patch Changes
+
+- 070ee92: A foreign plugin's entry file is now checked against the root it was actually discovered under.
+  
+  `refresh()` iterates every root a compat source admits — `.theokit/plugins`, and `.claude/plugins`
+  once `compatSources` names the `plugins` surface — and checks each plugin's declared `entry` file
+  exists. That check reconstructed the plugin's directory as `.theokit/plugins/<folder>`
+  unconditionally, regardless of which root the plugin was actually found under.
+  
+  A plugin discovered at `.claude/plugins/my-plugin/` was therefore checked against
+  `.theokit/plugins/my-plugin/` — a directory it never lived in. With nothing there, a legitimate
+  foreign plugin was refused as "entry file is missing." Had a same-named folder existed under
+  `.theokit/plugins/` instead, its entry file would have been read in place of the real one — a path
+  confusion the ADR D79-D80 traversal guard this check calls does not catch, because the guard runs
+  against the wrong root rather than against none.
+  
+  This was reachable through the bare `compatSources: ["claude-code"]` form, which has always admitted
+  the `plugins` surface — not something the per-surface work landing alongside this introduced.
+  
+  Found while testing the per-surface admission work for usetheokit/theokit-sdk#524.
+- 131ab8b: A foreign plugin's `source` field is now a real relative path instead of a single character.
+  
+  Both manifest loaders (Claude Code's `.claude-plugin/plugin.json` form and this SDK's own
+  `PLUGIN.md`/`plugin.json`) built `source` by searching the manifest path for the literal substring
+  `.theokit/` and slicing from there. A manifest read from `.claude/plugins/<name>/…` contains no such
+  substring: `indexOf` returns `-1`, and `.slice(-1)` silently returned the manifest path's LAST
+  CHARACTER — `"n"` from `.json`, `"d"` from `PLUGIN.md` — instead of a path.
+  
+  `source` is exactly the audit trail the visibility half of usetheokit/theokit-sdk#524 exists to
+  provide, and this was broken for precisely the case that matters most: a plugin admitted from a
+  foreign root. Replaced the substring search with `path.relative(cwd, manifestPath)` — the stdlib
+  does this correctly, and it is what the substring search was trying to approximate.
+  
+  Found alongside the entry-file root confusion, testing the same per-surface admission work.
+- 7b4063b: One resolver now answers "where does this project's configuration live?" — `theokitConfigRoot(cwd)`,
+  in `internal/persistence/paths.ts`, semver-exempt.
+  
+  Five readers hand-rolled `join(cwd, ".theokit", ...)` independently: `mcp.json`, the context
+  directory + `context.json`, the hooks-root fallback check, `registry.json`, and the personality
+  `PROJECT_SUBDIR`. `projectConfigRoots` (hooks/skills/subagents/plugins, per usetheokit/theokit-sdk#524)
+  already resolved its native root the same way, inline, making six independent copies of one
+  constant.
+  
+  No filename, format or resulting path changes — this is a pure consolidation, and the project's own
+  lint gate (`no-hardcoded-theokit-path.test.ts`, ratcheted 23 → 14) is the proof: every literal this
+  change removed was already flagged as migration debt, and the full suite is unchanged.
+  
+  Deliberately does NOT touch homedir-anchored state (sessions, credentials, the personality
+  `USER_SUBDIR`, provider discovery) — those follow `getTheokitHome`/`THEOKIT_HOME` by design, and
+  folding them into this resolver would be the exact silent behaviour change
+  `theokitConfigRoot`'s own docblock warns against: a project's committed configuration must never
+  follow an operator's relocated state directory. A regression test pins this — swapping the
+  resolver's body for `getTheokitHome`'s would move all six readers under `THEOKIT_HOME` at once, in
+  one line, with no caller-side signal.
+
 ## 5.0.0-next.1
 
 ### Major Changes

package/dist/{agent-XMKRP27S.js → agent-2KJ3IGRA.js}

@@ -1,14 +1,14 @@
-export { Agent } from './chunk-NCGWJ3HS.js';
+export { Agent } from './chunk-GO5QW4YL.js';
 import './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
-import './chunk-2ZLVT7H3.js';
-import './chunk-IJM7UGS5.js';
+import './chunk-CYKKYNOT.js';
+import './chunk-XJZEBGXD.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.js';
 import './chunk-OR6XIWLB.js';
-import './chunk-UNK4HNJH.js';
+import './chunk-J2SH3PNH.js';
 import './chunk-AAEZSPTC.js';
 import './chunk-K3NH62DG.js';
 import './chunk-UBR5PWD7.js';
@@ -17,7 +17,7 @@ import './chunk-XB4GI5RZ.js';
 import './chunk-24MGQDK3.js';
 import './chunk-2WXHA33T.js';
 import './chunk-HKCKOAIO.js';
-import './chunk-ILGZ2ZZV.js';
+import './chunk-N6OOOYFZ.js';
 import './chunk-KVNWIAO4.js';
 import './chunk-SVQIW5RJ.js';
 import './chunk-FD2UT76F.js';
@@ -27,7 +27,7 @@ import './chunk-NAF4L3T6.js';
 import './chunk-6WAKKTBO.js';
 import './chunk-6X6ID4MO.js';
 import './chunk-XDANGA2C.js';
-import './chunk-WFC26L6Y.js';
+import './chunk-2XRAWOZZ.js';
 import './chunk-SAGRF4IB.js';
 import './chunk-EH6XD3FY.js';
 import './chunk-UKMBRMGT.js';
@@ -41,8 +41,8 @@ import './chunk-TA3K7SBK.js';
 import './chunk-Q5EWJPRY.js';
 import './chunk-EIQFAOFD.js';
 import './chunk-3JHIFQ4I.js';
-import './chunk-XCCGNU3D.js';
-import './chunk-JTZ74HFD.js';
+import './chunk-4S5TWFIZ.js';
+import './chunk-67ADYSTW.js';
 import './chunk-JNAA4G4H.js';
 import './chunk-6M2OIS4Y.js';
 import './chunk-R7WIIPUR.js';
@@ -54,5 +54,5 @@ import './chunk-V22DZIXO.js';
 import './chunk-NJWYQWDL.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-XMKRP27S.js.map
-//# sourceMappingURL=agent-XMKRP27S.js.map
+//# sourceMappingURL=agent-2KJ3IGRA.js.map
+//# sourceMappingURL=agent-2KJ3IGRA.js.map

package/dist/{agent-XMKRP27S.js.map → agent-2KJ3IGRA.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-XMKRP27S.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-2KJ3IGRA.js"}

package/dist/{agent-CgNzshyV.d.cts → agent-C3KO5LKm.d.cts}

@@ -1,4 +1,4 @@
-import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-Dxjb0IfM.cjs';
+import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-BOiKqOgL.cjs';
 import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.cjs';
 
 /**
@@ -952,7 +952,39 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code";
+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
+ */
+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
+ */
+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.
@@ -1098,6 +1130,20 @@ interface CloudOptions {
 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>>;
     /**
@@ -1822,4 +1868,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type SkillsResolver as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderHandle as D, type MemoryProviderInitOptions as E, type PluginContext as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type PluginHookDisposer as J, type PostAssistantReplyContext as K, type LocalOptions as L, type MemorySettings as M, type PostToolCallContext as N, type PreToolCallContext as O, type Plugin as P, type PreUserSendContext as Q, type PreUserSendResult as R, type SystemPromptResolver as S, type ProviderTransform as T, type ProviderTransformContext as U, type RecordSessionSummaryArgs as V, type SessionLifecycleContext as W, type SessionRecord as X, type SessionStore as Y, type SettingSource as Z, Skill as _, type AgentDefinition as a, type SkillsResolverContext as a0, type SystemPromptContext as a1, type SystemPromptMemoryFact as a2, type TelemetrySettings as a3, type ToolCallSummary as a4, type ToolResultTransformContext as a5, type TransformContext as a6, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CreateSkillSpec as x, type MemoryProviderAgentRef as y, type MemoryProviderFactory as z };
+export { type SettingSource as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderAgentRef as D, type MemoryProviderFactory as E, type MemoryProviderHandle as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type MemoryProviderInitOptions as J, type PluginContext as K, type LocalOptions as L, type MemorySettings as M, type PluginHookDisposer as N, type PostAssistantReplyContext as O, type Plugin as P, type PostToolCallContext as Q, type PreToolCallContext as R, type SystemPromptResolver as S, type PreUserSendContext as T, type PreUserSendResult as U, type ProviderTransform as V, type ProviderTransformContext as W, type RecordSessionSummaryArgs as X, type SessionLifecycleContext as Y, type SessionRecord as Z, type SessionStore as _, type AgentDefinition as a, Skill as a0, type SkillsResolver as a1, type SkillsResolverContext as a2, type SystemPromptContext as a3, type SystemPromptMemoryFact as a4, type TelemetrySettings as a5, type ToolCallSummary as a6, type ToolResultTransformContext as a7, type TransformContext as a8, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CompatSourceAdapter as x, type CompatSurface as y, type CreateSkillSpec as z };

package/dist/{agent-CdYJfKr6.d.ts → agent-CvmTR9uf.d.ts}

@@ -1,4 +1,4 @@
-import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-ldzpyAaF.js';
+import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-D4a_BR_6.js';
 import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.js';
 
 /**
@@ -952,7 +952,39 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code";
+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
+ */
+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
+ */
+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.
@@ -1098,6 +1130,20 @@ interface CloudOptions {
 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>>;
     /**
@@ -1822,4 +1868,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type SkillsResolver as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderHandle as D, type MemoryProviderInitOptions as E, type PluginContext as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type PluginHookDisposer as J, type PostAssistantReplyContext as K, type LocalOptions as L, type MemorySettings as M, type PostToolCallContext as N, type PreToolCallContext as O, type Plugin as P, type PreUserSendContext as Q, type PreUserSendResult as R, type SystemPromptResolver as S, type ProviderTransform as T, type ProviderTransformContext as U, type RecordSessionSummaryArgs as V, type SessionLifecycleContext as W, type SessionRecord as X, type SessionStore as Y, type SettingSource as Z, Skill as _, type AgentDefinition as a, type SkillsResolverContext as a0, type SystemPromptContext as a1, type SystemPromptMemoryFact as a2, type TelemetrySettings as a3, type ToolCallSummary as a4, type ToolResultTransformContext as a5, type TransformContext as a6, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CreateSkillSpec as x, type MemoryProviderAgentRef as y, type MemoryProviderFactory as z };
+export { type SettingSource as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type MemoryProviderAgentRef as D, type MemoryProviderFactory as E, type MemoryProviderHandle as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type MemoryProviderInitOptions as J, type PluginContext as K, type LocalOptions as L, type MemorySettings as M, type PluginHookDisposer as N, type PostAssistantReplyContext as O, type Plugin as P, type PostToolCallContext as Q, type PreToolCallContext as R, type SystemPromptResolver as S, type PreUserSendContext as T, type PreUserSendResult as U, type ProviderTransform as V, type ProviderTransformContext as W, type RecordSessionSummaryArgs as X, type SessionLifecycleContext as Y, type SessionRecord as Z, type SessionStore as _, type AgentDefinition as a, Skill as a0, type SkillsResolver as a1, type SkillsResolverContext as a2, type SystemPromptContext as a3, type SystemPromptMemoryFact as a4, type TelemetrySettings as a5, type ToolCallSummary as a6, type ToolResultTransformContext as a7, type TransformContext as a8, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type MemoryProvider as k, type PreToolCallDecision as l, type ActiveMemoryPassArgs as m, type ActiveMemoryPassResult as n, type AgentSubagentDescription as o, type AgentToolDescription as p, type BudgetCheck as q, type BudgetTotal as r, type BudgetUsageEvent as s, type BuiltinToolName as t, type CloudEnv as u, type CloudRepo as v, type CompatSource as w, type CompatSourceAdapter as x, type CompatSurface as y, type CreateSkillSpec as z };

package/dist/{agent-2E7DI47Y.cjs → agent-V6YLX3W6.cjs}

@@ -1,16 +1,16 @@
 'use strict';
 
-var chunkWMH2MSOP_cjs = require('./chunk-WMH2MSOP.cjs');
+var chunkK6VDRJ6I_cjs = require('./chunk-K6VDRJ6I.cjs');
 require('./chunk-KVSAY6NZ.cjs');
 require('./chunk-Y2KYR2ED.cjs');
 require('./chunk-BUUUWQMB.cjs');
-require('./chunk-2NE7DTOK.cjs');
-require('./chunk-HWSALKOR.cjs');
+require('./chunk-KBXADFBJ.cjs');
+require('./chunk-H6YM3PV6.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-D6POWE7E.cjs');
 require('./chunk-GHX4P3V2.cjs');
 require('./chunk-TMKTSYDS.cjs');
-require('./chunk-LHSWHYF3.cjs');
+require('./chunk-RXZSVNDG.cjs');
 require('./chunk-7FDKWDA2.cjs');
 require('./chunk-2HPNT6HH.cjs');
 require('./chunk-FUSDYC2B.cjs');
@@ -19,7 +19,7 @@ require('./chunk-24SYBZPL.cjs');
 require('./chunk-QOGNZMHD.cjs');
 require('./chunk-YIFFF23U.cjs');
 require('./chunk-2ZPEDVLM.cjs');
-require('./chunk-RHZ6HP23.cjs');
+require('./chunk-IU5N5224.cjs');
 require('./chunk-KRD3GQAA.cjs');
 require('./chunk-RQMCOFAI.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
@@ -29,7 +29,7 @@ require('./chunk-FRITRLZQ.cjs');
 require('./chunk-QME6FDFG.cjs');
 require('./chunk-NINIJCHU.cjs');
 require('./chunk-UGRS7ZA7.cjs');
-require('./chunk-LKFET5A3.cjs');
+require('./chunk-LOHMT36V.cjs');
 require('./chunk-IJ7M6GOG.cjs');
 require('./chunk-7A6535RA.cjs');
 require('./chunk-SA6K24NB.cjs');
@@ -43,8 +43,8 @@ require('./chunk-BJUJT5ED.cjs');
 require('./chunk-ZF2LDKQQ.cjs');
 require('./chunk-HCT4HPCL.cjs');
 require('./chunk-JLRLCBJ4.cjs');
-require('./chunk-G4ZGYKJG.cjs');
-require('./chunk-CEILSTWB.cjs');
+require('./chunk-SYVWE64W.cjs');
+require('./chunk-GGZ5GPE3.cjs');
 require('./chunk-HW7SEELD.cjs');
 require('./chunk-ATT276RD.cjs');
 require('./chunk-3EE6LVWT.cjs');
@@ -61,7 +61,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkWMH2MSOP_cjs.Agent; }
+  get: function () { return chunkK6VDRJ6I_cjs.Agent; }
 });
-//# sourceMappingURL=agent-2E7DI47Y.cjs.map
-//# sourceMappingURL=agent-2E7DI47Y.cjs.map
+//# sourceMappingURL=agent-V6YLX3W6.cjs.map
+//# sourceMappingURL=agent-V6YLX3W6.cjs.map

package/dist/{agent-2E7DI47Y.cjs.map → agent-V6YLX3W6.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-2E7DI47Y.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-V6YLX3W6.cjs"}

package/dist/{chunk-WFC26L6Y.js → chunk-2XRAWOZZ.js}

@@ -73,6 +73,29 @@ var DEFAULT_DISCOVERY_SPECS = [
     followImports: false,
     priority: 50
   },
+  {
+    // usetheokit/theokit-sdk#531 — THEO.md was the only context file that could not live at the
+    // project root: every sibling here is `git-root-walk`, and this one was `cwd-only` pointed
+    // at `.theokit/THEO.md` specifically, with no warning that a root THEO.md was inert.
+    //
+    // ADDED rather than moving the existing entry below: a project already using
+    // `.theokit/THEO.md` keeps working unchanged. 55 sits between `theokit-context` (50) and the
+    // existing `THEO.md` (60), leaving room on both sides — the numbering discipline
+    // `claude-rules` (47) already established for this array.
+    //
+    // `followImports: true`, unlike the existing entry (`false`) and unlike `AGENTS.md`. This is
+    // a DELIBERATE divergence between the two THEO.md specs, not an inconsistency: a root-level
+    // file is edited by the same people, in the same place, as CLAUDE.md/GEMINI.md — the two
+    // other root-level, human-facing files that both carry `followImports: true` — so it belongs
+    // in their category rather than AGENTS.md's vendor-neutral, import-free one. Because this is a
+    // NEW spec, choosing `true` here changes nothing for `.theokit/THEO.md`, which keeps `false`.
+    id: "THEO.md.root",
+    pattern: "THEO.md",
+    scope: "git-root-walk",
+    parser: "plain-markdown",
+    followImports: true,
+    priority: 55
+  },
   {
     id: "THEO.md",
     pattern: ".theokit/THEO.md",
@@ -145,5 +168,5 @@ async function walkUpForGlob(cwd, pattern) {
 }
 
 export { DEFAULT_DISCOVERY_SPECS, findGitRoot, isSafePattern, walkUpForFile, walkUpForGlob };
-//# sourceMappingURL=chunk-WFC26L6Y.js.map
-//# sourceMappingURL=chunk-WFC26L6Y.js.map
+//# sourceMappingURL=chunk-2XRAWOZZ.js.map
+//# sourceMappingURL=chunk-2XRAWOZZ.js.map

package/dist/chunk-2XRAWOZZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/runtime/context/context-discovery.ts"],"names":[],"mappings":"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","file":"chunk-2XRAWOZZ.js","sourcesContent":["/**\n * Context file discovery (T1.1, ADRs D150 / D151).\n *\n * Discovers context files via three scopes:\n *  - `cwd-only` — single dir, single path lookup\n *  - `git-root-walk` — walk cwd → git-root, collect every directory's match\n *    (nearest-first ordering)\n *  - `globbed` — glob pattern relative to cwd (e.g. `.cursor/rules/*.mdc`)\n *\n * Pure `existsSync` checks — **no `.gitignore` parsing** (EC-A, KISS) and\n * **no invented `.theokitignore`** (EC-B). Paths normalized via\n * `realpath` to dedup symlink chains pointing to the same physical file\n * (EC-F). Git worktrees work transparently because `.git` exists as a\n * file in that case (EC-N).\n *\n * @internal\n */\n\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { glob } from \"node:fs/promises\";\nimport { dirname, isAbsolute, join, resolve } from \"node:path\";\n\n/** Single filename (\"AGENTS.md\") or relative glob (\".cursor/rules/*.mdc\"). */\nexport type DiscoveryScope = \"cwd-only\" | \"git-root-walk\" | \"globbed\";\n\n/** Parser to apply once file is read. */\nexport type DiscoveryParser = \"plain-markdown\" | \"mdc\" | \"frontmatter-zod\" | \"rules-frontmatter\";\n\n/**\n * One kind of context file the runner knows how to find and read. The shipped registry is\n * `DEFAULT_DISCOVERY_SPECS`; a caller supplies its own array to change the set.\n *\n * `scope` decides how `pattern` is used and how many files a single spec can yield:\n * `cwd-only` looks for one path and stops, `git-root-walk` collects a match in every directory\n * from `cwd` up to the git root (nearest first), and `globbed` expands `pattern` as a glob\n * relative to `cwd`. So `pattern` is a filename for the first two and a glob for the third —\n * putting a glob on a walk scope silently finds nothing.\n *\n * `priority` orders the merged prompt, ascending, and is a plain number rather than an index, so\n * a new spec can be slotted between two existing ones. Lower means earlier and therefore more\n * general; later content wins on conflict.\n *\n * `parser` must match the file format — `plain-markdown` reads the whole file, `mdc` and\n * `rules-frontmatter` parse frontmatter and can DECLINE the file when its activation conditions\n * do not hold, and `frontmatter-zod` is the legacy path the runner currently skips entirely.\n *\n * `followImports` is honored only by `plain-markdown`, and turns `@path` directives in the body\n * into inlined content bounded by the import root. Setting it on a frontmatter parser does\n * nothing.\n *\n * `id` names the source in `<source name=\"\">` and in telemetry. When one spec matches files in\n * several directories, the runner suffixes it with the path relative to the git root to keep them\n * apart.\n *\n * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.\n */\nexport interface DiscoverySpec {\n  /** Stable identifier — used as `<source name=\"\">` and telemetry key. */\n  readonly id: string;\n  /** Priority for merge (lower = earlier in prompt). */\n  readonly priority: number;\n  /** Filename (cwd-only/git-root-walk) or glob (globbed). */\n  readonly pattern: string;\n  readonly scope: DiscoveryScope;\n  readonly parser: DiscoveryParser;\n  /** Whether to follow `@path` import directives (CLAUDE.md / GEMINI.md). */\n  readonly followImports: boolean;\n}\n\n/**\n * The context files theokit looks for out of the box, in the order they are concatenated.\n *\n * Two things follow from the ordering. `AGENTS.md` comes first at priority 10 and `THEO.md` last,\n * so theokit-specific instruction wins over the vendor-neutral file on conflict. And the array is\n * consumed in the order written — the runner does not re-sort it — so a caller passing its own\n * array is responsible for keeping `priority` and array position consistent.\n *\n * `CLAUDE.md` and `GEMINI.md` are the only two entries with `followImports: true`, which means\n * they are the only files whose `@path` directives pull other files into the prompt. Those\n * imports cannot escape the import root.\n *\n * Frozen only by type: `ReadonlyArray` is a compile-time constraint, and the array and its\n * elements are not deep-frozen at runtime. Build a new array rather than mutating this one.\n *\n * @public — re-exported from `@theokit/sdk/context`, and therefore under semver.\n */\nexport const DEFAULT_DISCOVERY_SPECS: ReadonlyArray<DiscoverySpec> = [\n  {\n    id: \"AGENTS.md\",\n    pattern: \"AGENTS.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: false,\n    priority: 10,\n  },\n  {\n    id: \"GEMINI.md\",\n    pattern: \"GEMINI.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 20,\n  },\n  {\n    id: \"CLAUDE.md\",\n    pattern: \"CLAUDE.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 30,\n  },\n  {\n    id: \"cursor-rules\",\n    pattern: \".cursor/rules/*.mdc\",\n    scope: \"globbed\",\n    parser: \"mdc\",\n    followImports: false,\n    priority: 40,\n  },\n  {\n    id: \"theokit-rules\",\n    pattern: \".theokit/rules/*.md\",\n    scope: \"globbed\",\n    parser: \"rules-frontmatter\",\n    followImports: false,\n    priority: 45,\n  },\n  {\n    // Rules written for the Claude Code CLI. Measured 2026-08-26 over this repository's 32 rule\n    // files: none carries frontmatter, and `rules-frontmatter` already reads a file without it as\n    // `alwaysApply: true` — the format needed nothing, only a spec pointing at the directory.\n    //\n    // 47, not 46. Specs sort ascending and a context budget drops the tail first, so it must land\n    // AFTER `.theokit/rules` (45) — the explicit namespace should survive a squeeze the borrowed one\n    // does not. It must also leave a slot on BOTH sides: B-127 makes these numbers a public contract\n    // precisely so a consumer can place its own source between two defaults, and 46 would have left\n    // no room between 45 and itself. 47 keeps 46 free below and 48–49 free above.\n    //\n    // The reckoning B-127's docblock asks for: no published priority MOVES, so a consumer that chose\n    // 46, 48 or 49 is unaffected. A consumer that had chosen 47 now collides — that is the cost of\n    // an eighth default, paid once and recorded here rather than discovered later.\n    id: \"claude-rules\",\n    pattern: \".claude/rules/*.md\",\n    scope: \"globbed\",\n    parser: \"rules-frontmatter\",\n    followImports: false,\n    priority: 47,\n  },\n  {\n    id: \"theokit-context\",\n    pattern: \".theokit/context/*.md\",\n    scope: \"globbed\",\n    parser: \"frontmatter-zod\",\n    followImports: false,\n    priority: 50,\n  },\n  {\n    // usetheokit/theokit-sdk#531 — THEO.md was the only context file that could not live at the\n    // project root: every sibling here is `git-root-walk`, and this one was `cwd-only` pointed\n    // at `.theokit/THEO.md` specifically, with no warning that a root THEO.md was inert.\n    //\n    // ADDED rather than moving the existing entry below: a project already using\n    // `.theokit/THEO.md` keeps working unchanged. 55 sits between `theokit-context` (50) and the\n    // existing `THEO.md` (60), leaving room on both sides — the numbering discipline\n    // `claude-rules` (47) already established for this array.\n    //\n    // `followImports: true`, unlike the existing entry (`false`) and unlike `AGENTS.md`. This is\n    // a DELIBERATE divergence between the two THEO.md specs, not an inconsistency: a root-level\n    // file is edited by the same people, in the same place, as CLAUDE.md/GEMINI.md — the two\n    // other root-level, human-facing files that both carry `followImports: true` — so it belongs\n    // in their category rather than AGENTS.md's vendor-neutral, import-free one. Because this is a\n    // NEW spec, choosing `true` here changes nothing for `.theokit/THEO.md`, which keeps `false`.\n    id: \"THEO.md.root\",\n    pattern: \"THEO.md\",\n    scope: \"git-root-walk\",\n    parser: \"plain-markdown\",\n    followImports: true,\n    priority: 55,\n  },\n  {\n    id: \"THEO.md\",\n    pattern: \".theokit/THEO.md\",\n    scope: \"cwd-only\",\n    parser: \"plain-markdown\",\n    followImports: false,\n    priority: 60,\n  },\n];\n\nconst SAFE_FILENAME = /^[a-zA-Z0-9_.\\-/*]+$/;\nconst TRAVERSAL_RE = /(^|\\/)\\.\\.(\\/|$)/;\n\n/**\n * Reject patterns that contain path traversal (`..`) or non-allowed\n * characters (D81 parity, EC-4).\n *\n * @internal\n */\nexport function isSafePattern(pattern: string): boolean {\n  if (typeof pattern !== \"string\" || pattern.length === 0) return false;\n  if (TRAVERSAL_RE.test(pattern)) return false;\n  if (isAbsolute(pattern)) return false;\n  return SAFE_FILENAME.test(pattern);\n}\n\n/**\n * Walk upward from `cwd` looking for the closest directory containing\n * a `.git` entry (file OR directory — worktrees use a `.git` FILE,\n * EC-N). Returns the absolute path of that directory, or `undefined`\n * when no git root exists at or above `cwd`.\n *\n * @internal\n */\nexport function findGitRoot(cwd: string): string | undefined {\n  if (typeof cwd !== \"string\" || cwd.length === 0) return undefined;\n  let current = resolve(cwd);\n  // Guard against infinite loops on weird filesystems.\n  for (let i = 0; i < 64; i += 1) {\n    if (existsSync(join(current, \".git\"))) return current;\n    const parent = dirname(current);\n    if (parent === current) return undefined;\n    current = parent;\n  }\n  return undefined;\n}\n\n/**\n * Walk `cwd` upward to `stopDir` (inclusive) collecting every existing\n * occurrence of `filename`. Returns absolute, realpath-deduped paths in\n * nearest-first order (innermost dir first).\n *\n * No `.gitignore` parsing (EC-A). Realpath collapses symlink chains\n * pointing to the same physical file (EC-F). Filesystem races (file\n * deleted mid-walk) are skipped silently (EC-5).\n *\n * @internal\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: walk-up loop combines validation + realpath dedup + FS-race handling + stopDir guard in a single bounded loop; splitting fragments the dedup invariant.\nexport function walkUpForFile(\n  cwd: string,\n  filename: string,\n  stopDir: string | undefined,\n): string[] {\n  if (!isSafePattern(filename)) {\n    return [];\n  }\n  const start = resolve(cwd);\n  const stop = stopDir !== undefined ? resolve(stopDir) : undefined;\n  const found: string[] = [];\n  const seenReal = new Set<string>();\n  let current = start;\n  // 64-level depth cap.\n  for (let i = 0; i < 64; i += 1) {\n    const candidate = join(current, filename);\n    if (existsSync(candidate)) {\n      let real: string;\n      try {\n        real = realpathSync(candidate);\n      } catch {\n        // FS race (deleted mid-walk) — skip.\n        real = candidate;\n      }\n      if (!seenReal.has(real)) {\n        seenReal.add(real);\n        found.push(real);\n      }\n    }\n    if (stop !== undefined && current === stop) break;\n    const parent = dirname(current);\n    if (parent === current) break;\n    current = parent;\n  }\n  return found;\n}\n\n/**\n * Glob-style discovery under `cwd` (e.g. `.cursor/rules/*.mdc`, `.theokit/rules/**\\/*.md`).\n * Returns absolute, lex-sorted paths.\n *\n * `*` matches within one path segment and `**` spans any depth, including zero — so\n * `.theokit/rules/**\\/*.md` finds `rules/top.md` as well as `rules/deep/nested/inner.md`, while\n * `.theokit/rules/*.md` keeps its flat meaning and finds only the first. That distinction is the\n * compatibility contract: every existing spec uses a single `*`, and widening it would silently\n * start absorbing nested files nobody chose to expose.\n *\n * ## Why this used to be flat, and what changed (B-119)\n *\n * The previous implementation split the pattern at its LAST `/`, treated the prefix as a literal\n * directory and did one `readdir` — documented as \"nested directories deferred to v2\" (EC-R). The\n * deferral was deliberate; what made it a defect was measured from a consumer. TheoCode's own rule\n * loader descends recursively, so migrating it onto the `theokit-rules` spec would have silently\n * dropped every nested rule — on the path that decides whether a repository's hooks execute. And a\n * pattern written to say so, `.theokit/rules/**\\/*.md`, resolved its directory part to a literal\n * `**` and matched NOTHING, not even the top-level file it matched before the globstar was added.\n *\n * ## Why the stdlib rather than a walker\n *\n * `fs.promises.glob` (Node ≥ 22, and this package requires ≥ 22.12) implements exactly these\n * semantics, verified against a fixture before adoption: `**\\/*.md` returns all three depths,\n * `*.md` returns one, and it emits no experimental warning. Writing a recursive walker here would\n * have been a third implementation of matching inside one package — the same duplication that let\n * the enumerator and the compiler in `context-glob.ts` disagree in the first place. `globToRegex`\n * stays where it belongs: deciding whether a rule APPLIES to a set of paths, which is a different\n * question from which files exist.\n *\n * `isSafePattern` still runs first and is unchanged, so `..` is refused before any I/O.\n *\n * @internal\n */\nexport async function walkUpForGlob(cwd: string, pattern: string): Promise<string[]> {\n  if (!isSafePattern(pattern)) return [];\n  const found: string[] = [];\n  try {\n    for await (const entry of glob(pattern, { cwd })) {\n      found.push(resolve(cwd, entry));\n    }\n  } catch {\n    // A pattern whose directory does not exist is the ordinary case — most projects have no\n    // `.cursor/rules/`. Same outcome as matching nothing.\n    return [];\n  }\n  // Sorted, because discovery order becomes prompt order and must not vary with the filesystem.\n  //\n  // The comparator is explicit and deliberately NOT `localeCompare`, which is the usual suggestion\n  // for a bare `.sort()`. `localeCompare` orders by the machine's locale, so the same tree would\n  // assemble a different prompt on a differently-configured machine — trading one source of\n  // non-determinism for a subtler one. Code-unit ordering is what a bare `.sort()` already does for\n  // strings; writing it out states the intent and keeps the result machine-independent.\n  return found.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));\n}\n"]}

package/dist/{chunk-XCCGNU3D.js → chunk-4S5TWFIZ.js}

@@ -1,4 +1,4 @@
-import { pluginBundleRoots, projectConfigRoots } from './chunk-JTZ74HFD.js';
+import { pluginBundleRoots, projectConfigRoots } from './chunk-67ADYSTW.js';
 import { readWorkspaceDir, parseSimpleYaml } from './chunk-JNAA4G4H.js';
 import { ConfigurationError } from './chunk-ALUN2B4W.js';
 import { diag } from './chunk-CZJ6Q7CW.js';
@@ -39,7 +39,7 @@ async function loadSubagents(cwd, settingSourcesIncludeProject, inline, compatSo
 }
 async function readProjectSubagents(cwd, compatSources) {
   const subagents = {};
-  for (const configRoot of projectConfigRoots(cwd, compatSources)) {
+  for (const configRoot of projectConfigRoots(cwd, compatSources, "subagents")) {
     await readSubagentsFrom(join(configRoot, "agents"), subagents);
   }
   for (const bundle of await pluginBundleDirs(cwd, compatSources)) {
@@ -59,7 +59,7 @@ async function readSubagentsFrom(root, subagents) {
     }
     const definition = parseSubagentMarkdown(raw, entry.name);
     if (subagents[definition.name] === void 0) {
-      subagents[definition.name] = definition.definition;
+      subagents[definition.name] = { ...definition.definition, source: path };
     }
   }
 }
@@ -165,5 +165,5 @@ function parseFrontmatterFields(frontmatter) {
 }
 
 export { loadSubagents, pluginBundleDirs };
-//# sourceMappingURL=chunk-XCCGNU3D.js.map
-//# sourceMappingURL=chunk-XCCGNU3D.js.map
+//# sourceMappingURL=chunk-4S5TWFIZ.js.map
+//# sourceMappingURL=chunk-4S5TWFIZ.js.map