@theokit/sdk 5.4.0 → 5.6.0

package/dist/internal/memory/storage/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkVPK6PHIE_cjs = require('../../../chunk-VPK6PHIE.cjs');
+var chunk52FDUJSV_cjs = require('../../../chunk-52FDUJSV.cjs');
 var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
-var chunkNQTNSHSB_cjs = require('../../../chunk-NQTNSHSB.cjs');
+var chunkGFFBXSQT_cjs = require('../../../chunk-GFFBXSQT.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
-require('../../../chunk-LOHMT36V.cjs');
+require('../../../chunk-LD6HASA5.cjs');
 require('../../../chunk-7A6535RA.cjs');
 require('../../../chunk-SA6K24NB.cjs');
 require('../../../chunk-GZV6AVRL.cjs');
@@ -19,23 +19,23 @@ require('../../../chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "appendDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkVPK6PHIE_cjs.appendDiaryEntry; }
+  get: function () { return chunk52FDUJSV_cjs.appendDiaryEntry; }
 });
 Object.defineProperty(exports, "diaryPath", {
   enumerable: true,
-  get: function () { return chunkVPK6PHIE_cjs.diaryPath; }
+  get: function () { return chunk52FDUJSV_cjs.diaryPath; }
 });
 Object.defineProperty(exports, "entryHash", {
   enumerable: true,
-  get: function () { return chunkVPK6PHIE_cjs.entryHash; }
+  get: function () { return chunk52FDUJSV_cjs.entryHash; }
 });
 Object.defineProperty(exports, "readAllSqliteFacts", {
   enumerable: true,
-  get: function () { return chunkVPK6PHIE_cjs.readAllSqliteFacts; }
+  get: function () { return chunk52FDUJSV_cjs.readAllSqliteFacts; }
 });
 Object.defineProperty(exports, "renderDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkVPK6PHIE_cjs.renderDiaryEntry; }
+  get: function () { return chunk52FDUJSV_cjs.renderDiaryEntry; }
 });
 Object.defineProperty(exports, "persistActiveMemoryTranscript", {
   enumerable: true,
@@ -43,99 +43,99 @@ Object.defineProperty(exports, "persistActiveMemoryTranscript", {
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.MEMORY_INDEX_MAX_BYTES; }
+  get: function () { return chunkGFFBXSQT_cjs.MEMORY_INDEX_MAX_BYTES; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.MEMORY_INDEX_MAX_LINES; }
+  get: function () { return chunkGFFBXSQT_cjs.MEMORY_INDEX_MAX_LINES; }
 });
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.appendFact; }
+  get: function () { return chunkGFFBXSQT_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.appendFactToMarkdown; }
+  get: function () { return chunkGFFBXSQT_cjs.appendFactToMarkdown; }
 });
 Object.defineProperty(exports, "asMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.asMemoryRoot; }
+  get: function () { return chunkGFFBXSQT_cjs.asMemoryRoot; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkGFFBXSQT_cjs.claudeProjectMemoryDir; }
 });
 Object.defineProperty(exports, "collectMarkdownFiles", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.collectMarkdownFiles; }
+  get: function () { return chunkGFFBXSQT_cjs.collectMarkdownFiles; }
 });
 Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.defaultIndexPath; }
+  get: function () { return chunkGFFBXSQT_cjs.defaultIndexPath; }
 });
 Object.defineProperty(exports, "discoverSessionFiles", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.discoverSessionFiles; }
+  get: function () { return chunkGFFBXSQT_cjs.discoverSessionFiles; }
 });
 Object.defineProperty(exports, "discoverWikiFiles", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.discoverWikiFiles; }
+  get: function () { return chunkGFFBXSQT_cjs.discoverWikiFiles; }
 });
 Object.defineProperty(exports, "indexBudgetWarning", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.indexBudgetWarning; }
+  get: function () { return chunkGFFBXSQT_cjs.indexBudgetWarning; }
 });
 Object.defineProperty(exports, "lanceStoragePath", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.lanceStoragePath; }
+  get: function () { return chunkGFFBXSQT_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryIndexRoot", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.memoryIndexRoot; }
+  get: function () { return chunkGFFBXSQT_cjs.memoryIndexRoot; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.memoryMdPath; }
+  get: function () { return chunkGFFBXSQT_cjs.memoryMdPath; }
 });
 Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.memoryReadRoots; }
