@cortexkit/opencode-magic-context 0.33.1 → 0.34.1

package/src/agents/permissions.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "bun:test";
+import { DREAMER_CURATE_ALLOWED_TOOLS, DREAMER_DOCS_ALLOWED_TOOLS } from "./dreamer";
+import {
+    applyDisallowedTools,
+    buildAllowOnlyPermission,
+    HISTORIAN_ALLOWED_TOOLS,
+    SIDEKICK_ALLOWED_TOOLS,
+} from "./permissions";
+
+describe("buildAllowOnlyPermission", () => {
+    it("starts with wildcard deny so nothing is allowed by default", () => {
+        const perm = buildAllowOnlyPermission([]);
+        expect(perm["*"]).toBe("deny");
+    });
+
+    it("layers the allow-list on top of the wildcard deny", () => {
+        const perm = buildAllowOnlyPermission(["read", "ctx_search"]);
+        expect(perm["*"]).toBe("deny");
+        expect(perm.read).toBe("allow");
+        expect(perm.ctx_search).toBe("allow");
+    });
+
+    it("places named allows AFTER the wildcard deny so findLast-semantics make them win", () => {
+        // OpenCode's Permission.evaluate uses `findLast` over the ruleset
+        // built from this object's insertion order. If "*" appeared after a
+        // named tool, the deny would clobber it — guard against accidental
+        // regressions in the helper's ordering.
+        const perm = buildAllowOnlyPermission(["read"]);
+        const keys = Object.keys(perm);
+        const wildcardIdx = keys.indexOf("*");
+        const readIdx = keys.indexOf("read");
+        expect(wildcardIdx).toBeLessThan(readIdx);
+    });
+
+    it("never accidentally allows `task`, `bash`, or `edit` unless explicitly listed", () => {
+        // The whole point of this helper is preventing historian / dreamer /
+        // sidekick from inheriting the primary-agent surface. Lock that in.
+        const perm = buildAllowOnlyPermission(["read"]);
+        expect(perm.task).toBeUndefined();
+        expect(perm.bash).toBeUndefined();
+        expect(perm.edit).toBeUndefined();
+        expect(perm.webfetch).toBeUndefined();
+        expect(perm.websearch).toBeUndefined();
+        // The wildcard deny covers them via findLast — verified above.
+    });
+
+    it("returns an empty allow-list as just the wildcard deny", () => {
+        const perm = buildAllowOnlyPermission([]);
+        expect(Object.keys(perm)).toEqual(["*"]);
+    });
+});
+
+describe("HISTORIAN_ALLOWED_TOOLS", () => {
+    it("includes `read` (for state-file offload)", () => {
+        // Historian's primary tool need is reading the offloaded
+        // existing-state XML the runner writes to a temp file.
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("read");
+    });
+
+    it("includes `aft_outline`, `aft_zoom`, `aft_search` for token-efficient repo navigation/search", () => {
+        // Read-only AFT navigation + search tools let historian/compressor
+        // find or verify a symbol or skim file structure when writing
+        // accurate compartment summaries without dragging in whole files.
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("aft_outline");
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("aft_zoom");
+        expect(HISTORIAN_ALLOWED_TOOLS).toContain("aft_search");
+    });
+
+    it("does NOT include `task` (the bug we're fixing — preventing subagent fanout)", () => {
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("task");
+    });
+
+    it("does NOT include any edit / bash / web tools", () => {
+        for (const dangerous of ["bash", "edit", "write", "webfetch", "websearch"]) {
+            expect(HISTORIAN_ALLOWED_TOOLS).not.toContain(dangerous);
+        }
+    });
+
+    it("does NOT include `grep` or `glob` (historian summarizes, not explores)", () => {
+        // Historian's job is summarizing the input it was given.
+        // Repo-wide exploration belongs to dreamer / primary agents.
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("grep");
+        expect(HISTORIAN_ALLOWED_TOOLS).not.toContain("glob");
+    });
+});
+
+describe("applyDisallowedTools", () => {
+    it("returns the defaults unchanged when disallowed is empty", () => {
+        expect(applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, [])).toEqual([
+            ...HISTORIAN_ALLOWED_TOOLS,
+        ]);
+    });
+
+    it('removes all tools when "*" is in the disallowed list', () => {
+        expect(applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["*"])).toEqual([]);
+    });
+
+    it('removes all tools when "*" appears alongside other entries', () => {
+        expect(applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["*", "read"])).toEqual([]);
+    });
+
+    it("removes a single tool by name", () => {
+        const result = applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["read"]);
+        expect(result).not.toContain("read");
+        expect(result).toContain("aft_outline");
+        expect(result).toContain("aft_zoom");
+        expect(result).toContain("aft_search");
+    });
+
+    it("removes multiple tools by name", () => {
+        const result = applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["read", "aft_search"]);
+        expect(result).toEqual(["aft_outline", "aft_zoom"]);
+    });
+
+    it("silently ignores unknown tool names (defense-in-depth)", () => {
+        expect(applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["nonexistent"])).toEqual([
+            ...HISTORIAN_ALLOWED_TOOLS,
+        ]);
+    });
+
+    it("produces empty allow-list → buildAllowOnlyPermission yields wildcard deny only", () => {
+        const allowed = applyDisallowedTools(HISTORIAN_ALLOWED_TOOLS, ["*"]);
+        const perm = buildAllowOnlyPermission(allowed);
+        expect(perm).toEqual({ "*": "deny" });
+    });
+});
+
+describe("DREAMER_CURATE_ALLOWED_TOOLS (base dreamer = curate only)", () => {
+    it("is ctx_memory ONLY — curate edits the memory store and reads no code", () => {
+        // A separate verify task owns memory-vs-code correctness; curate is
+        // pure pool hygiene, so it has no read/grep/bash/write/edit surface.
+        expect([...DREAMER_CURATE_ALLOWED_TOOLS]).toEqual(["ctx_memory"]);
+    });
+
+    it("does NOT include any codebase / shell / file-write tool", () => {
+        for (const denied of [
+            "read",
+            "grep",
+            "glob",
+            "bash",
+            "write",
+            "edit",
+            "aft_search",
+            "ctx_search",
+            "ctx_note",
+            "task",
+        ]) {
+            expect(DREAMER_CURATE_ALLOWED_TOOLS).not.toContain(denied);
+        }
+    });
+});
+
+describe("DREAMER_DOCS_ALLOWED_TOOLS (maintain-docs)", () => {
+    it("includes read/grep/glob/bash + write/edit + aft for doc maintenance", () => {
+        for (const tool of [
+            "read",
+            "grep",
+            "glob",
+            "bash",
+            "write",
+            "edit",
+            "aft_outline",
+            "aft_zoom",
+            "aft_search",
+        ]) {
+            expect(DREAMER_DOCS_ALLOWED_TOOLS).toContain(tool);
+        }
+    });
+
+    it("does NOT include memory tools (it edits docs, not the memory store)", () => {
+        for (const denied of ["ctx_memory", "ctx_search", "ctx_note", "task"]) {
+            expect(DREAMER_DOCS_ALLOWED_TOOLS).not.toContain(denied);
+        }
+    });
+});
+
+describe("SIDEKICK_ALLOWED_TOOLS", () => {
+    it("includes ctx_search but not ctx_memory for retrieval", () => {
+        // Sidekick is the /ctx-aug memory retriever. It searches memories without
+        // receiving the mutation-capable ctx_memory tool.
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("ctx_search");
+        expect(SIDEKICK_ALLOWED_TOOLS).not.toContain("ctx_memory");
+    });
+
+    it("includes `aft_outline` and `aft_zoom` for lightweight structural context", () => {
+        // Sidekick can pull file outline / symbol body when the user's
+        // prompt references a specific file or symbol, without dragging
+        // in whole files.
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("aft_outline");
+        expect(SIDEKICK_ALLOWED_TOOLS).toContain("aft_zoom");
+    });
+
+    it("does NOT include `read` (use aft_outline/aft_zoom for navigation instead)", () => {
+        // Sidekick should pull symbol-scoped views, not arbitrary file
+        // contents. If it needs full source it can use aft_zoom on a
+        // specific symbol.
+        expect(SIDEKICK_ALLOWED_TOOLS).not.toContain("read");
+    });
+
+    it("does NOT include `task` or any edit / bash / web tool", () => {
+        for (const denied of ["task", "bash", "edit", "write", "webfetch", "websearch"]) {
+            expect(SIDEKICK_ALLOWED_TOOLS).not.toContain(denied);
+        }
+    });
+});
+
+describe("integration: full hidden-agent permission shape", () => {
+    it("historian permission object: `*` denied + read + aft_outline + aft_zoom + aft_search allowed", () => {
+        const perm = buildAllowOnlyPermission(HISTORIAN_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            read: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
+            aft_search: "allow",
+        });
+    });
+
+    it("base dreamer (curate) permission object: `*` denied + ctx_memory only", () => {
+        const perm = buildAllowOnlyPermission(DREAMER_CURATE_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            ctx_memory: "allow",
+        });
+    });
+
+    it("dreamer-docs permission object: `*` denied + repo-exploration + write/edit + aft_* (no memory)", () => {
+        const perm = buildAllowOnlyPermission(DREAMER_DOCS_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            read: "allow",
+            grep: "allow",
+            glob: "allow",
+            bash: "allow",
+            write: "allow",
+            edit: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
+            aft_search: "allow",
+        });
+    });
+
+    it("sidekick permission object: `*` denied + read-only retrieval/navigation allowed", () => {
+        const perm = buildAllowOnlyPermission(SIDEKICK_ALLOWED_TOOLS);
+        expect(perm).toEqual({
+            "*": "deny",
+            ctx_search: "allow",
+            aft_outline: "allow",
+            aft_zoom: "allow",
+        });
+    });
+});

