@cortexkit/opencode-magic-context 0.33.1 → 0.34.0

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

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "bun:test";
+
+import { COMPARTMENT_AGENT_SYSTEM_PROMPT } from "../hooks/magic-context/compartment-prompt";
+import { withContentLanguageDirective } from "./language-directive";
+import { buildMagicContextSection } from "./magic-context-prompt";
+
+describe("Magic Context language guidance", () => {
+    it("keeps guidance bytes unchanged when language is unset or blank", () => {
+        const baseline = buildMagicContextSection(null, 20, true, true, false, false, false);
+        expect(buildMagicContextSection(null, 20, true, true, false, false, false, undefined)).toBe(
+            baseline,
+        );
+        expect(buildMagicContextSection(null, 20, true, true, false, false, false, "   ")).toBe(
+            baseline,
+        );
+    });
+
+    it("keeps historian prompt bytes unchanged when language is unset", () => {
+        expect(
+            withContentLanguageDirective(COMPARTMENT_AGENT_SYSTEM_PROMPT, undefined, {
+                preserveUserQuotes: true,
+            }),
+        ).toBe(COMPARTMENT_AGENT_SYSTEM_PROMPT);
+    });
+
+    it("adds deterministic primary language guidance when set", () => {
+        const first = buildMagicContextSection(null, 20, true, true, false, false, false, "tr");
+        const second = buildMagicContextSection(null, 20, true, true, false, false, false, "tr");
+        const baseline = buildMagicContextSection(null, 20, true, true, false, false, false);
+
+        expect(first).toBe(second);
+        expect(first).toContain("Use Turkish (Türkçe) for your natural-language replies");
+        expect(first.startsWith(baseline)).toBe(true);
+    });
+});

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

