@theokit/sdk 5.5.0 → 5.7.0

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

@@ -50,12 +50,24 @@ export declare class HooksExecutor {
     private readonly compatSources;
     /** #631 — the consumer's chance to refuse a command before it is spawned. */
     private readonly gate;
+    /**
+     * B-026 — the operator tier. `managedSettingsRoot` exists so the precedence rule is testable;
+     * production passes nothing and the platform path is resolved.
+     */
+    private readonly policy;
     private config;
     constructor(cwd: string, 
     /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */
     compatSources?: readonly CompatSourceDeclaration[], 
     /** #631 — the consumer's chance to refuse a command before it is spawned. */
-    gate?: HookApprovalGate | undefined);
+    gate?: HookApprovalGate | undefined, 
+    /**
+     * B-026 — the operator tier. `managedSettingsRoot` exists so the precedence rule is testable;
+     * production passes nothing and the platform path is resolved.
+     */
+    policy?: {
+        readonly managedSettingsRoot?: 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

@@ -8,14 +8,49 @@
  *
  * Consumed by `hooks-executor.ts` (runtime dispatch).
  *
- * Config shape (identical to Claude Code's `settings.json` hooks):
+ * Config SHAPE is Claude Code's `settings.json` hooks:
  *   { "hooks": { "PreToolUse": [ { "matcher": "shell",
  *       "hooks": [ { "type": "command", "command": "…", "timeout": 30 } ] } ] } }
  *
+ * The shape, not the event COVERAGE. Four of the thirty-three documented events are fired by this
+ * runtime — see {@link CLAUDE_CODE_EVENT_MAP} for which, why the rest are refused rather than
+ * mapped, and the order in which they should be added. An event outside the set is reported to the
+ * operator rather than skipped in silence.
+ *
  * @internal
  */
 /** The five lifecycle events the SDK runtime actually fires. */
 export type HookEvent = "preRun" | "postRun" | "preToolUse" | "postToolUse" | "stop";
+/**
+ * The Claude Code event names this runtime actually FIRES, and the internal event each becomes.
+ *
+ * Exported so the supported set is stated rather than implied. It used to be private, and the
+ * docblock above claimed a shape "identical to Claude Code's `settings.json` hooks" while accepting
+ * four of the thirty-three documented events — a claim nothing could contradict.
+ *
+ * A Claude Code event with no firing point here — `SessionStart`, `SubagentStop`, `PreCompact`,
+ * `Notification`, `SessionEnd` among them — is skipped with a report rather than silently accepted,
+ * because it would never run.
+ *
+ * ## Why this map is not simply grown
+ *
+ * Mapping a name the runtime does not fire is strictly WORSE than refusing it. An operator declaring
+ * `PreCompact` today gets a report saying it will not fire; with the name mapped they would get
+ * silence and a guard that never runs — a declared veto that does not exist. The map grows when the
+ * seam exists, one event at a time.
+ *
+ * ## Priority, when it does grow
+ *
+ * The blocking events first. An unwired veto loses a CAPABILITY; an unwired observer loses a
+ * SIGNAL. Thirteen of the sixteen the spec marks "Can block? Yes" are unwired, and
+ * `tests/internal/runtime/hooks/the-supported-event-set-is-stated.test.ts` lists them in the order
+ * they should be taken, so the next person does not re-derive which is which.
+ *
+ * `postRun` is reachable through this SDK's own config and has no entry here on purpose: it fires
+ * per RUN, and no documented Claude Code event means that. `SessionEnd` is the near miss, and a
+ * session is not a run.
+ */
+export declare const CLAUDE_CODE_EVENT_MAP: Readonly<Record<string, HookEvent>>;
 export interface HookCommand {
     command: string;
     matcher?: string;

package/dist/internal/runtime/skills/discover-skills.d.ts

@@ -13,6 +13,10 @@ export interface Skill {
     source: string;
     category?: string;
     dependencies?: string[];
+    /** `disable-model-invocation: true` — the model is never told this skill exists. */
+    disableModelInvocation?: boolean;
+    /** `user-invocable: false` — carried for a host that has a picker; this SDK has no such surface. */
+    userInvocable?: boolean;
 }
 /**
  * Information passed to `onInvalidSkill` when a `SKILL.md` is present but its

package/dist/internal/session/compact-session.d.ts

@@ -30,6 +30,31 @@ export interface CompactResult {
 }
 /** Is this message a summary produced by a PRIOR compaction? (filtered from verbatim preservation). */
 export declare function isCompactSummary(content: string): boolean;
+/**
+ * What a pre-compaction handler is told, and what it is given to bail out with.
+ *
+ * `trigger` is READ from the compaction that is happening, never inferred from the call site: the
+ * inference would be right today and silently wrong the first time a third caller appears.
+ *
+ * @public
+ */
+export interface PreCompactContext {
+    /** The messages about to be summarised — what the handler gets a last look at. */
+    readonly messages: readonly CompressibleMessage[];
+    /** `manual` when a person asked, `auto` when a usage threshold did. */
+    readonly trigger: "manual" | "auto";
+    /** Aborted when the bound fires, so a long handler can stop rather than be merely ignored. */
+    readonly signal: AbortSignal;
+}
+/** @public */
+export type PreCompactHandler = (ctx: PreCompactContext) => void | Promise<void>;
+/**
+ * The bound, in milliseconds, when the caller does not choose one.
+ *
+ * Same value as `@theokit/agents`' `withPreCompaction`, because B-082's requirement is the same
+ * contract as B-002 and not a second one.
+ */
+export declare const DEFAULT_PRE_COMPACT_TIMEOUT_MS = 30000;
 /**
  * Compact one session transcript: summarize the reconstructed history, then append (append-only)
  * a `compact_boundary` + the replacement chain (recent user messages verbatim + marker'd summary).
@@ -42,6 +67,17 @@ export declare function compactSessionTranscript(opts: {
     sessionId: string;
     trigger: "manual" | "auto";
     summarize: (messages: readonly CompressibleMessage[]) => Promise<string>;
+    /**
+     * Work to run before the transcript is rewritten, on the path the caller actually took.
+     *
+     * Absent, nothing is entered and the path is byte-identical to before B-082 — asserted by a test
+     * rather than left as an inference.
+     */
+    onPreCompact?: PreCompactHandler;
+    /** Where a handler's failure or timeout is reported. Compaction proceeds either way. */
+    onPreCompactError?: (error: unknown) => void;
+    /** Overrides {@link DEFAULT_PRE_COMPACT_TIMEOUT_MS}. */
+    preCompactTimeoutMs?: number;
 }): Promise<CompactResult>;
 /**
  * M50 review F6 (fixed by the probe) — the summarizer's provider route, PURE and unit-tested.

package/dist/project.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkLOHMT36V_cjs = require('./chunk-LOHMT36V.cjs');
+var chunk7KBNBPFK_cjs = require('./chunk-7KBNBPFK.cjs');
 var chunkJLRLCBJ4_cjs = require('./chunk-JLRLCBJ4.cjs');
 var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
 require('./chunk-6LHQPOMI.cjs');
@@ -11,7 +11,7 @@ var DEFAULT_FILENAME = "THEO.md";
 async function readProjectInstructions(cwd, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
   const scope = options?.scope ?? "nearest";
-  const paths = chunkLOHMT36V_cjs.walkUpForFile(cwd, filename, options?.stopDir);
+  const paths = chunk7KBNBPFK_cjs.walkUpForFile(cwd, filename, options?.stopDir);
   const files = [];
   for (const path of paths) {
     try {
@@ -30,7 +30,7 @@ function reduceContent(files, scope) {
 }
 async function writeProjectInstructions(cwd, content, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
-  if (!chunkLOHMT36V_cjs.isSafePattern(filename)) {
+  if (!chunk7KBNBPFK_cjs.isSafePattern(filename)) {
     throw new chunkJ7J7J2GN_cjs.ConfigurationError(
       `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,
       { code: "unsafe_filename" }

package/dist/project.js

@@ -1,4 +1,4 @@
-import { walkUpForFile, isSafePattern } from './chunk-2XRAWOZZ.js';
+import { walkUpForFile, isSafePattern } from './chunk-A6PDYH55.js';
 import { replaceFileAtomic } from './chunk-3JHIFQ4I.js';
 import { ConfigurationError } from './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';

package/dist/skills.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunkQATRS7JD_cjs = require('./chunk-QATRS7JD.cjs');
+var chunkMYJGWS2J_cjs = require('./chunk-MYJGWS2J.cjs');
 require('./chunk-7A6535RA.cjs');
 require('./chunk-SA6K24NB.cjs');
-require('./chunk-HW7SEELD.cjs');
+require('./chunk-QRVS2PRE.cjs');
 require('./chunk-J7J7J2GN.cjs');
 require('./chunk-6LHQPOMI.cjs');
 
@@ -11,15 +11,15 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "buildSkillsBlock", {
   enumerable: true,
-  get: function () { return chunkQATRS7JD_cjs.buildSkillsBlock; }
+  get: function () { return chunkMYJGWS2J_cjs.buildSkillsBlock; }
 });
 Object.defineProperty(exports, "discoverSkills", {
   enumerable: true,
-  get: function () { return chunkQATRS7JD_cjs.discoverSkills; }
+  get: function () { return chunkMYJGWS2J_cjs.discoverSkills; }
 });
 Object.defineProperty(exports, "loadSkillInstructions", {
   enumerable: true,
-  get: function () { return chunkQATRS7JD_cjs.loadSkillInstructions; }
+  get: function () { return chunkMYJGWS2J_cjs.loadSkillInstructions; }
 });
 //# sourceMappingURL=skills.cjs.map
 //# sourceMappingURL=skills.cjs.map

package/dist/skills.js

@@ -1,7 +1,7 @@
-export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-LX7SEXOQ.js';
+export { buildSkillsBlock, discoverSkills, loadSkillInstructions } from './chunk-CA5VUAP3.js';
 import './chunk-EH6XD3FY.js';
 import './chunk-UKMBRMGT.js';
-import './chunk-JNAA4G4H.js';
+import './chunk-UOLBAPDM.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
 //# sourceMappingURL=skills.js.map

package/dist/subagents-loader-CJFYQQU2.js

@@ -0,0 +1,7 @@
+export { loadSubagents } from './chunk-T3ZDEYTJ.js';
+import './chunk-X7EUUHXU.js';
+import './chunk-UOLBAPDM.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=subagents-loader-CJFYQQU2.js.map
+//# sourceMappingURL=subagents-loader-CJFYQQU2.js.map

package/dist/{subagents-loader-AIVDQ2D5.js.map → subagents-loader-CJFYQQU2.js.map}

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

package/dist/subagents-loader-MOO7DC4E.cjs

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

package/dist/{subagents-loader-DN4LETGL.cjs.map → subagents-loader-MOO7DC4E.cjs.map}

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

package/dist/subagents-loader.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkAYA65JA5_cjs = require('./chunk-AYA65JA5.cjs');
-require('./chunk-43YXGD3P.cjs');
-require('./chunk-HW7SEELD.cjs');
+var chunkRWPLWMCZ_cjs = require('./chunk-RWPLWMCZ.cjs');
+require('./chunk-TY56BKSK.cjs');
+require('./chunk-QRVS2PRE.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 chunkAYA65JA5_cjs.loadSubagents(cwd, sources.includes("project"), void 0, options?.compatSources ?? []);
+  return chunkRWPLWMCZ_cjs.loadSubagents(cwd, sources.includes("project"), void 0, options?.compatSources ?? []);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-DyB_lzrx.cjs';
+import { a as AgentDefinition } from './agent-Dya5SmhY.cjs';
 import './sdk-agent-BOiKqOgL.cjs';
 import './run-CTAdRU3U.cjs';
 import 'zod';

package/dist/subagents-loader.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-CjMVbhhY.js';
+import { a as AgentDefinition } from './agent-Bqzdhkqr.js';
 import './sdk-agent-D4a_BR_6.js';
 import './run-CTAdRU3U.js';
 import 'zod';

package/dist/subagents-loader.js

@@ -1,6 +1,6 @@
-import { loadSubagents } from './chunk-O7L7M42F.js';
-import './chunk-NSLHPAC7.js';
-import './chunk-JNAA4G4H.js';
+import { loadSubagents } from './chunk-T3ZDEYTJ.js';
+import './chunk-X7EUUHXU.js';
+import './chunk-UOLBAPDM.js';
 import { ConfigurationError } from './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
 

package/dist/types/agent.d.ts

@@ -31,7 +31,7 @@ export type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "a
  *
  * @public
  */
-export type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
+export type CompatSource = "claude-code" | "theokit" | "agents" | "gemini" | "cursor" | CompatSourceAdapter;
 /**
  * A surface a foreign configuration source may be admitted to.
  *
@@ -40,9 +40,14 @@ export type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
  * 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.
  *
+ * `context` is the foreign root's INSTRUCTIONS — `.claude/rules/*.md`. Same risk class as `skills`:
+ * text a cloned repository wrote, entering the system prompt as if the consumer had written it. It
+ * was missing until usetheokit/theokit-sdk#652, so the four surfaces above failed closed while this
+ * one was admitted by a path that consulted no grant at all.
+ *
  * @public
  */
-export type CompatSurface = "hooks" | "plugins" | "skills" | "subagents";
+export type CompatSurface = "context" | "hooks" | "plugins" | "skills" | "subagents";
 /**
  * A foreign source admitted to named surfaces only.
  *

package/docs/error-codes.md

@@ -6,7 +6,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 
 **Transport codes vs the rest.** `ErrorCode` in `errors.ts` is the small canonical union a provider failure maps onto — the codes marked *transport* below. Everything else is raised by a specific subsystem at a specific place, and a `catch` that only handles the union will meet them anyway.
 
-241 distinct code(s).
+243 distinct code(s).
 
 | Code | Kind | Raised by | Sites |
 |---|---|---|---|
@@ -47,18 +47,18 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `cloud_stdio_cwd_rejected` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:121` |
 | `compression_failed` | domain | — | `packages/sdk/src/internal/runtime/compression/compression-summarizer.ts:41` |
 | `compression_model_unresolved` | domain | — | `packages/sdk/src/internal/runtime/compression/compression-model-registry.ts:102` +1 |
-| `context_config_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:256` |
+| `context_config_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:288` |
 | `context_frontmatter_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-frontmatter.ts:38` |
-| `context_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:250` |
-| `context_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:237` |
-| `context_sources_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:277` |
+| `context_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:282` |
+| `context_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:269` |
+| `context_sources_shape` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/context/context-manager.ts:309` |
 | `credential_pool_ambiguous` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:68` +1 |
 | `credential_pool_empty` | domain | ConfigurationError | `packages/sdk/src/internal/llm/credential-pool.ts:91` |
 | `cron_ambiguous_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:215` |
 | `cron_missing_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:233` +1 |
 | `cron_no_target` | domain | ConfigurationError | `packages/sdk/src/cron.ts:221` +1 |
 | `cron_workflow_message` | domain | ConfigurationError | `packages/sdk/src/cron.ts:227` |
-| `duplicate_skill_name` | domain | ConfigurationError | `packages/sdk/src/define-skill-read-tool.ts:72` |
+| `duplicate_skill_name` | domain | ConfigurationError | `packages/sdk/src/define-skill-read-tool.ts:155` |
 | `duplicate_tool_name` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:201` |
 | `effective_tools_expected_options` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/effective-tools.ts:102` +1 |
 | `embedding_dimension_mismatch` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:146` +1 |
@@ -79,10 +79,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:42` +1 |
 | `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:454` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:305` |
-| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:200` +2 |
-| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:191` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:299` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:406` |
+| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:252` +2 |
+| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:243` |
+| `hooks_unsupported_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:384` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:400` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:28` +1 |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |
@@ -99,7 +100,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `invalid_input` | domain | MemoryAdapterError | `packages/memory-honcho/src/adapter.ts:98` +9 |
 | `invalid_max_iterations` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/real-local-run.ts:71` |
 | `invalid_memory_backend` | domain | ConfigurationError | `packages/sdk/src/internal/memory/index-manager-dispatch.ts:24` +1 |
-| `invalid_memory_directory` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/memory-root.ts:124` |
+| `invalid_memory_directory` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/memory-root.ts:151` |
 | `invalid_memory_kind` | domain | ConfigurationError | `packages/sdk/src/internal/memory/storage/markdown-store.ts:206` |
 | `invalid_model_selection` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/model-selection.ts:21` |
 | `invalid_processor_options` | domain | ConfigurationError | `packages/sdk/src/built-in-processors.ts:86` |
@@ -136,7 +137,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `migration_destination_exists` | domain | ConfigurationError | `packages/sdk/src/internal/memory/migrate-sqlite-to-lance.ts:159` +1 |
 | `missing_api_key` | domain | AuthenticationError, ConfigurationError | `packages/sdk/src/internal/agent/helpers.ts:215` +2 |
 | `missing_credential` | domain | AuthenticationError | `packages/sdk/src/internal/providers/builtin/openai-chatgpt.ts:72` |
-| `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:66` |
+| `missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:88` |
 | `missing_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:35` |
 | `model_unavailable` | domain | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:75` +1 |
 | `network` | domain | MemoryAdapterError, buildErrorMetadata | `packages/memory-honcho/src/adapter.ts:258` +5 |
@@ -161,6 +162,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `parse_failed` | domain | — | `packages/sdk/src/errors.ts:653` |
 | `path_traversal` | domain | — | `packages/sdk/src/internal/security/path-guard.ts:37` |
 | `permission_enforcement_unavailable` | domain | ConfigurationError | `packages/acp/src/permission-plugin.ts:138` +1 |
+| `permission_rule_invalid` | domain | ConfigurationError | `packages/sdk/src/permission-rules.ts:82` +2 |
 | `personality_empty_body` | domain | ConfigurationError | `packages/sdk/src/internal/personality/registry.ts:117` |
 | `personality_not_found` | domain | ConfigurationError | `packages/sdk/src/internal/personality/switch.ts:60` |
 | `personality_reserved_name` | domain | ConfigurationError | `packages/sdk/src/internal/personality/registry.ts:110` |
@@ -184,7 +186,7 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `sandbox_derived_helper_failed` | domain | ConfigurationError | `packages/sdk/src/sandbox/types.ts:185` +1 |
 | `sandbox_not_available` | domain | SandboxNotAvailableError | `packages/sdk/src/sandbox/types.ts:92` +1 |
 | `sandbox_security` | domain | SandboxSecurityError | `packages/sdk/src/sandbox/types.ts:73` +1 |
-| `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:77` +3 |
+| `schema_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/skill-frontmatter.ts:99` +5 |
 | `server_error` | domain | buildErrorMetadata | `packages/sdk/src/internal/error-mappers/ollama.ts:92` +1 |
 | `session_busy` | domain | — | `packages/sdk/src/internal/persistence/session-writer.ts:56` +1 |
 | `sql_injection_blocked` | domain | ConfigurationError | `packages/sdk/src/internal/memory/lance-index.ts:256` +3 |
@@ -196,13 +198,13 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `ssrf_blocked` | domain | — | `packages/sdk-tools/src/internal/network-guard.ts:23` |
 | `stream_idle_timeout` | domain | NetworkError | `packages/sdk/src/internal/llm/sse.ts:95` |
 | `stream_truncated` | domain | NetworkError | `packages/sdk/src/internal/llm/anthropic.ts:184` +1 |
-| `subagent_mcp_unsupported_local` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:173` |
+| `subagent_mcp_unsupported_local` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:207` |
 | `subagent_missing_description` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:142` |
-| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:250` |
+| `subagent_missing_frontmatter` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:284` |
 | `subagent_missing_prompt` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/validation/validate-agent-options.ts:147` |
-| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:193` |
-| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:213` |
-| `subagent_unknown_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:158` |
+| `subagent_reasoning_effort_without_model` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:227` |
+| `subagent_sandbox_not_boolean` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:247` |
+| `subagent_unknown_field` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/skills/subagents-loader.ts:192` |
 | `subagent_unknown_setting_source` | domain | ConfigurationError | `packages/sdk/src/subagents-loader.ts:96` |
 | `subscribe_baseUrl_missing` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:77` |
 | `subscribe_name_invalid` | domain | SubscriptionError | `packages/sdk/src/subscription/theokit-subscribe.ts:72` |

package/docs/harness-capability-map.md

@@ -4,7 +4,7 @@ Every public symbol the TheoKit workspace publishes, and the exact specifier to
 
 A symbol listed under two specifiers is reachable from both, but that does NOT make the two interchangeable: a class emitted separately into a subpath entry is a distinct nominal type from the one in the root bundle, so passing one where the other is expected fails on a private field. When a symbol appears twice, import it and everything it is passed to from the SAME specifier.
 
-1204 export(s) across 46 entry point(s).
+1212 export(s) across 46 entry point(s).
 
 ## `@theokit/acp`
 
@@ -200,6 +200,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `InteractionUpdate` | type | Lowest-level raw update from a run.  |
 | `InvalidateCacheOptions` | interface | Options for {@link SDKAgent.invalidateCache } . |
 | `InvalidTaskIdError` | class | Thrown when a user-supplied task ID violates the grammar `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter prefix (`wf-` / `b-` / `cron-`, EC-5). |
+| `isInside` | function | Whether `child` is inside `parent`.  |
 | `isTransientError` | function | Is this error transient (worth retrying)?  |
 | `isValidTaskId` | function | Validates a task ID against the public grammar + reserved prefixes.  |
 | `JobQueue` | class | An in-process queue of background jobs with status tracking, cancellation, and an optional concurrency bound.  |
@@ -218,6 +219,8 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `LiveSessionReason` | type | Why the destruction was refused. |
 | `loadProjectEnv` | function | Read the project's `.env` into `env`, then restore every {@link SOVEREIGN_ENV_KEYS } entry to the value it had BEFORE the load — including restoring it to absent.  |
 | `LocalOptions` | interface | Local agent configuration.  |
+| `ManagedSettings` | interface | What an operator may impose.  |
+| `managedSettingsPathFor` | function | Where the platform keeps its managed settings.  |
 | `McpAuthConfig` | interface | OAuth-style auth bundle for HTTP/SSE MCP servers. |
 | `McpHttpServerConfig` | type | HTTP or SSE MCP server. |
 | `McpOAuthConfig` | interface | OAuth 2.1 PKCE flow descriptor.  |
@@ -257,10 +260,13 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `normalizeUsage` | function | Convert a provider's raw `usage` object into the SDK's canonical `TokenUsage`.  |
 | `OTelSpan` | interface | The subset of the OpenTelemetry `Span` API this SDK calls.  |
 | `OutputProcessorContext` | interface | Context passed to {@link Processor.processOutput } . |
+| `parsePermissionRules` | function | Parse a rule set into engine rules, DENY first.  |
 | `PartialToolCallUpdate` | interface | Tool call arguments streaming in incrementally. |
 | `PermissionAction` | type | `PermissionEngine` — first-match permission rules for tool invocations.  |
 | `PermissionEngine` | class | Ordered first-match permission rules for tool invocations — the policy object you hand to `PermissionPlugin.create()` to have it enforced.  |
 | `PermissionEngineOptions` | interface | Options for {@link PermissionEngine } . |
+| `PermissionFloorContext` | interface | Where the floor is anchored.  |
+| `permissionFloorReason` | function | Why this call may not be approved, or `undefined` when the floor has no objection.  |
 | `PermissionGate` | type | SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape).  |
 | `PermissionGateContext` | interface | SE1 — context passed to the {@link PermissionGate } .  |
 | `PermissionGateDecision` | type | SE1 — the resolution of an `"ask"` verdict by the host gate.  |
@@ -268,6 +274,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `PermissionPlugin` | class | SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015). |
 | `PermissionPluginOptions` | interface | Options for {@link createPermissionPlugin } . |
 | `PermissionRule` | interface | One entry in a {@link PermissionEngine } 's ordered rule list.  |
+| `PermissionRuleSet` | interface | A policy as an operator writes it: three lists of rule strings. |
 | `PersonalityPreset` | interface | Resolved personality preset surfaced via {@link SDKAgent.usePersonality } (Hermes #26, ADRs D160-D169).  |
 | `planReaping` | function | Sort artifacts into keep, reap, and undetermined — and delete nothing.  |
 | `Plugin` | type | SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015).  |
@@ -293,6 +300,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `ProviderTransform` | interface | M41 — the one OPTIONAL behavior seam on a provider profile.  |
 | `ProviderTransformContext` | interface | M41 (agent-builder provider framework) — the context a provider's `transform` receives per request.  |
 | `RateLimitError` | class | Too many requests or usage limits exceeded. |
+| `readManagedSettings` | function | Read the deployed policy, or `{}` when none is.  |
 | `readSessionMessages` | function | Read the messages a session already contains, for a surface that needs to re-render it.  |
 | `ReadSessionMessagesOptions` | interface | Which session to read, in the terms a host already has. |
 | `ReapableArtifact` | interface | One artifact the caller is considering deleting, described well enough to decide about.  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",

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

@@ -1 +0,0 @@
-{"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"]}