package/src/agents/permissions.ts

@@ -0,0 +1,186 @@
+import { log } from "../shared/logger";
+
+/**
+ * Permission rulesets for Magic Context's hidden subagents.
+ *
+ * # Why this exists
+ *
+ * Hidden agents (`historian`, `historian-editor`, `dreamer`, `sidekick`) are
+ * registered with `mode: "subagent"` and `hidden: true`, but those flags
+ * only control visibility in the UI picker — they do NOT restrict which
+ * tools the spawned session can call. By default a registered subagent
+ * inherits the FULL primary-agent tool surface: `task`, `bash`, `edit`,
+ * `webfetch`, `websearch`, `read`, `grep`, `glob`, every MCP tool, etc.
+ *
+ * That default is wrong for our agents:
+ *   - Historian should be a pure XML-emitting summarizer. It must not
+ *     dispatch `task(subagent_type=explore)` to fan out, edit files,
+ *     run bash, or fetch the web — its job is to read offloaded state
+ *     files and emit `<compartment>` blocks.
+ *   - The `task` permission only gets auto-denied when an agent is
+ *     INVOKED via the parent's `task()` tool (see OpenCode's
+ *     `deriveSubagentSessionPermission`). Our hidden agents are spawned
+ *     directly via `client.session.prompt(...)` from the plugin
+ *     runtime, so that auto-deny never fires — they get the same
+ *     `task` permission as a primary `build` agent.
+ *
+ * # Design
+ *
+ * Each hidden agent's `permission` field starts with `{ "*": "deny" }`
+ * and adds explicit `allow` entries for ONLY the tool ids it needs.
+ * OpenCode's `Permission.fromConfig` converts this flat map into a
+ * `Rule[]` ruleset where later entries override earlier ones, so the
+ * named allows always win against the wildcard deny.
+ *
+ * This is the same pattern OpenCode's own `explore` subagent uses
+ * (see `packages/opencode/src/agent/agent.ts:179-201`).
+ *
+ * User-supplied agent overrides (`pluginConfig.historian.permission`,
+ * etc.) still merge on top via OpenCode's `Permission.merge`, so
+ * advanced users can extend the allow-list without us blocking them.
+ *
+ * # What each agent needs
+ *
+ *   - **historian / historian-editor / compressor**: `read` plus the
+ *     read-only AFT navigation/search tools `aft_outline`, `aft_zoom`,
+ *     and `aft_search`. The runner offloads large existing-state XML to
+ *     a temp file under `<project>/.opencode/magic-context/historian/`
+ *     and the prompt instructs the model to read that file. AFT
+ *     navigation is allowed so historian can find or verify a symbol or
+ *     file structure when writing accurate compartment summaries.
+ *
+ *   - **dreamer**: `read`, `grep`, `glob`, `bash`, `write`, `edit`, the
+ *     read-only AFT navigation/search tools `aft_outline`, `aft_zoom`,
+ *     `aft_search`, plus the Magic Context MCP tools `ctx_memory`,
+ *     `ctx_search`, `ctx_note`.
+ *     Dreamer task prompts in
+ *     `features/magic-context/dreamer/task-prompts.ts` explicitly tell
+ *     the model to grep schema files for defaults, read source to
+ *     confirm claims, run `git log` / `gh` / `curl` for verify and
+ *     smart-note evaluation, and use glob/find for directory
+ *     inventory. Live DB shows >100 bash invocations across all
+ *     dreamer task variants. `task` / `edit` / `write` / `webfetch` /
+ *     `websearch` remain denied — dreamer must not spawn subagents
+ *     or commit changes.
+ *
+ *   - **sidekick**: `ctx_search`, plus the read-only AFT
+ *     navigation tools `aft_outline` and `aft_zoom`. Sidekick's job
+ *     is augmenting user prompts via memory retrieval — see
+ *     `features/magic-context/sidekick/agent.ts`. AFT navigation lets
+ *     it pull symbol-scoped structural context for prompts that
+ *     reference a specific file or symbol.
+ */
+
+/**
+ * Build a `permission` map suitable for `AgentConfig.permission`. Starts
+ * with a wildcard deny, then layers in the named tool allows on top.
+ * OpenCode's `Permission.fromConfig` preserves insertion order and its
+ * `evaluate` uses `findLast`, so named allows defeat the wildcard deny.
+ *
+ * Returns `Record<string, "deny" | "allow">` which the SDK's
+ * `AgentConfig.permission` type accepts via its `[key: string]: unknown`
+ * index signature. The same pattern is used by OpenCode's built-in
+ * `explore`/`scout`/`general` agents and by Alfonso for its static
+ * agent profiles.
+ */
+export function buildAllowOnlyPermission(
+    allowedTools: readonly string[] | undefined,
+    agentLabel?: string,
+): Record<string, "deny" | "allow"> {
+    const permission: Record<string, "deny" | "allow"> = { "*": "deny" };
+    // Defensive: never throw on an undefined allow-list. A `for..of` on undefined
+    // crashes with "undefined is not an object (evaluating 'allowedTools')", and
+    // because this runs inside the plugin's `config` hook a throw there fails the
+    // ENTIRE plugin load — disabling the transform/compaction. Degrade to a
+    // deny-all agent instead of taking Magic Context down.
+    if (allowedTools === undefined) {
+        // Observed only inside OpenCode's plugin loader (never in an isolated
+        // import of the same dist), so capture WHICH agent + a stack to pin the
+        // real cause on the next natural restart. Should never fire.
+        log(
+            `[magic-context] buildAllowOnlyPermission: allow-list UNDEFINED for ${agentLabel ?? "unknown agent"} — registering deny-all (defensive)`,
+            { stackHead: new Error().stack?.split("\n").slice(1, 6).join("\n") },
+        );
+    }
+    for (const tool of allowedTools ?? []) {
+        permission[tool] = "allow";
+    }
+    return permission;
+}
+
+/**
+ * Tools the historian + historian-editor + compressor agents need.
+ *
+ * Historian runners offload large `<existing_state>` XML to disk and
+ * tell the model to `read` it before emitting the summary XML. The
+ * core need is `read`; we also allow the read-only AFT navigation
+ * tools `aft_outline` and `aft_zoom` so that if a historian/compressor
+ * ever needs to verify a symbol or skim a file's structure to write
+ * an accurate compartment summary, it can do so token-efficiently
+ * instead of pulling whole files via `read`.
+ *
+ * Still denied: bash, edit, write, task, grep/glob, webfetch/
+ * websearch. Historian's job is summarizing the input it was given,
+ * not exploring the repo.
+ */
+export const HISTORIAN_ALLOWED_TOOLS = ["read", "aft_outline", "aft_zoom", "aft_search"] as const;
+
+/**
+ * Subtract `disallowed` from the default historian allow-list. `"*"` removes
+ * all tools. Unknown tool names are silently ignored (the Zod enum in the
+ * config schema rejects them at parse time, so this is defense-in-depth).
+ */
+export function applyDisallowedTools(
+    defaults: readonly string[],
+    disallowed: readonly string[],
+): readonly string[] {
+    if (disallowed.includes("*")) return [];
+    return defaults.filter((t) => !disallowed.includes(t));
+}
+
+// The old kitchen-sink DREAMER_ALLOWED_TOOLS is retired: each dreamer task now
+// runs on its own scoped agent. Curate uses DREAMER_CURATE_ALLOWED_TOOLS
+// (ctx_memory only) and maintain-docs uses DREAMER_DOCS_ALLOWED_TOOLS (file
+// read/write/bash, no memory) — both in `dreamer.ts` alongside the other
+// per-task allow-lists (mapper/classifier/etc).
+
+/**
+ * Tools the sidekick agent needs. Sidekick is a read-only memory
+ * retriever for `/ctx-aug` — it queries the project's memory store
+ * through `ctx_search` only. Keep `ctx_memory` out of this list because
+ * its OpenCode tool definition is mutation-capable for primary agents.
+ *
+ * Also allow `aft_outline` and `aft_zoom` so sidekick can pull
+ * lightweight structural context about a file or symbol when the
+ * user's prompt references it directly — token-efficient navigation
+ * without dragging in whole files.
+ *
+ * Still denied: spawning subagents, edits, bash, web fetches.
+ */
+
+export const DREAMER_RETROSPECTIVE_ALLOWED_TOOLS = ["ctx_search"] as const;
+
+/**
+ * The refresh-primers code investigator: read + navigate + search the CURRENT
+ * source to answer a primer question. NO write/edit/bash (could corrupt user
+ * source) and NO ctx_memory/ctx_note (a ctx_memory mutation bumps the project
+ * memory epoch → busts m[0], breaking the primers cache-neutral contract).
+ */
+export const DREAMER_PRIMER_INVESTIGATOR_ALLOWED_TOOLS = [
+    "read",
+    "grep",
+    "glob",
+    "aft_outline",
+    "aft_zoom",
+    "aft_search",
+    "ctx_search",
+] as const;
+
+/**
+ * The smart-note compiler consumes untrusted note text and emits code that will
+ * later run in the QuickJS sandbox. It must not have ambient tools: all I/O is
+ * performed only when the compiled check runs through the host capability API.
+ */
+export const SMART_NOTE_COMPILER_ALLOWED_TOOLS = [] as const;
+
+export const SIDEKICK_ALLOWED_TOOLS = ["ctx_search", "aft_outline", "aft_zoom"] as const;