@@ -0,0 +1,292 @@
+import { describe, expect, it } from "bun:test";
+import { buildMagicContextSection } from "./magic-context-prompt";
+
+const CAVEMAN_MARKER = "BEWARE";
+const CAVEMAN_PHRASE_TAIL = "consciously revert to full sentences";
+
+const KNOWN_AGENT_IDENTITIES = [
+    "sisyphus",
+    "atlas",
+    "hephaestus",
+    "sisyphus-junior",
+    "oracle",
+    "athena",
+    "athena-junior",
+] as const;
+
+describe("buildMagicContextSection — generic guidance", () => {
+    it("emits the same generic guidance for all known agent identities", () => {
+        const generic = buildMagicContextSection(null, 20, true, false, false, false);
+
+        for (const agent of KNOWN_AGENT_IDENTITIES) {
+            expect(buildMagicContextSection(agent, 20, true, false, false, false)).toBe(generic);
+        }
+    });
+
+    it("does not emit legacy agent-tailored guidance", () => {
+        const out = buildMagicContextSection("atlas", 20, true, false, false, false);
+
+        expect(out).toContain("### Reduction Triggers");
+        expect(out).toContain("Your current task requirements and constraints");
+        expect(out).not.toContain("CRITICAL — you run long sessions");
+        expect(out).not.toContain("delegation tool outputs from completed waves");
+        expect(out).not.toContain("council member response outputs");
+    });
+
+    it("opens with the long-term-partner frame in BOTH ctx_reduce availability variants", () => {
+        const reduce = buildMagicContextSection(null, 20, true, false, false, false);
+        const noReduce = buildMagicContextSection(null, 20, false, false, false, false);
+
+        for (const out of [reduce, noReduce]) {
+            // Identity frame + the durability + no-scarcity + no-wind-down beats.
+            expect(out).toContain("long-term partner on this project");
+            expect(out).toContain("weeks, months, or even years");
+            expect(out).toContain("effectively unbounded");
+            expect(out).toContain("never a reason to wrap up, cut scope, rush, or defer");
+            expect(out).toContain("Finishing a task does not end the session");
+            expect(out).toContain("no compaction pauses");
+            // Frame is at the TOP — before the tool mechanics.
+            expect(out.indexOf("long-term partner")).toBeLessThan(out.indexOf("ctx_note"));
+        }
+    });
+
+    it("uses the mode-specific partner-frame closer", () => {
+        const reduce = buildMagicContextSection(null, 20, true, false, false, false);
+        const noReduce = buildMagicContextSection(null, 20, false, false, false, false);
+
+        // reduce mode: agent participates in housekeeping
+        expect(reduce).toContain("Reduction prompts are routine housekeeping");
+        expect(reduce).not.toContain("there's nothing to prune");
+        // no-reduce mode: fully automatic, nothing to prune
+        expect(noReduce).toContain("there's nothing to prune and no warnings to act on");
+        expect(noReduce).not.toContain("Reduction prompts are routine housekeeping");
+        // Both keep the task-scope caveat.
+        for (const out of [reduce, noReduce]) {
+            expect(out).toContain("never let context size change");
+        }
+    });
+
+    it("no longer emits the scarcity-flavored 'compress early and often, don't wait for warnings' line", () => {
+        const reduce = buildMagicContextSection(null, 20, true, false, false, false);
+        expect(reduce).not.toContain("don't wait for warnings");
+    });
+});
+
+describe("buildMagicContextSection — subagent mode", () => {
+    const subagent = () => buildMagicContextSection(null, 20, true, false, false, false, true);
+
+    it("emits ONLY the minimal §N§ + ctx_reduce mechanics", () => {
+        const out = subagent();
+        // Has the marker (injection idempotency) + the tag/ctx_reduce mechanics.
+        expect(out).toContain("## Magic Context");
+        expect(out).toContain("§N§ identifiers");
+        expect(out).toContain("ctx_reduce");
+        expect(out).toContain("The last 20 tags are protected");
+    });
+
+    it("OMITS the long-term-partner frame and primary-only guidance", () => {
+        const out = subagent();
+        expect(out).not.toContain("long-term partner");
+        expect(out).not.toContain("weeks, months, or even years");
+        expect(out).not.toContain("### Reduction Triggers");
+        expect(out).not.toContain("ctx_memory");
+        expect(out).not.toContain("ctx_search");
+        expect(out).not.toContain("ctx_note");
+        expect(out).not.toContain("ctx_expand");
+    });
+
+    it("threads protectedTags into the protected-count line", () => {
+        const out = buildMagicContextSection(null, 7, true, false, false, false, true);
+        expect(out).toContain("The last 7 tags are protected");
+    });
+
+    it("is much shorter than the full primary block", () => {
+        const full = buildMagicContextSection(null, 20, true, false, false, false, false);
+        expect(subagent().length).toBeLessThan(full.length / 2);
+    });
+
+    it("defaults subagentMode=false (legacy callers unaffected)", () => {
+        const sixArg = buildMagicContextSection(null, 20, true, false, false, false);
+        const explicitFalse = buildMagicContextSection(null, 20, true, false, false, false, false);
+        expect(sixArg).toBe(explicitFalse);
+        expect(sixArg).toContain("long-term partner");
+    });
+});
+
+describe("buildMagicContextSection: memory gating", () => {
+    // buildMagicContextSection's 9th positional parameter is memoryEnabled
+    // (defaults to true). The 7-arg legacy call below relies on that default.
+    it("memory ON (default) keeps the ctx_memory guidance and is byte-identical to legacy callers", () => {
+        const legacy = buildMagicContextSection(null, 20, true, false, false, false, false);
+        const memOn = buildMagicContextSection(
+            null,
+            20,
+            true,
+            false,
+            false,
+            false,
+            false,
+            undefined,
+            true,
+        );
+        expect(memOn).toBe(legacy);
+        expect(memOn).toContain("Use `ctx_memory`");
+        expect(memOn).toContain("**Save to memory proactively**");
+    });
+
+    it("memory OFF drops ALL ctx_memory guidance but keeps ctx_search", () => {
+        const off = buildMagicContextSection(
+            null,
+            20,
+            true,
+            false,
+            false,
+            false,
+            false,
+            undefined,
+            false,
+        );
+        expect(off).not.toContain("ctx_memory");
+        expect(off).not.toContain("Save to memory proactively");
+        expect(off).toContain("Use `ctx_search`");
+        // no dangling blank line where the block was removed
+        expect(off).not.toContain("\n\nUse `ctx_search`");
+    });
+
+    it("memory OFF gates the guidance in no-reduce mode too", () => {
+        const off = buildMagicContextSection(
+            null,
+            20,
+            false,
+            false,
+            false,
+            false,
+            false,
+            undefined,
+            false,
+        );
+        expect(off).not.toContain("ctx_memory");
+        expect(off).toContain("Use `ctx_search`");
+    });
+});
+
+describe("buildMagicContextSection — caveman compression warning", () => {
+    it("emits the warning when caveman is enabled and ctx_reduce is unavailable", () => {
+        const out = buildMagicContextSection(
+            null, // agent
+            20, // protectedTags (ignored in no-reduce path)
+            false, // ctx_reduce is unavailable in this session.
+            false, // dreamerEnabled
+            false, // temporalAwarenessEnabled
+            true, // cavemanTextCompressionEnabled
+        );
+        expect(out).toContain(CAVEMAN_MARKER);
+        expect(out).toContain(CAVEMAN_PHRASE_TAIL);
+        expect(out).toContain("DO NOT mimic this style");
+    });
+
+    it("omits the warning when caveman is disabled", () => {
+        const out = buildMagicContextSection(
+            null,
+            20,
+            false, // ctx_reduce is unavailable in this session.
+            false, // dreamerEnabled
+            false, // temporalAwarenessEnabled
+            false, // cavemanTextCompressionEnabled = false
+        );
+        expect(out).not.toContain(CAVEMAN_MARKER);
+        expect(out).not.toContain(CAVEMAN_PHRASE_TAIL);
+    });
+
+    it("emits the warning when ctx_reduce is callable and caveman is enabled", () => {
+        // Caveman compression is independent from ctx_reduce availability, so
+        // reduce-enabled primary guidance must still warn about rewritten prose.
+        const out = buildMagicContextSection(
+            null,
+            20,
+            true, // ctx_reduce is callable in this session.
+            false, // dreamerEnabled
+            false, // temporalAwarenessEnabled
+            true, // cavemanTextCompressionEnabled
+        );
+        expect(out).toContain(CAVEMAN_MARKER);
+        expect(out).toContain(CAVEMAN_PHRASE_TAIL);
+    });
+
+    it("omits the warning by default (parameter optional)", () => {
+        // Old callers that didn't pass the new parameter must continue to
+        // produce identical output (no warning leaked into legacy paths).
+        const out = buildMagicContextSection(null, 20, false, false, false);
+        expect(out).not.toContain(CAVEMAN_MARKER);
+    });
+});
+
+describe("buildMagicContextSection — compaction-off guidance variant (#266 S4)", () => {
+    // Spec #266 decision #3: compaction-off mode reuses the EXISTING no-reduce
+    // guidance variant machinery — no third template. The variant is reached
+    // by passing ctxReduceCallable=false (which the process-global registration
+    // override in ctx-reduce-availability.ts forces when ctx_reduce is not
+    // registered). This suite pins the spec's guidance acceptance:
+    //   - no ctx_reduce mention, no §N§ prefix advertising, no tag-recovery
+    //   - memory/search/note/expand guidance present
+    //   - byte-identical to the existing reduce-unavailable variant (no third
+    //     template constant was introduced)
+
+    it("the compaction-off variant is byte-identical to the existing no-reduce variant", () => {
+        // The existing no-reduce variant is buildMagicContextSection(..., false, ...).
+        // Compaction-off reaches the SAME code path via the availability override,
+        // so the rendered text must be byte-identical — no third template.
+        const existingNoReduce = buildMagicContextSection(null, 20, false, false, false, false);
+        const compactionOff = buildMagicContextSection(null, 20, false, false, false, false);
+        expect(compactionOff).toBe(existingNoReduce);
+    });
+
+    it("does not advertise ctx_reduce, §N§ prefixes, or tag-based recovery", () => {
+        const out = buildMagicContextSection(null, 20, false, false, false, false);
+        // No ctx_reduce tool mention.
+        expect(out).not.toContain("ctx_reduce");
+        // No §N§ prefix SYSTEM DESCRIPTION / advertising. The reduce variant
+        // opens with "Messages and tool outputs are tagged with §N§
+        // identifiers" — that advertising line is absent here. (The
+        // `[dropped §N§]` sentinel appears only inside TOOL_HISTORY_GUIDANCE's
+        // "never reproduce these markers" prohibition list, which is shared
+        // by both variants and is not advertising; the spec pins reuse of the
+        // existing variant byte-identical, so that prohibition mention stays.)
+        expect(out).not.toContain("tagged with §N§ identifiers");
+        expect(out).not.toContain("Use `ctx_reduce`");
+        // No tag-based-recovery WORKFLOW wording. The expand line frames
+        // recovery around <session-history> summary headings and ctx_search
+        // message ordinals, not §N§ tags. "tag" appears only inside the
+        // shared TOOL_HISTORY_GUIDANCE prohibition ("never reproduce ..."),
+        // not as a recovery instruction.
+        expect(out).not.toMatch(/recover.*tag|tag.*recover/i);
+        expect(out).not.toContain("§N§ identifiers (e.g.");
+    });
+
+    it("still covers memory, search, notes, and ctx_expand guidance", () => {
+        const out = buildMagicContextSection(null, 20, false, false, false, false);
+        expect(out).toContain("ctx_search");
+        expect(out).toContain("ctx_expand");
+        expect(out).toContain("ctx_note");
+        expect(out).toContain("ctx_memory");
+    });
+
+    it("frames ctx_expand as recovery for summaries / ctx_search hits, not tag-based recovery", () => {
+        const out = buildMagicContextSection(null, 20, false, false, false, false);
+        // The expand line in the no-reduce variant references <session-history>
+        // summary headings and ctx_search message ordinals — not §N§ tags.
+        expect(out).toContain("ctx_expand");
+        expect(out).toContain("session-history");
+        expect(out).toContain("message ordinals");
+    });
+
+    it("the reduce variant DOES advertise §N§ and ctx_reduce (contrast for the off-mode assertion)", () => {
+        // This is the mutation-direction anchor: the reduce-on variant carries
+        // the §N§ + ctx_reduce advertising that the off-mode variant omits.
+        // If the off-mode variant ever leaked these, this contrast would
+        // still pass but the off-mode assertion above would go red.
+        const reduce = buildMagicContextSection(null, 20, true, false, false, false);
+        expect(reduce).toContain("ctx_reduce");
+        expect(reduce).toContain("tagged with §N§ identifiers");
+    });
+});

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

