@cortexkit/opencode-magic-context 0.34.2 → 0.35.1

package/src/agents/magic-context-prompt.test.ts

@@ -290,3 +290,147 @@ describe("buildMagicContextSection — compaction-off guidance variant (#266 S4)
         expect(reduce).toContain("tagged with §N§ identifiers");
     });
 });
+
+describe("buildMagicContextSection — prompt-surface composition", () => {
+    it("keeps full bytes stable while serving compressed light guidance", () => {
+        const implicit = buildMagicContextSection(
+            null,
+            20,
+            true,
+            true,
+            true,
+            true,
+            false,
+            "tr",
+            true,
+        );
+        const explicitFull = buildMagicContextSection(
+            null,
+            20,
+            true,
+            true,
+            true,
+            true,
+            false,
+            "tr",
+            true,
+            "full",
+        );
+        const light = buildMagicContextSection(
+            null,
+            20,
+            true,
+            true,
+            true,
+            true,
+            false,
+            "tr",
+            true,
+            "light",
+        );
+
+        expect(explicitFull).toBe(implicit);
+        expect(light).not.toBe(implicit);
+        expect(light).toContain("In primary sessions with ctx_reduce");
+        expect(light).toContain("NEVER narrate ctx_reduce");
+        expect(light).toContain("DO NOT mimic this style");
+        expect(light).toContain("Keep code, identifiers, file paths");
+        expect(light).not.toContain("### Reduction Triggers");
+    });
+
+    it("keeps feature-gated and shared fragments orthogonal to light", () => {
+        const light = (options: {
+            reduce?: boolean;
+            dreamer?: boolean;
+            temporal?: boolean;
+            caveman?: boolean;
+            subagent?: boolean;
+            language?: string;
+            memory?: boolean;
+        }) =>
+            buildMagicContextSection(
+                null,
+                20,
+                options.reduce ?? true,
+                options.dreamer ?? false,
+                options.temporal ?? false,
+                options.caveman ?? false,
+                options.subagent ?? false,
+                options.language,
+                options.memory ?? true,
+                "light",
+            );
+
+        const memoryOff = light({ memory: false });
+        expect(memoryOff).not.toContain("Use `ctx_memory`");
+        expect(memoryOff).toContain("ctx_search");
+
+        const noReduce = light({ reduce: false });
+        expect(noReduce).not.toContain("In primary sessions with ctx_reduce");
+        expect(noReduce).not.toContain("drop grammar");
+
+        const gatedOff = light({ dreamer: false, temporal: false, caveman: false });
+        expect(gatedOff).not.toContain("surface_condition creates");
+        expect(gatedOff).not.toContain("**Temporal awareness**");
+        expect(gatedOff).not.toContain("**BEWARE**");
+
+        const gatedOn = light({ dreamer: true, temporal: true, caveman: true, language: "tr" });
+        expect(gatedOn).toContain("surface_condition creates");
+        expect(gatedOn).toContain("**Temporal awareness**");
+        expect(gatedOn).toContain("**BEWARE**");
+        expect(gatedOn).toContain("Keep code, identifiers, file paths");
+
+        const subagent = light({ subagent: true });
+        expect(subagent).toContain("In bounded subagent sessions");
+        expect(subagent).toContain("[dropped §N§]");
+        expect(subagent).not.toContain("long-term partner");
+        expect(subagent).not.toContain("ctx_search");
+    });
+
+    it("appends shared runtime fragments after a complete primary override", () => {
+        const override = "## Magic Context\n\nUser-owned primary guidance.";
+        const output = buildMagicContextSection(
+            null,
+            20,
+            true,
+            true,
+            true,
+            true,
+            false,
+            "tr",
+            true,
+            "full",
+            override,
+        );
+
+        expect(output.startsWith(override)).toBe(true);
+        expect(output.match(/^## Magic Context$/gm)).toHaveLength(1);
+        expect(output).toContain("**Temporal awareness**");
+        expect(output).toContain("**BEWARE**: History compression is on");
+        expect(output).toContain("Use Turkish (Türkçe) for your natural-language replies");
+        expect(output.indexOf("**Temporal awareness**")).toBeGreaterThan(
+            output.indexOf("User-owned primary guidance."),
+        );
+        expect(output).not.toContain("### Reduction Triggers");
+        expect(output).not.toContain("surface_condition");
+    });
+
+    it("keeps subagent guidance independent from a primary override", () => {
+        const output = buildMagicContextSection(
+            null,
+            20,
+            true,
+            false,
+            false,
+            false,
+            true,
+            undefined,
+            true,
+            "full",
+            "## Magic Context\n\nPrimary override must not reach subagents.",
+        );
+
+        expect(output).toContain("§N§ identifiers");
+        expect(output).not.toContain("Primary override must not reach subagents");
+    });
+});

package/src/agents/magic-context-prompt.ts

@@ -1,5 +1,6 @@
 /** Generic magic context system prompt section shared by all agents. */
 
+import type { PromptSurfacePreset } from "../shared/prompt-surface";
 import { buildPrimaryLanguageDirective } from "./language-directive";
 
 /**
@@ -30,6 +31,10 @@ const PARTNER_FRAME_CLOSER_REDUCE = `\nReduction prompts are routine housekeepin
 /** Closer for sessions where ctx_reduce is unavailable — context is managed fully automatically. */
 const PARTNER_FRAME_CLOSER_NO_REDUCE = `\nContext is managed for you entirely automatically — there's nothing to prune and no warnings to act on. Stay reasonably concise per operation, and never let context size change *what* work you take on or *how thoroughly* you do it.`;
 
+const PARTNER_FRAME_CLOSER_REDUCE_LIGHT = `\nWhen ctx_reduce is available, use it only as routine housekeeping; never cut task scope or depth because context is large.`;
+
+const PARTNER_FRAME_CLOSER_NO_REDUCE_LIGHT = `\nWhen ctx_reduce is unavailable, context is automatic; never prune, heed reduction warnings, or cut task scope or depth because context is large.`;
+
 /**
  * Shared `ctx_note` guidance for both intro variants. Generalizes two observed
  * misuse patterns: (1) taking a note for work that's only a few turns away — that
@@ -107,6 +112,23 @@ Use \`ctx_expand\` to recover the raw conversation behind a summary under a \`##
 \`ctx_search\` returns ranked results from memories, git commits, and raw message history. Use message ordinals from results with \`ctx_expand\` to retrieve surrounding conversation context.
 ${TOOL_HISTORY_GUIDANCE}`;
 
+const LIGHT_SEARCH_RECOVERY = `Use ctx_search before asking the user about prior project context; it searches memories, commits, and compacted conversation. When a session-history summary lacks exact wording, values, errors, or reasoning, call ctx_expand with its heading range instead of guessing.`;
+
+const BASE_INTRO_LIGHT = (
+    protectedTags: number,
+    memoryEnabled: boolean,
+): string => `In primary sessions with ctx_reduce, the system tags messages and tool outputs as §N§ (for example §1§ and §42§); never imitate these prefixes in replies because only injected tag numbers are valid ctx_reduce handles.
+In primary sessions, NEVER narrate ctx_reduce; call it silently after extracting a spent output because it marks content discardable and QUEUES release rather than deleting immediately. The last ${protectedTags} tags stay protected until they age out. Use drop grammar "3-5", "1,2,9", or "1-5,8,12-15".
+${CTX_NOTE_GUIDANCE}
+${memoryGuidanceBlock(memoryEnabled)}${LIGHT_SEARCH_RECOVERY}
+${TOOL_HISTORY_GUIDANCE}
+For primary ctx_reduce choices, NEVER blanket-drop a large range because mixed-value evidence may be lost: inspect every tag first. Drop only analyzed reads, searches, diagnostics, or build/test outputs after use. NEVER drop user directives or assistant prose unless exceptionally large; keep requirements, constraints, unresolved errors or decisions, exact wording, raw evidence, and active files or work. Only extracted pasted user payloads may go.
+Consider small targeted drops after acted-on reads or searches, completed logical steps, before context switches, and before the turn ends; this keeps the working set tidy without changing task scope.`;
+
+const BASE_INTRO_NO_REDUCE_LIGHT = (memoryEnabled: boolean): string => `${CTX_NOTE_GUIDANCE}
+${memoryGuidanceBlock(memoryEnabled)}${LIGHT_SEARCH_RECOVERY}
+${TOOL_HISTORY_GUIDANCE}`;
+
 const GENERIC_SECTION = `
 ### Reduction Triggers
 - After reading files or search results you already acted on — drop raw outputs.
@@ -124,6 +146,8 @@ const GENERIC_SECTION = `
 - Recent errors and unresolved decisions.
 - Active work context and files being edited.`;
 
+const SMART_NOTE_GUIDANCE_LIGHT = `\nsurface_condition creates a smart note checked nightly against external signals on ctx_note write.`;
+
 const TEMPORAL_AWARENESS_GUIDANCE = `\n**Temporal awareness**: User messages may be preceded by HTML comments like \`<!-- +12m -->\`, \`<!-- +2h 15m -->\`, or \`<!-- +3d 4h -->\` indicating time elapsed since the previous message's completion. Compartments in \`<session-history>\` carry \`start-date\` and \`end-date\` attributes (YYYY-MM-DD) showing real-time boundaries. Use these when reasoning about workflow pacing, log durations, build times, or how long ago something happened.`;
 
 /**
@@ -142,6 +166,12 @@ Use \`ctx_reduce\` to drop tool outputs you have already finished with, keeping
 Drop silently — do not narrate it. NEVER drop large ranges blindly (e.g., "1-50"); review each tag first. Do not drop user or assistant text messages — only large tool outputs are worth dropping.
 Older tool calls may show \`[dropped §N§]\` sentinels; that is normal context management, not a pattern to copy. ALWAYS make fresh real tool calls when you need data again; never fabricate or inline tool output.`;
 
+const SUBAGENT_REDUCE_INTRO_LIGHT = (
+    protectedTags: number,
+): string => `In bounded subagent sessions, the system tags messages and tool outputs as §N§; use only those IDs in ctx_reduce drop ranges such as "3-5", "1,2,9", or "1-5,8,12-15". The last ${protectedTags} tags stay protected.
+When dropping, do it silently and NEVER choose a large range before reviewing every tag; drop only finished large tool outputs, never user or assistant messages.
+If older calls show [dropped §N§], never copy that system sentinel because it is not reply syntax; make a fresh real tool call and never fabricate or inline output.`;
+
 const CAVEMAN_COMPRESSION_WARNING = `\n**BEWARE**: History compression is on; older user AND assistant text — including your own earlier responses — has been deterministically rewritten in a terse caveman style (dropped articles, missing auxiliaries, \`//\` instead of connectives like \`because\`). This is automatic context compression that runs after the fact, not your actual prior wording or the user's. **DO NOT mimic this style in new turns.** Write fresh responses in normal prose. If you notice your output drifting into caveman cadence, that drift is in-context-learning bleeding from the compressed history — consciously revert to full sentences.`;
 
 export function buildMagicContextSection(
@@ -154,6 +184,8 @@ export function buildMagicContextSection(
     subagentMode = false,
     language?: string,
     memoryEnabled = true,
+    preset: PromptSurfacePreset = "full",
+    primaryOverride?: string,
 ): string {
     // Subagent sessions: minimal §N§ + ctx_reduce mechanics only. Bypasses the
     // long-term-partner frame, memory/search/note guidance, and the reduction
@@ -162,10 +194,16 @@ export function buildMagicContextSection(
     // when ctx_reduce is off the subagent gets no §N§ prefix, so describing the
     // tag system would be noise.
     if (subagentMode) {
-        return `## Magic Context\n\n${SUBAGENT_REDUCE_INTRO(protectedTags)}`;
+        const intro =
+            preset === "light"
+                ? SUBAGENT_REDUCE_INTRO_LIGHT(protectedTags)
+                : SUBAGENT_REDUCE_INTRO(protectedTags);
+        return `## Magic Context\n\n${intro}`;
     }
     const smartNoteGuidance = dreamerEnabled
-        ? `\nWhen \`surface_condition\` is provided with \`write\`, the note becomes a project-scoped smart note.\nThe dreamer evaluates smart note conditions during nightly runs and surfaces them when conditions are met.\nExample: \`ctx_note(action="write", content="Implement X because Y", surface_condition="When PR #42 is merged in this repo")\``
+        ? preset === "light"
+            ? SMART_NOTE_GUIDANCE_LIGHT
+            : `\nWhen \`surface_condition\` is provided with \`write\`, the note becomes a project-scoped smart note.\nThe dreamer evaluates smart note conditions during nightly runs and surfaces them when conditions are met.\nExample: \`ctx_note(action="write", content="Implement X because Y", surface_condition="When PR #42 is merged in this repo")\``
         : "";
     const temporalGuidance = temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE : "";
     // Caveman compression is independent of ctx_reduce availability. Emit the
@@ -175,8 +213,21 @@ export function buildMagicContextSection(
     const languageDirective = buildPrimaryLanguageDirective(language);
     const languageGuidance = languageDirective ? `\n\n${languageDirective}` : "";
 
+    if (primaryOverride !== undefined) {
+        // A user override owns the complete primary section. Runtime clauses stay
+        // composer-owned so an override cannot suppress temporal guidance, the
+        // warning against overly compressed prose, or the language directive.
+        return `${primaryOverride}${temporalGuidance}${cavemanWarning}${languageGuidance}`;
+    }
+
     if (!ctxReduceCallable) {
+        if (preset === "light") {
+            return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_NO_REDUCE_LIGHT}\n\n${BASE_INTRO_NO_REDUCE_LIGHT(memoryEnabled)}${smartNoteGuidance}${temporalGuidance}${cavemanWarning}${languageGuidance}`;
+        }
         return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_NO_REDUCE}\n\n${BASE_INTRO_NO_REDUCE(memoryEnabled)}${smartNoteGuidance}${temporalGuidance}${cavemanWarning}${languageGuidance}`;
     }
+    if (preset === "light") {
+        return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_REDUCE_LIGHT}\n\n${BASE_INTRO_LIGHT(protectedTags, memoryEnabled)}${smartNoteGuidance}${temporalGuidance}${cavemanWarning}${languageGuidance}`;
+    }
     return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_REDUCE}\n\n${BASE_INTRO(protectedTags, memoryEnabled)}${smartNoteGuidance}${temporalGuidance}${cavemanWarning}\n${GENERIC_SECTION}\n\nPrefer many small targeted operations over one large blanket operation, and keep the working set tidy as routine maintenance.${languageGuidance}`;
 }

package/src/agents/permissions.ts

@@ -6,9 +6,10 @@ import { log } from "../shared/logger";
  * # 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
+ * registered with `mode: "primary"` and `hidden: true`: primary mode keeps
+ * them out of OpenCode's general Task candidate list, while hidden keeps them
+ * out of the UI picker. Those flags do NOT restrict which tools the spawned
+ * session can call. By default a registered agent
  * inherits the FULL primary-agent tool surface: `task`, `bash`, `edit`,
  * `webfetch`, `websearch`, `read`, `grep`, `glob`, every MCP tool, etc.
  *

package/src/config/index.test.ts

@@ -934,3 +934,56 @@ describe("transform_mode resolution", () => {
         expect(result.subc?.connection_file).not.toContain("project-controlled.sock");
     });
 });
+
+describe("loadPluginConfigDetailed — prompt-surface registration owner", () => {
+    it("captures the user default before project guidance routing is merged", () => {
+        const xdg = mkdtempSync(join(tmpdir(), "mc-config-prompt-surface-"));
+        const projectDir = mkdtempSync(join(tmpdir(), "mc-project-prompt-surface-"));
+        const fs = require("node:fs") as typeof import("node:fs");
+        const userDir = join(xdg, "cortexkit");
+        const projectConfigDir = join(projectDir, ".cortexkit");
+        fs.mkdirSync(userDir, { recursive: true });
+        fs.mkdirSync(projectConfigDir, { recursive: true });
+        writeFileSync(
+            join(userDir, "magic-context.jsonc"),
+            JSON.stringify({
+                prompt_surface: {
+                    default: "light",
+                    guidance_override_path: "guidance.md",
+                    tool_descriptions: { ctx_search: "user text" },
+                },
+            }),
+        );
+        writeFileSync(
+            join(projectConfigDir, "magic-context.jsonc"),
+            JSON.stringify({
+                prompt_surface: {
+                    default: "full",
+                    models: { "openai/*": "light" },
+                },
+            }),
+        );
+        const originalXdg = process.env.XDG_CONFIG_HOME;
+        process.env.XDG_CONFIG_HOME = xdg;
+
+        try {
+            const result = loadPluginConfigDetailed(projectDir);
+            expect(result.config.prompt_surface).toEqual({
+                default: "full",
+                models: { "openai/*": "light" },
+                guidance_override_path: "guidance.md",
+                tool_descriptions: { ctx_search: "user text" },
+            });
+            expect(result.registrationPromptSurface).toEqual({
+                default: "light",
+                guidance_override_path: "guidance.md",
+                tool_descriptions: { ctx_search: "user text" },
+            });
+        } finally {
+            if (originalXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+            else process.env.XDG_CONFIG_HOME = originalXdg;
+            rmSync(xdg, { recursive: true, force: true });
+            rmSync(projectDir, { recursive: true, force: true });
+        }
+    });
+});

package/src/config/index.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 
 import { detectConfigFile, parseJsonc } from "../shared/jsonc-parser";
 import { setOutputReserveConfig } from "../shared/models-dev-cache";
+import type { PromptSurfaceConfig } from "../shared/prompt-surface";
 import { isCompactionEnabled, migrateLegacyAgentEnabledInMemory } from "./agent-disable";
 import {
     cortexKitProjectConfigBasePath,
@@ -82,6 +83,8 @@ export type LoadOutcome =
 
 export interface LoadResultDetailed {
     config: MagicContextPluginConfig & { configWarnings?: string[] };
+    /** USER-tier default/overrides captured before project routing is merged. */
+    registrationPromptSurface: PromptSurfaceConfig;
     loadOutcome: LoadOutcome;
     sources: {
         userConfig: LoadOutcome;
@@ -593,6 +596,7 @@ export function loadPluginConfigDetailed(directory: string): LoadResultDetailed
 
     return {
         config,
+        registrationPromptSurface: trustedBaseConfig.prompt_surface,
         loadOutcome: combinedOutcome({ sources, substitutionFailures, recoveredTopLevelKeys }),
         sources,
         substitutionFailures,

package/src/config/project-security.test.ts

@@ -48,6 +48,26 @@ describe("stripUnsafeProjectConfigFields", () => {
         expect(warnings.some((w) => w.includes("output_reserve"))).toBe(true);
     });
 
+    it("strips prompt-surface text overrides but keeps project routing", () => {
+        const raw: Record<string, unknown> = {
+            prompt_surface: {
+                default: "light",
+                models: { "openai/*": "full" },
+                guidance_override_path: "/repo/guidance.md",
+                tool_descriptions: { ctx_search: "repo-controlled text" },
+            },
+        };
+
+        const warnings = stripUnsafeProjectConfigFields(raw);
+
+        expect(raw.prompt_surface).toEqual({
+            default: "light",
+            models: { "openai/*": "full" },
+        });
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain("prompt_surface.guidance_override_path/tool_descriptions");
+    });
+
     it("strips language from project config", () => {
         const raw: Record<string, unknown> = { language: "tr", dreamer: { model: "x" } };
         const warnings = stripUnsafeProjectConfigFields(raw);

package/src/config/project-security.ts

@@ -16,6 +16,7 @@ import { DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE } from "./schema/magic-context";
 /** Hidden agents that run with elevated/autonomous capability. */
 const HIDDEN_AGENT_KEYS = ["historian", "dreamer", "sidekick"] as const;
 const HISTORIAN_USER_ONLY_FIELDS = ["model", "fallback_models"] as const;
+const PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"] as const;
 
 /**
  * Fields on a hidden-agent block that constitute a privilege-escalation /
@@ -217,6 +218,9 @@ function makeProjectThresholdWarning(field: string, reason: string): string {
  *    a cloned repo cannot choose a model that sends project memory to a provider.
  *  - `pi.subagent_extensions` — a cloned repo must not choose which extensions
  *    the user's Pi child processes load.
+ *  - `prompt_surface.guidance_override_path` / `tool_descriptions` — a repository
+ *    may select a reviewed preset, but must not inject arbitrary guidance or tool
+ *    description text into the user's provider-visible prompt.
  *  - hidden-agent `prompt`/`permission`/`tools` — a repo must not reprogram or
  *    re-permission the historian/dreamer/sidekick.
  */
@@ -290,6 +294,25 @@ export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknow
         );
     }
 
+    // Repositories may select preset routing, but project settings cannot add
+    // guidance or tool-description text to the provider-visible prompt; those
+    // user-only fields are removed before project settings are merged.
+    const promptSurface = projectRaw.prompt_surface;
+    if (isPlainObject(promptSurface)) {
+        const removed: string[] = [];
+        for (const field of PROMPT_SURFACE_USER_ONLY_FIELDS) {
+            if (field in promptSurface) {
+                delete promptSurface[field];
+                removed.push(field);
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring prompt_surface.${removed.join("/")} from project config (security: repositories may select prompt presets but only user config may provide guidance or tool-description text).`,
+            );
+        }
+    }
+
     const pi = projectRaw.pi;
     if (isPlainObject(pi) && "subagent_extensions" in pi) {
         delete pi.subagent_extensions;

package/src/config/schema/magic-context.test.ts

@@ -19,6 +19,7 @@ describe("MagicContextConfigSchema", () => {
                 transform_mode: "ts",
                 storage: { enforce_private_permissions: true },
                 cache_ttl: "5m",
+                prompt_surface: { default: "full" },
                 execute_threshold_percentage: 65,
                 protected_tags: 20,
                 clear_reasoning_age: 50,
@@ -79,6 +80,7 @@ describe("MagicContextConfigSchema", () => {
                 auto_update: false,
                 toast_duration_ms: 5000,
                 cache_ttl: "10m",
+                prompt_surface: { default: "full" },
                 protected_tags: 3,
                 execute_threshold_percentage: 75,
                 clear_reasoning_age: 60,
@@ -257,6 +259,23 @@ describe("MagicContextConfigSchema", () => {
 
             expect(result.cache_ttl).toEqual(input.cache_ttl);
         });
+
+        // Accepts preset routing, a guidance override path, and tool-description overrides.
+        it("parses prompt-surface defaults, routes, and user overrides", () => {
+            const promptSurface = {
+                default: "light" as const,
+                models: {
+                    "anthropic/claude/sonnet": "full" as const,
+                    "openai/*": "light" as const,
+                },
+                guidance_override_path: "./guidance.md",
+                tool_descriptions: { ctx_search: "Search project context" },
+            };
+
+            expect(
+                MagicContextConfigSchema.parse({ prompt_surface: promptSurface }).prompt_surface,
+            ).toEqual(promptSurface);
+        });
     });
 
     describe("validation", () => {
@@ -264,6 +283,45 @@ describe("MagicContextConfigSchema", () => {
             expect(() => MagicContextConfigSchema.parse({ transform_mode: "wasm" })).toThrow();
         });
 
+        it("rejects malformed prompt-surface model keys and empty override text", () => {
+            const malformedKeys = [
+                "",
+                "provider",
+                "/model",
+                "provider/",
+                "provider//model",
+                "provider/model*",
+                "provider/*/nested",
+                "provider//model",
+                "provider/model/",
+                "provider/ model",
+                "*/model",
+            ];
+            for (const key of malformedKeys) {
+                expect(
+                    MagicContextConfigSchema.safeParse({
+                        prompt_surface: { models: { [key]: "light" } },
+                    }).success,
+                ).toBe(false);
+            }
+
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { guidance_override_path: "  " },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { tool_descriptions: { ctx_search: "  " } },
+                }).success,
+            ).toBe(false);
+            expect(
+                MagicContextConfigSchema.safeParse({
+                    prompt_surface: { tool_descriptions: { "  ": "description" } },
+                }).success,
+            ).toBe(false);
+        });
+
         it("rejects empty Pi subagent extension entries", () => {
             expect(() =>
                 MagicContextConfigSchema.parse({ pi: { subagent_extensions: ["  "] } }),

package/src/config/schema/magic-context.ts

@@ -7,6 +7,7 @@ import type {
     AGENTIC_DREAM_TASKS,
     DreamTaskName,
 } from "../../features/magic-context/dreamer/task-registry";
+import { isValidPromptSurfaceModelKey } from "../../shared/prompt-surface";
 import { AgentOverrideConfigSchema } from "./agent-overrides";
 
 export const DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE = 65;
@@ -49,6 +50,60 @@ export const PiConfigSchema = z
     .optional();
 export type PiConfig = NonNullable<z.infer<typeof PiConfigSchema>>;
 
+/**
+ * Route the built-in prompt surface without changing guidance or tool registration.
+ * Project config can choose preset routing; only user config can provide override text.
+ */
+export const PromptSurfacePresetSchema = z.enum(["full", "light"]);
+export type { PromptSurfacePreset } from "../../shared/prompt-surface";
+
+const PromptSurfaceModelKeySchema = z.string().refine(isValidPromptSurfaceModelKey, {
+    message:
+        "Use a non-empty provider/model key or the literal provider/* wildcard; model IDs may contain additional slashes and matching is case-sensitive.",
+});
+// Tool-description keys must be non-empty IDs; harness-specific known-tool
+// validation can run when a user override is applied.
+const PromptSurfaceToolKeySchema = z.string().refine((value) => value.trim().length > 0, {
+    message: "tool description keys must not be empty or whitespace-only",
+});
+
+export const PromptSurfaceConfigSchema = z
+    .object({
+        default: PromptSurfacePresetSchema.default("full").describe(
+            'Fallback prompt-surface preset ("full" or "light").',
+        ),
+        models: z
+            .record(PromptSurfaceModelKeySchema, PromptSurfacePresetSchema)
+            .optional()
+            .describe(
+                "Literal per-model routing. Keys are provider/model or provider/*; matching is case-sensitive and preserves additional slashes in model IDs.",
+            ),
+        guidance_override_path: z
+            .string()
+            .refine((value) => value.trim().length > 0, {
+                message: "guidance_override_path must not be empty or whitespace-only",
+            })
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY path to a complete primary guidance section. Relative paths resolve from the user config file.",
+            ),
+        tool_descriptions: z
+            .record(
+                PromptSurfaceToolKeySchema,
+                z.string().refine((value) => value.trim().length > 0, {
+                    message: "tool description values must not be empty or whitespace-only",
+                }),
+            )
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY top-level description overrides keyed by ctx_* tool ID; parameter schemas and descriptions are unchanged.",
+            ),
+    })
+    .describe(
+        "Prompt-surface preset routing. Project config may select default/models, while guidance_override_path and tool_descriptions are user-level only.",
+    );
+export type PromptSurfaceConfig = z.infer<typeof PromptSurfaceConfigSchema>;
+
 /** A 5-field cron expression, or "" to disable the task. */
 const CronScheduleSchema = z
     .string()
@@ -416,6 +471,8 @@ export interface MagicContextConfig {
     historian?: HistorianConfig;
     dreamer?: DreamerConfig;
     cache_ttl: string | { default: string; [modelKey: string]: string };
+    /** Preset routing for guidance and provider-visible prompt surfaces. */
+    prompt_surface: PromptSurfaceConfig;
     /** User-only output-token reservation override. Zero disables reservation. */
     output_reserve?: number | { default: number; [modelKey: string]: number };
     /** TUI toast lifetime in milliseconds for Magic Context notifications. Default: 5000. */
@@ -637,6 +694,9 @@ export const MagicContextConfigSchema = z
             .describe(
                 'Cache TTL: string (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time.',
             ),
+        prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe(
+            "Prompt-surface presets: default is full; models use the literal provider/model or provider/* routing grammar. Guidance and tool-description overrides are user-level only. On OpenCode and Pi, per-model routing applies to the guidance block only: tool descriptions are registered once per process, so they follow the default preset (a v1 plugin-surface limitation; per-model tool descriptions are planned for the OpenCode v2 plugin API once the SDK stabilizes).",
+        ),
         output_reserve: z
             .union([
                 z.number().min(0),
@@ -828,7 +888,7 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. If transform_mode is rust, compaction-off resolves to the TypeScript transform and emits one frozen boot warning because there is no Rust reduced-mode contract. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
+                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; ctx_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in magic-context.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /ctx-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory/docs injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
                     ),
             })
             .default({ enabled: true })

package/src/shared/index.ts

@@ -1,4 +1,6 @@
 export * from "./logger";
 export * from "./model-suggestion-retry";
 export * from "./normalize-sdk-response";
+export * from "./prompt-surface";
+export * from "./prompt-surface-runtime";
 export * from "./resolve-fallbacks";