package/src/agents/sidekick.ts

@@ -0,0 +1 @@
+export const SIDEKICK_AGENT = "sidekick";

package/src/agents/smart-note-compiler.ts

@@ -0,0 +1 @@
+export const SMART_NOTE_COMPILER_AGENT = "smart-note-compiler";

package/src/config/agent-disable.ts

@@ -0,0 +1,106 @@
+/**
+ * User-facing spelling of the compaction-off config path, for log lines and
+ * command output. Built from fragments so the accessor-exclusivity guard
+ * (compaction-accessor-guard.test.ts) can keep rejecting literal
+ * `compaction.enabled` reads elsewhere — messages import this constant instead
+ * of inlining the path (the S5/S8 slices both re-derived it and tripped the
+ * guard; one constant ends that class).
+ */
+export const COMPACTION_ENABLED_PATH = `compaction${"."}enabled`;
+
+export function isDreamerRunnable(config: { dreamer?: { disable?: boolean } | null }): boolean {
+    return !!config.dreamer && config.dreamer.disable !== true;
+}
+
+export function isSidekickRunnable(config: { sidekick?: { disable?: boolean } | null }): boolean {
+    return !!config.sidekick && config.sidekick.disable !== true;
+}
+
+export function isHistorianRunnable(config: { historian?: { disable?: boolean } | null }): boolean {
+    return config.historian?.disable !== true;
+}
+
+/**
+ * The ONLY non-schema reader of the `compaction.enabled` config path.
+ * Resolves the compaction-off mode gate from a parsed Magic Context config.
+ * Lives beside the other subsystem toggles (isDreamerRunnable /
+ * isHistorianRunnable) and is IMPORTED — never re-derived — by every gate
+ * site (pi-plugin, cli, plugin boot, session hooks). Returns true (compaction
+ * ON / default behavior) when the block or field is absent.
+ */
+export function isCompactionEnabled(config: {
+    compaction?: { enabled?: boolean } | null;
+}): boolean {
+    return config.compaction?.enabled !== false;
+}
+
+function clonePlainObject(value: unknown): Record<string, unknown> | undefined {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return { ...(value as Record<string, unknown>) };
+}
+
+function migrateLegacyEnabledForAgent(args: {
+    patched: Record<string, unknown>;
+    agentName: "dreamer" | "sidekick" | "historian";
+    warnings: string[];
+}): void {
+    const agent = clonePlainObject(args.patched[args.agentName]);
+    if (!agent || !("enabled" in agent)) return;
+
+    const enabled = agent.enabled;
+    const disable = agent.disable;
+    delete agent.enabled;
+
+    if (args.agentName === "historian") {
+        args.warnings.push(
+            'Removed invalid "historian.enabled" in-memory (run doctor to persist).',
+        );
+        args.patched.historian = agent;
+        return;
+    }
+
+    if (args.agentName === "dreamer") {
+        if (disable !== true && enabled === false) {
+            agent.disable = true;
+            args.warnings.push(
+                'Migrated "dreamer.enabled=false" → "dreamer.disable=true" in-memory (run doctor to persist). This now also disables manual /ctx-dream; for manual-only remove disable and set schedule="".',
+            );
+        }
+        // enabled=true is a no-op alias for the new default (disable=false); strip silently.
+        args.patched.dreamer = agent;
+        return;
+    }
+
+    if (disable !== true && enabled === false) {
+        agent.disable = true;
+        args.warnings.push(
+            'Migrated "sidekick.enabled=false" → "sidekick.disable=true" in-memory (run doctor to persist).',
+        );
+    }
+    // enabled=true is a no-op alias for the new default; strip silently.
+    args.patched.sidekick = agent;
+}
+
+export function migrateLegacyAgentEnabledInMemory(
+    rawConfig: Record<string, unknown>,
+    warnings: string[],
+): Record<string, unknown> {
+    const shouldPatch = ["dreamer", "sidekick", "historian"].some((key) => {
+        const agent = rawConfig[key];
+        return (
+            typeof agent === "object" &&
+            agent !== null &&
+            !Array.isArray(agent) &&
+            "enabled" in agent
+        );
+    });
+    if (!shouldPatch) return rawConfig;
+
+    const patched: Record<string, unknown> = { ...rawConfig };
+    migrateLegacyEnabledForAgent({ patched, agentName: "dreamer", warnings });
+    migrateLegacyEnabledForAgent({ patched, agentName: "sidekick", warnings });
+    migrateLegacyEnabledForAgent({ patched, agentName: "historian", warnings });
+    return patched;
+}