@@ -0,0 +1,182 @@
+/** Generic magic context system prompt section shared by all agents. */
+
+import { buildPrimaryLanguageDirective } from "./language-directive";
+
+/**
+ * Mindset frame that counters two trained priors which make agents
+ * self-sabotage under Magic Context:
+ *   1. Context-scarcity reflex — models trained on finite contexts wrap up, cut
+ *      scope, or rush when usage looks high. Our reduction nudges accidentally
+ *      trigger this.
+ *   2. Session = one task — models trained on one-session-per-task wind down when
+ *      a task finishes instead of continuing as a durable partner.
+ * This frame is injected at the TOP of the section (before the mechanics) in both
+ * ctx_reduce modes so it sets the frame before the agent reads anything that could
+ * read as a scarcity signal.
+ */
+const LONG_TERM_PARTNER_FRAME = `### You are the user's long-term partner on this project — not a one-off hire
+
+Most AI sessions are disposable: one session per task, discarded when it's done — like hiring a developer for a single bug fix and letting them go the moment they finish. Magic Context changes this completely. This session is a durable working relationship: you carry the full history and accumulated knowledge of this project, and you continue across many tasks, bugs, and features — with memory that persists across restarts. This session may continue for weeks, months, or even years.
+
+Because of this:
+- **Your context is continuously managed and effectively unbounded.** As the session grows, earlier turns are automatically compacted into \`<session-history>\` and stay fully retrievable via \`ctx_search\`/\`ctx_expand\`. You will not hit a context wall and you will not lose continuity mid-task.
+- **High context usage is normal and fully handled** — never a reason to wrap up, cut scope, rush, or defer work. Keep going at full depth.
+- **Finishing a task does not end the session.** Continue naturally into the next piece of work, carrying everything forward.
+- **There are no compaction pauses.** Unlike native context management that stops you to summarize and restart, Magic Context compacts in the background — you stay in flow, uninterrupted, so there's no reason to artificially wind down.`;
+
+/** Closer for sessions where ctx_reduce is callable — the agent has an active housekeeping role. */
+const PARTNER_FRAME_CLOSER_REDUCE = `\nReduction prompts are routine housekeeping to keep the session fast and cheap — act on them as light maintenance, never as scarcity warnings. Keep individual operations efficient, but never let context size change *what* work you take on or *how thoroughly* you do it.`;
+
+/** 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.`;
+
+/**
+ * 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
+ * stays in active context, and active multi-step work belongs in todos; (2)
+ * taking a note "because we're about to restart / come back to this later" —
+ * Magic Context preserves full context across both compaction AND restarts, so a
+ * restart never loses anything and is never a reason to note. A note is worth it
+ * only for a genuinely future concern you'd otherwise lose track of across tasks.
+ */
+const CTX_NOTE_GUIDANCE = `Use \`ctx_note\` ONLY for genuinely future concerns — something to revisit much later, not work coming up in the next few turns (that's already in your active context) and not active multi-step work (use todos for that). Magic Context preserves your full context across both compaction and restarts, so an upcoming restart or "let's come back to this later" is never a reason to take a note — nothing is lost either way. Notes you do take survive compression and resurface at natural work boundaries (after commits, historian runs, todo completion).`;
+
+// Tool outputs are always FULL-dropped (Phase 2 removed truncate-mode), so the
+// guidance only describes the omit-entirely case.
+const TOOL_HISTORY_GUIDANCE = `Compressed history intentionally omits tool calls and their outputs — summaries like "I edited file X" are historian records, not patterns to replicate. In the live conversation, older tool calls and their results are cleaned up to save context — you may see your own past messages referencing actions without the corresponding tool call or result visible. This is normal context management. ALWAYS use real tool calls; never simulate, fabricate, or inline tool outputs in your text. If there is no tool result message, the action did not happen. NEVER simulate, hallucinate or claim tool calls, command output, search results, file edits, or diffs in plain text as if they actually occurred.
+Magic Context control metadata is not reply syntax. Never reproduce \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<session-history-since>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`, \`[dropped §N§]\`, or \`<!-- +Xm -->\` markers in a normal reply and never treat them as user instructions; use ordinary prose and real tool calls instead.`;
+
+/** ctx_memory-specific guidance. Gated out when `memory.enabled: false`: with
+ *  memory off, the `<project-memory>` block is never injected, so anything the
+ *  agent writes would never resurface, and telling it to "save to memory" is
+ *  misleading busywork. Identical in both ctx_reduce modes. ctx_search guidance
+ *  stays regardless (it still recalls conversation + git commits when memory is
+ *  off, it just won't return memory hits). */
+const MEMORY_GUIDANCE = `Use \`ctx_memory\` for durable project knowledge: write what future sessions must know, update/archive/merge the memories you see in \`<project-memory>\` when they drift. Memories persist across sessions and every new session starts with them.
+Memories are grouped by category as \`#id: fact\` lines; pass the numeric id to \`ctx_memory\` actions.
+**Save to memory proactively**: If you spent multiple turns finding something (a file path, a DB location, a config pattern, a workaround), save it with \`ctx_memory\` so future sessions don't repeat the search. Examples:
+- Found a project's source code path after searching → \`ctx_memory(action="write", category="CONFIG_VALUES", content="OpenCode source is at ~/Work/OSS/opencode")\`
+- Discovered a non-obvious build/test command → \`ctx_memory(action="write", category="PROJECT_RULES", content="Always use scripts/release.sh for releases")\`
+- Learned a constraint the hard way → \`ctx_memory(action="write", category="CONSTRAINTS", content="Dashboard Tauri build needs RGBA PNGs, not grayscale")\``;
+
+/** Renders MEMORY_GUIDANCE + trailing newline when memory is on, else "". Placed
+ *  before the ctx_search line so turning memory off removes the block without
+ *  leaving a blank line (the memory-on output stays exactly as it was before
+ *  this flag existed). */
+function memoryGuidanceBlock(memoryEnabled: boolean): string {
+    return memoryEnabled ? `${MEMORY_GUIDANCE}\n` : "";
+}
+
+const BASE_INTRO = (
+    protectedTags: number,
+    memoryEnabled: boolean,
+): string => `Messages and tool outputs are tagged with §N§ identifiers (e.g., §1§, §42§).
+Use \`ctx_reduce\` to mark spent tagged content as discardable and reclaim space. Marking is NOT an immediate delete — it queues the content, which stays fully visible until space is actually needed (as soon as the next turn if you're already under pressure, much later if not), so mark a tool output as soon as you're done with it rather than hoarding the call for the end of the turn. The last ${protectedTags} tags are protected (marking one just queues it until it ages out). Syntax: "3-5", "1,2,9", or "1-5,8,12-15".
+Do not announce or narrate \`ctx_reduce\` drops — just call the tool silently. Saying "I'll drop these outputs" wastes tokens the user does not care about.
+${CTX_NOTE_GUIDANCE}
+${memoryGuidanceBlock(memoryEnabled)}Use \`ctx_search\` to search across project memories, indexed git commits, and this session's full conversation history (including compacted parts) from one query.
+Use \`ctx_expand\` to recover the raw conversation behind a summary under a \`## start-end · date · title\` heading inside \`<session-history>\` — pass the heading's start/end range when the summary is not enough (exact wording, values, error text).
+**Search before asking the user**: If you can't remember or don't know something that might have been discussed before or stored in project memory, use \`ctx_search\` before asking the user. Examples:
+- Can't remember where a related codebase or dependency lives → \`ctx_search(query="opencode source code path")\`
+- Forgot a prior architectural decision or constraint → \`ctx_search(query="why did we choose SQLite over postgres")\`
+- Need a config value, API key location, or environment detail → \`ctx_search(query="embedding provider configuration")\`
+- Looking for how something was implemented previously → \`ctx_search(query="how does the dreamer lease work")\`
+- Want to recall what was decided in an earlier conversation → \`ctx_search(query="dashboard release signing setup")\`
+\`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}
+NEVER drop large ranges blindly (e.g., "1-50"). Review each tag before deciding.
+Keep your user's instructions and intent — never drop a user message for its directive, even an old one. But a large block of pasted content inside a user message (logs, data dumps, long code, attachments) is fair to mark discardable once you've extracted what you need — it stays searchable via \`ctx_search\`.
+NEVER drop assistant text messages unless they are exceptionally large. Your conversation messages are lightweight; only large tool outputs are worth dropping.
+Before your turn finishes, consider using \`ctx_reduce\` to drop large tool outputs you no longer need.`;
+
+/** Intro when ctx_reduce is unavailable — no drop guidance, no ctx_reduce
+ *  references, and no tag system description. When the session's tool allow-list
+ *  denies ctx_reduce, transform.ts skips §N§ prefix injection entirely, so the
+ *  agent never sees tags — describing a tagging system they can't observe just
+ *  wastes tokens and (empirically) primes some models to emit malformed `§N">§`
+ *  tokens at the start of their own text. */
+const BASE_INTRO_NO_REDUCE = (memoryEnabled: boolean): string => `${CTX_NOTE_GUIDANCE}
+${memoryGuidanceBlock(memoryEnabled)}Use \`ctx_search\` to search across project memories, indexed git commits, and this session's full conversation history (including compacted parts) from one query.
+Use \`ctx_expand\` to recover the raw conversation behind a summary under a \`## start-end · date · title\` heading inside \`<session-history>\` — pass the heading's start/end range when the summary is not enough (exact wording, values, error text).
+**Search before asking the user**: If you can't remember or don't know something that might have been discussed before or stored in project memory, use \`ctx_search\` before asking the user. Examples:
+- Can't remember where a related codebase or dependency lives → \`ctx_search(query="opencode source code path")\`
+- Forgot a prior architectural decision or constraint → \`ctx_search(query="why did we choose SQLite over postgres")\`
+- Need a config value, API key location, or environment detail → \`ctx_search(query="embedding provider configuration")\`
+- Looking for how something was implemented previously → \`ctx_search(query="how does the dreamer lease work")\`
+- Want to recall what was decided in an earlier conversation → \`ctx_search(query="dashboard release signing setup")\`
+\`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 GENERIC_SECTION = `
+### Reduction Triggers
+- After reading files or search results you already acted on — drop raw outputs.
+- After completing a logical step — drop intermediate outputs from that step.
+- Between major context switches — when moving to a new task area.
+
+### What to Drop
+- Large file reads, grep results, and tool outputs you already used.
+- Large build/test output after you analyzed and acted on it.
+- Old diagnostic or exploration results that are no longer relevant.
+
+### What to Keep
+- ALL user messages and assistant conversation text — these are cheap and compartmentalized automatically.
+- Your current task requirements and constraints.
+- Recent errors and unresolved decisions.
+- Active work context and files being edited.`;
+
+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.`;
+
+/**
+ * Minimal guidance for SUBAGENT sessions. Subagents are bounded, single-task
+ * executors driven by a parent agent — they self-manage tool-output bloat (the
+ * re-read thrash the emergency drop alone can't prevent mid-run) but take on
+ * NONE of the primary's long-term role: no partner frame, no memory/search/note
+ * curation, no reduction-trigger taxonomy. So this block carries ONLY the §N§ +
+ * ctx_reduce mechanics. The `## Magic Context` marker is still present for
+ * injection idempotency (system-prompt-hash.ts gates on it).
+ */
+const SUBAGENT_REDUCE_INTRO = (
+    protectedTags: number,
+): string => `Messages and tool outputs are tagged with §N§ identifiers (e.g., §1§, §42§).
+Use \`ctx_reduce\` to drop tool outputs you have already finished with, keeping your working context lean. Syntax: "3-5", "1,2,9", or "1-5,8,12-15". The last ${protectedTags} tags are protected.
+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 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(
+    _agent: string | null,
+    protectedTags: number,
+    ctxReduceCallable = true,
+    dreamerEnabled = false,
+    temporalAwarenessEnabled = false,
+    cavemanTextCompressionEnabled = false,
+    subagentMode = false,
+    language?: string,
+    memoryEnabled = true,
+): string {
+    // Subagent sessions: minimal §N§ + ctx_reduce mechanics only. Bypasses the
+    // long-term-partner frame, memory/search/note guidance, and the reduction
+    // taxonomy — none of which apply to a bounded single-task child. Only
+    // reachable when ctx_reduce is enabled for the subagent (caller gates this);
+    // 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 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")\``
+        : "";
+    const temporalGuidance = temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE : "";
+    // Caveman compression is independent of ctx_reduce availability. Emit the
+    // warning in both primary guidance variants whenever the primary-session
+    // caveman pass is enabled so the agent does not mimic compressed history.
+    const cavemanWarning = cavemanTextCompressionEnabled ? CAVEMAN_COMPRESSION_WARNING : "";
+    const languageDirective = buildPrimaryLanguageDirective(language);
+    const languageGuidance = languageDirective ? `\n\n${languageDirective}` : "";
+
+    if (!ctxReduceCallable) {
+        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}`;
+    }
+    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}`;
+}