+  get: function () { return chunkGFFBXSQT_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.notesDir; }
+  get: function () { return chunkGFFBXSQT_cjs.notesDir; }
 });
 Object.defineProperty(exports, "projectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.projectMemoryDir; }
+  get: function () { return chunkGFFBXSQT_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.readFacts; }
+  get: function () { return chunkGFFBXSQT_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkGFFBXSQT_cjs.readFactsFromMarkdown; }
 });
 Object.defineProperty(exports, "resolveMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.resolveMemoryRoot; }
+  get: function () { return chunkGFFBXSQT_cjs.resolveMemoryRoot; }
 });
 Object.defineProperty(exports, "sessionSummaryPath", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.sessionSummaryPath; }
+  get: function () { return chunkGFFBXSQT_cjs.sessionSummaryPath; }
 });
 Object.defineProperty(exports, "sessionsDir", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.sessionsDir; }
+  get: function () { return chunkGFFBXSQT_cjs.sessionsDir; }
 });
 Object.defineProperty(exports, "wikiDir", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.wikiDir; }
+  get: function () { return chunkGFFBXSQT_cjs.wikiDir; }
 });
 Object.defineProperty(exports, "writeSessionSummary", {
   enumerable: true,
-  get: function () { return chunkNQTNSHSB_cjs.writeSessionSummary; }
+  get: function () { return chunkGFFBXSQT_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.js

@@ -1,9 +1,9 @@
-export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-WS5ULCL4.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-STGSMJMJ.js';
 export { persistActiveMemoryTranscript } from '../../../chunk-OR6XIWLB.js';
-export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-SADXXGWU.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryIndexRoot, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-BZ3YMAMP.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
-import '../../../chunk-2XRAWOZZ.js';
+import '../../../chunk-5NELQ6LB.js';
 import '../../../chunk-EH6XD3FY.js';
 import '../../../chunk-UKMBRMGT.js';
 import '../../../chunk-JOFVLOFY.js';

package/dist/internal/memory/storage/memory-root.d.cts

@@ -50,6 +50,33 @@ export declare function projectMemoryDir(cwd: string): MemoryRoot;
  * TRANSCRIPTS ARE THE TRAP, and the reason this went unnoticed: the CLI keys THOSE by `cwd`, and
  * `encodeProjectDir` is right for them. One encoder for two axes made the two indistinguishable in
  * the code. The encoder is still shared — the path it is given is not.
+ *
+ * ## What is READ here and what is not IMPLEMENTED (B-054)
+ *
+ * This reads the directory the Claude Code CLI writes its auto-memory into. It does not implement
+ * the CLI's auto-memory BEHAVIOUR: `autoMemoryEnabled`, `autoMemoryDirectory`,
+ * `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, `cleanupPeriodDays` and the documented 200-line / 25 KB read
+ * cap have no counterpart — measured 0 files across this package and `@theokit/agents`.
+ *
+ * Interop in one direction is the decision, not an oversight: a memory the CLI recorded stays
+ * visible, and this runtime does not start writing into a store another product owns the lifecycle
+ * of. A `cleanupPeriodDays` implemented here would delete files the CLI expects to find.
+ *
+ * `CLAUDE_CONFIG_DIR` is honoured HERE and nowhere else, and that is the whole of its scope in this
+ * runtime: it names the CLI's home so this reader finds the right directory. It does not relocate a
+ * user-level configuration root of this product's own, because there is none to relocate — the
+ * config roots resolved elsewhere are PROJECT-relative.
+ *
+ * ## The filename collision, stated at one of its two ends
+ *
+ * `MEMORY.md` names two different contracts. The CLI's is a plain file under the directory above,
+ * capped and swept by the CLI. This SDK's is the durable-memory subsystem — a SQLite+FTS5 store
+ * under `.theokit/memory/` with `memory_search` / `memory_get` tools, no index cap, and a different
+ * directory entirely.
+ *
+ * Same filename, different directory, different semantics. A parity checklist that greps for
+ * `MEMORY.md` finds one and concludes the other exists — the third name in this backlog to collide
+ * that way, and the reason the statement lives at both ends rather than in a changelog.
  */
 export declare function claudeProjectMemoryDir(cwd: string): MemoryRoot;
 /**

package/dist/internal/memory/storage/memory-root.d.ts

@@ -50,6 +50,33 @@ export declare function projectMemoryDir(cwd: string): MemoryRoot;
  * TRANSCRIPTS ARE THE TRAP, and the reason this went unnoticed: the CLI keys THOSE by `cwd`, and
  * `encodeProjectDir` is right for them. One encoder for two axes made the two indistinguishable in
  * the code. The encoder is still shared — the path it is given is not.
+ *
+ * ## What is READ here and what is not IMPLEMENTED (B-054)
+ *
+ * This reads the directory the Claude Code CLI writes its auto-memory into. It does not implement
+ * the CLI's auto-memory BEHAVIOUR: `autoMemoryEnabled`, `autoMemoryDirectory`,
+ * `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, `cleanupPeriodDays` and the documented 200-line / 25 KB read
+ * cap have no counterpart — measured 0 files across this package and `@theokit/agents`.
+ *
+ * Interop in one direction is the decision, not an oversight: a memory the CLI recorded stays
+ * visible, and this runtime does not start writing into a store another product owns the lifecycle
+ * of. A `cleanupPeriodDays` implemented here would delete files the CLI expects to find.
+ *
+ * `CLAUDE_CONFIG_DIR` is honoured HERE and nowhere else, and that is the whole of its scope in this
+ * runtime: it names the CLI's home so this reader finds the right directory. It does not relocate a
+ * user-level configuration root of this product's own, because there is none to relocate — the
+ * config roots resolved elsewhere are PROJECT-relative.
+ *
+ * ## The filename collision, stated at one of its two ends
+ *
+ * `MEMORY.md` names two different contracts. The CLI's is a plain file under the directory above,
+ * capped and swept by the CLI. This SDK's is the durable-memory subsystem — a SQLite+FTS5 store
+ * under `.theokit/memory/` with `memory_search` / `memory_get` tools, no index cap, and a different
+ * directory entirely.
+ *
+ * Same filename, different directory, different semantics. A parity checklist that greps for
+ * `MEMORY.md` finds one and concludes the other exists — the third name in this backlog to collide
+ * that way, and the reason the statement lives at both ends rather than in a changelog.
  */
 export declare function claudeProjectMemoryDir(cwd: string): MemoryRoot;
 /**

package/dist/internal/persistence/index.cjs

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

package/dist/internal/persistence/index.js

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

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

@@ -8,14 +8,27 @@ export interface ConfigSourceAdapter {
     /** The project-relative directory the dialect keeps its configuration in. */
     readonly dirName: string;
     /**
-     * Variables the dialect's own runtime defines for commands it executes.
+     * Variables the dialect's own runtime defines for commands it executes, under the dialect's own
+     * documented spellings.
      *
-     * Empty for the native source: a `.theokit/` hook is written against THIS runtime and inherits it
-     * already. Non-empty is what makes a foreign command runnable rather than silently broken.
+     * Every dialect gets a project-directory variable, because none of them can locate a
+     * project-relative script without one — the inherited environment says where the PROCESS is, and
+     * a hook that has to depend on the process cwd is the dependency #522 removed for the foreign
+     * side. Fixing one dialect and leaving the other different was the half-fix.
+     *
+     * The SPELLINGS differ on purpose: a ported script reaches for the name its own docs use, and a
+     * native one for this runtime's.
      */
     runtimeEnv(cwd: string): Record<string, string>;
 }
-/** The native source. Always read, never opted into, always first for precedence. */
+/**
+ * The native source. Always read, never opted into, always first for precedence.
+ *
+ * `THEOKIT_PROJECT_DIR` is the native counterpart of `CLAUDE_PROJECT_DIR` below. This used to be
+ * `{}`, on the reasoning that a `.theokit/` hook "is written against THIS runtime and inherits it
+ * already" — true of the runtime's BEHAVIOUR and not of a project PATH. Nothing in the inherited
+ * environment says where the project is, so a native hook had to depend on the process cwd.
+ */
 export declare const NATIVE_SOURCE: ConfigSourceAdapter;
 /**
  * Claude Code.

package/dist/internal/runtime/compat/managed-settings.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What an operator may impose. One key today, and the shape is the point: each addition is a control
+ * that already exists somewhere below and is being lifted into a tier the project cannot reach.
+ *
+ * Deliberately NOT a passthrough of arbitrary keys. A policy file whose unknown keys were carried
+ * along would let an organisation believe it had imposed something this runtime never reads — the
+ * exact belief-in-an-absent-protection this tier exists to remove.
+ */
+export interface ManagedSettings {
+    /**
+     * Refuse to execute the `` !`command` `` form in a skill or command body.
+     *
+     * A skill is a markdown file a repository can carry, and its body can run shell at expansion time.
+     * Without this the only way to decline was to stop reading skills entirely.
+     */
+    disableSkillShellExecution?: boolean;
+    /**
+     * The permission posture the operator imposes on every run.
+     *
+     * `plan` is the one this exists for: an explore-only posture where edits are structurally refused.
+     * A `createPlanModeTool` already existed and it is a tool the MODEL may call — the difference is
+     * who decides. A never-prompt posture (`bypass`) is the other end, for a locked-down CI run where
+     * there is nobody to ask.
+     *
+     * It does NOT reach the standing-grant gate. `bypass` allows what the RULES would have asked
+     * about; a grant an operator recorded is not the run's to clear.
+     */
+    permissionMode?: "default" | "plan" | "acceptEdits" | "bypass";
+    /**
+     * The permission policy, as rule strings an operator writes and reviews.
+     *
+     * `{ "permissions": { "deny": ["Read(path:./.env)"] } }` — the spec's own paste-ready
+     * secret-exclusion example, which could not be expressed at all while every policy was a compiled
+     * predicate. Parsed by `parsePermissionRules` into the rules `PermissionEngine` already evaluates;
+     * the engine is unchanged and keeps its fail-closed default and its immune-to-un-deny explicit
+     * deny.
+     */
+    permissions?: {
+        readonly deny?: readonly string[];
+        readonly ask?: readonly string[];
+        readonly allow?: readonly string[];
+    };
+    /**
+     * Refuse to run ANY hook, whatever the project declared.
+     *
+     * The first control lifted, because it is the one whose absence is hardest to notice: a hook that
+     * does not run looks identical to a hook that ran and approved.
+     */
+    disableAllHooks?: boolean;
+}
+/**
+ * Where the platform keeps its managed settings.
+ *
+ * `root` exists so the precedence rule is testable: the real directories are platform-owned and a
+ * test must not write to `/etc`. Hard-coding the path inside the reader would make the thing that
+ * actually matters — that a project cannot override this file — unreachable by any test not running
+ * as root.
+ *
+ * The paths are Claude Code's own, because the file is Claude Code's format: an organisation that
+ * already deployed one should not have to deploy a second copy under a different name to get the
+ * same policy honoured here.
+ */
+export declare function managedSettingsPathFor(root?: string): string;
+/**
+ * Read the deployed policy, or `{}` when none is.
+ *
+ * Absent is the ordinary case and not an error — most machines have no operator tier, and a reader
+ * that failed without one would make the feature a prerequisite for running at all.
+ *
+ * A file that EXISTS and cannot be read is different, and says so — through `diagFailure`, not
+ * `diag`. `diag` returns immediately when no sink is installed, and most consumers never install
+ * one: an organisation that deployed a policy with a typo in it would get complete silence, which is
+ * the same defect this repository just fixed for dropped hook events. A policy channel that is
+ * silent by default reports nothing about the one thing the tier exists to make certain. An organisation that deployed a
+ * policy and got silence would believe it applied; that belief is what this tier removes.
+ *
+ * SYNC for the same reason `readCompatConfigFile` is: the caller resolves this before any submanager
+ * exists to await a promise, and a once-per-agent read of one small file is the same class of work.
+ */
+export declare function readManagedSettings(root?: string): ManagedSettings;

package/dist/internal/runtime/context/context-discovery-runner.d.ts

@@ -35,6 +35,20 @@ export interface DiscoveryRunnerOptions {
     readonly maxBytesPerFile: number;
     /** Optional override of the default registry. */
     readonly specs?: ReadonlyArray<DiscoverySpec>;
+    /**
+     * The foreign dialects the consumer granted the `context` surface to — the output of
+     * `adaptersForSurface(compatSources, "context")`, mapped to `.kind`.
+     *
+     * Left unset, every spec runs, which is what every caller before usetheokit/theokit-sdk#652 got.
+     * Set, it filters specs carrying a {@link DiscoverySpec.dialect} the list does not name — so an
+     * empty array is a real value meaning "no foreign dialect granted", NOT the same as absent.
+     *
+     * That distinction is the whole option. `resolveCompatSources` returns `[]` for a consumer who
+     * declared nothing, and collapsing `[]` into `undefined` here would restore the defect: a
+     * repository's `.claude/rules/*.md` entering the system prompt of a consumer who never asked for
+     * that dialect.
+     */
+    readonly declaredCompatKinds?: ReadonlyArray<string>;
     /** Cursor MDC: file paths the LLM has touched this turn (EC-I: empty at send-time). */
     readonly touchedFiles?: ReadonlyArray<string>;
     /** When true, skip `theokit-context` spec — caller already handles the legacy path. */

package/dist/internal/runtime/context/context-discovery.d.ts

@@ -58,6 +58,43 @@ export interface DiscoverySpec {
     readonly parser: DiscoveryParser;
     /** Whether to follow `@path` import directives (CLAUDE.md / GEMINI.md). */
     readonly followImports: boolean;
+    /**
+     * The `CompatSource` kind whose grant gates this file — the name a consumer writes in
+     * `local.compatSources` to receive it.
+     *
+     * Absent means UNGATED, and that covers two different situations which the field deliberately does
+     * not distinguish, because the gate treats them identically:
+     *
+     * 1. **Native.** theokit's own roots. Declaring theokit is what running theokit means, so there is
+     *    no separate grant to ask for.
+     * 2. **A repo-root instruction file.** `AGENTS.md`, `GEMINI.md`, `CLAUDE.md` and
+     *    `.cursor/rules/*.mdc` are every bit as foreign as `.claude/` is, and every one of them puts
+     *    a cloned repository's prose into the system prompt. They are ungated anyway, for a reason
+     *    that is a limit rather than a judgement: `adaptersFor` registers ONE foreign adapter,
+     *    `claude-code`, so `compatSources` has no spelling that admits `agents`, `gemini` or
+     *    `cursor`. Labelling them would gate them on a grant nobody can write, making three formats
+     *    permanently unreachable — a silent loss of capability with no way to restore it, which is a
+     *    worse defect than the one being fixed and the exact shape this codebase already paid for in
+     *    usetheokit/theokit-sdk#524.
+     *
+     *    `CLAUDE.md` is ungated for the adjacent reason, and this one IS a judgement: the grant gates
+     *    the foreign ROOT — the `.claude/` directory whose hooks, skills, subagents and plugins
+     *    already require it — and `CLAUDE.md` does not live there. It sits at the repository root
+     *    beside the other three, is widely used as a generic agent-instructions file by projects that
+     *    have no `.claude/` at all, and gating it would take it from them.
+     *
+     *    So this field closes the door the grant vocabulary already has a key for, and leaves three
+     *    named. Whether a repo-root instruction file should require an opt-in at all is a product
+     *    decision affecting every consumer, not a bug fix, and it is tracked separately — writing it
+     *    down is the point, because an undocumented gap reads as an oversight.
+     *
+     * Optional because this interface is `@public` and under semver: a caller passing its own array
+     * keeps working, and its specs read as ungated — the behaviour they had before this field existed.
+     *
+     * On the SPEC rather than as a condition at the call site, because the table MIXES dialects.
+     * Adding one is adding a row, not editing a branch somebody else has to find.
+     */
+    readonly dialect?: string;
 }
 /**
  * The context files theokit looks for out of the box, in the order they are concatenated.

package/dist/internal/runtime/context/context-manager.d.ts

@@ -1,8 +1,10 @@
 import type { ContextSettings, ContextSnapshot, SDKContextManager } from "../../../types/context.js";
+import { type CompatSourceDeclaration } from "../compat/foreign-config-sources.js";
 export declare class FileContextManager implements SDKContextManager {
     private readonly cwd;
     private readonly settings;
     private readonly settingSourcesIncludeProject;
+    private readonly compatSources?;
     private state;
     /**
      * The in-scope file set used by the most recent `refresh`. Tracked so
@@ -11,7 +13,25 @@ export declare class FileContextManager implements SDKContextManager {
      * snapshot untouched, at zero per-send cost.
      */
     private lastScope;
-    constructor(cwd: string, settings: ContextSettings, settingSourcesIncludeProject: boolean);
+    /**
+     * @param compatSources - What the consumer declared in `local.compatSources` (or
+     * `.theokit/config.json`), as `resolveCompatSources` resolved it. `undefined` means the caller
+     * did not thread the declaration through at all and every dialect runs — the pre-#652 behaviour,
+     * kept so an internal caller constructing this directly does not silently lose content. An empty
+     * ARRAY is different and is the fix: it means the consumer declared no foreign dialect, so
+     * `.claude/rules/*.md` does not reach the prompt.
+     */
+    constructor(cwd: string, settings: ContextSettings, settingSourcesIncludeProject: boolean, compatSources?: readonly CompatSourceDeclaration[] | undefined);
+    /**
+     * The dialect kinds granted the `context` surface, or `undefined` when nothing was declared to
+     * this instance.
+     *
+     * Routed through `adaptersForSurface` rather than reading `.kind` off the declarations, so the
+     * three fail-closed rules #524 established govern this surface identically to the other four: a
+     * bare string admits everything, an object with no `import` admits nothing, and an unrecognised
+     * surface name narrows rather than widens.
+     */
+    private grantedContextDialects;
     initialize(): Promise<void>;
     /**
      * Re-run discovery for a specific per-send in-scope file set (T3). Path-scoped

package/dist/internal/runtime/context/yaml-frontmatter.d.ts

@@ -7,13 +7,16 @@
  *   key: true             → true         (boolean)
  *   key: [a, b, c]        → ["a","b","c"](string[])
  *   key:                  → undefined    (caller's Zod default kicks in)
+ *     - a                 → ["a","b"]    (block list, when `- ` items follow a bare key)
+ *     - b
  *
  * Limitations (intentional — keep parser tiny, no dep):
  * - No nested objects (use flat keys like `providerId` not `provider.id`).
  * - No quoted strings — `match: "1"` becomes the literal 3-char string `"1"`.
- * - List values cannot contain a literal comma inside an element; the
- *   `tags: [a,b, c]` splitter is greedy on `,`. Use multi-line lists or
- *   reword if you need this.
+ * - Inline list values cannot contain a literal comma inside an element; the
+ *   `tags: [a,b, c]` splitter is greedy on `,`. Use the block form above or
+ *   reword if you need this — and note that the block form was, for a while,
+ *   what this line recommended and the parser could not read.
  *
  * @internal
  */

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

@@ -6,6 +6,16 @@ export interface HookCommand {
     matcher?: string;
     /** Optional timeout in ms; defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * #637 — the event key as the config file spelled it (`PreToolUse`), for the approval gate.
+     *
+     * Declared here AND in `hooks-source.ts`, because this interface has two independent copies —
+     * the same duplication `types/hooks.ts` records for `HookEvent`. Adding the field to one only
+     * would break at the assignment boundary in one direction and pass silently in the other.
+     * Consolidating the pair is a separate change with its own blast radius, per the decision
+     * recorded at the head of `types/hooks.ts`.
+     */
+    sourceEvent: string;
     /**
      * The config file this command was declared in.
      *
@@ -40,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,18 +8,63 @@
  *
  * 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;
     timeoutMs?: number;
+    /**
+     * #637 — the event key as written in the config file (`PreToolUse`), carried so the approval
+     * gate can report the vocabulary the consumer's stored fingerprint was taken against.
+     *
+     * REQUIRED, not optional: `parseClaudeCodeCommand` is the only producer of a `HookCommand` in
+     * this package, so every command has one. An optional field would hand every reader a fallback
+     * branch for a case that cannot occur — and if an in-memory producer is added later, required is
+     * what forces it to supply a value instead of inheriting a silent `undefined`.
+     */
+    sourceEvent: string;
     /**
      * The config file this command was declared in.
      *