package/src/config/compaction-accessor-guard.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+// isCompactionEnabled (config/agent-disable.ts) is the ONLY non-schema reader
+// of the `compaction.enabled` config path. Every gate site (pi-plugin, cli,
+// plugin boot, session hooks) must IMPORT it and never re-derive the value.
+// This guard asserts no other source file reads `compaction.enabled` or
+// `compaction?.enabled` directly. Precedent: the runMigrations import guard
+// (packages/cli/src/lib/migration-import-guard.test.ts).
+//
+// The schema file (config/schema/magic-context.ts) is the single producer of
+// the path and is excluded; the accessor file (config/agent-disable.ts) is the
+// single consumer and is excluded. The storage helpers read a DB column
+// (compaction_mode_record), not the config path, so they are not in scope.
+
+const REPOSITORY_ROOT = resolve(import.meta.dir, "../../../..");
+const SOURCE_ROOTS = ["packages/cli/src", "packages/plugin/src", "packages/pi-plugin/src"];
+
+const ALLOWED_READERS = new Set<string>([
+    // The accessor itself — the one permitted non-schema reader.
+    "packages/plugin/src/config/agent-disable.ts",
+    // The Zod schema that defines the path.
+    "packages/plugin/src/config/schema/magic-context.ts",
+    // project-security.ts references the path NAME in a warning string when it
+    // strips the project-tier field; it never reads the parsed config path.
+    // The strip operates on a raw Record<string, unknown> by key name, not on
+    // a parsed MagicContextConfig.
+    "packages/plugin/src/config/project-security.ts",
+]);
+
+function sourceFiles(directory: string): string[] {
+    const result: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            result.push(...sourceFiles(path));
+        } else if (/\.tsx?$/.test(entry.name) && !/\.test\.tsx?$/.test(entry.name)) {
+            result.push(path);
+        }
+    }
+    return result;
+}
+
+// Matches direct reads of the config path: `compaction.enabled` or
+// `compaction?.enabled` as a property access (not a string literal). This is a
+// structural grep, not a full AST parse — it is deliberately conservative and
+// may surface false positives, which are then allow-listed only after review.
+// It does NOT match the DB column `compaction_mode_record`, the accessor name
+// `isCompactionEnabled`, or the schema's own `.object({ enabled: ... })`.
+const COMPACTION_ENABLED_READ = /\bcompaction\??\s*\.\s*enabled\b(?!_)/;
+
+describe("compaction.enabled accessor exclusivity (issue #266)", () => {
+    it("no non-schema source file reads compaction.enabled directly", () => {
+        const offenders: string[] = [];
+        for (const root of SOURCE_ROOTS) {
+            for (const path of sourceFiles(resolve(REPOSITORY_ROOT, root))) {
+                const relativePath = relative(REPOSITORY_ROOT, path);
+                if (ALLOWED_READERS.has(relativePath)) continue;
+                const source = readFileSync(path, "utf8");
+                if (COMPACTION_ENABLED_READ.test(source)) {
+                    offenders.push(relativePath);
+                }
+            }
+        }
+        expect(offenders).toEqual([]);
+    });
+
+    it("isCompactionEnabled is exported from the accessor module", async () => {
+        const mod = await import("../config/agent-disable");
+        expect(typeof mod.isCompactionEnabled).toBe("function");
+    });
+
+    it("isCompactionEnabled resolves default-on for absent block and explicit true, off for false", async () => {
+        const { isCompactionEnabled } = await import("../config/agent-disable");
+        expect(isCompactionEnabled({})).toBe(true);
+        expect(isCompactionEnabled({ compaction: {} })).toBe(true);
+        expect(isCompactionEnabled({ compaction: { enabled: true } })).toBe(true);
+        expect(isCompactionEnabled({ compaction: { enabled: false } })).toBe(false);
+        expect(isCompactionEnabled({ compaction: null })).toBe(true);
+    });
+});