@cortexkit/opencode-magic-context 0.42.5 → 0.43.0

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

@@ -26,8 +26,8 @@ describe("buildMagicContextSection — generic guidance", () => {
     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).toContain("### Your desk");
+        expect(out).toContain("no longer needs to stay on the desk for the work ahead");
         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");
@@ -79,9 +79,10 @@ describe("buildMagicContextSection — subagent mode", () => {
         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("Your context is a desk");
+        expect(out).toContain("§N§ tag");
         expect(out).toContain("ctx_reduce");
-        expect(out).toContain("newest token-mass window");
+        expect(out).toContain("newest tags are protected");
     });
 
     it("OMITS the long-term-partner frame and primary-only guidance", () => {
@@ -99,7 +100,7 @@ describe("buildMagicContextSection — subagent mode", () => {
         const withSeven = buildMagicContextSection(null, 7, true, false, false, false, true);
         const withTwenty = buildMagicContextSection(null, 20, true, false, false, false, true);
         expect(withSeven).toBe(withTwenty);
-        expect(withSeven).toContain("newest token-mass window");
+        expect(withSeven).toContain("newest tags are protected");
     });
 
     it("is much shorter than the full primary block", () => {
@@ -132,8 +133,8 @@ describe("buildMagicContextSection: memory gating", () => {
             true,
         );
         expect(memOn).toBe(legacy);
-        expect(memOn).toContain("Use `ctx_memory`");
-        expect(memOn).toContain("**Save to memory proactively**");
+        expect(memOn).toContain("`<project-memory>` is the pinboard");
+        expect(memOn).toContain("`ctx_memory` pins a new one");
     });
 
     it("memory OFF drops ALL ctx_memory guidance but keeps ctx_search", () => {
@@ -149,10 +150,8 @@ describe("buildMagicContextSection: memory gating", () => {
             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`");
+        expect(off).not.toContain("pinboard");
+        expect(off).toContain("`ctx_search` searches the archive");
     });
 
     it("memory OFF gates the guidance in no-reduce mode too", () => {
@@ -168,7 +167,7 @@ describe("buildMagicContextSection: memory gating", () => {
             false,
         );
         expect(off).not.toContain("ctx_memory");
-        expect(off).toContain("Use `ctx_search`");
+        expect(off).toContain("`ctx_search` searches the archive");
     });
 });
 
@@ -247,15 +246,8 @@ describe("buildMagicContextSection — compaction-off guidance variant (#266 S4)
         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`");
+        expect(out).not.toContain("§N§");
+        expect(out).not.toContain("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
@@ -275,11 +267,9 @@ describe("buildMagicContextSection — compaction-off guidance variant (#266 S4)
 
     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("ctx_expand(start, end)");
         expect(out).toContain("session-history");
-        expect(out).toContain("message ordinals");
+        expect(out).toContain("heading is a pointer into the archive");
     });
 
     it("the reduce variant DOES advertise §N§ and ctx_reduce (contrast for the off-mode assertion)", () => {
@@ -289,7 +279,7 @@ describe("buildMagicContextSection — compaction-off guidance variant (#266 S4)
         // 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");
+        expect(reduce).toContain("arrives with a §N§ tag");
     });
 });
 
@@ -333,8 +323,8 @@ describe("buildMagicContextSection — prompt-surface composition", () => {
 
         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("### Your desk");
+        expect(light).toContain("Stamp as soon as an item has served its purpose, silently");
         expect(light).toContain("DO NOT mimic this style");
         expect(light).toContain("Keep code, identifiers, file paths");
         expect(light).not.toContain("### Reduction Triggers");
@@ -364,26 +354,26 @@ describe("buildMagicContextSection — prompt-surface composition", () => {
             );
 
         const memoryOff = light({ memory: false });
-        expect(memoryOff).not.toContain("Use `ctx_memory`");
+        expect(memoryOff).not.toContain("`ctx_memory` pins");
         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");
+        expect(noReduce).not.toContain("§N§");
+        expect(noReduce.slice(noReduce.indexOf("### Your desk"))).not.toContain("ctx_reduce");
 
         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("a `surface_condition` leaves the note");
+        expect(gatedOff).not.toContain("<!-- +Xm -->");
         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("a `surface_condition` leaves the note");
+        expect(gatedOn).toContain("<!-- +Xm -->");
         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("Your context is a desk");
         expect(subagent).toContain("[dropped §N§]");
         expect(subagent).not.toContain("long-term partner");
         expect(subagent).not.toContain("ctx_search");
@@ -407,10 +397,10 @@ describe("buildMagicContextSection — prompt-surface composition", () => {
 
         expect(output.startsWith(override)).toBe(true);
         expect(output.match(/^## Magic Context$/gm)).toHaveLength(1);
-        expect(output).toContain("**Temporal awareness**");
+        expect(output).toContain("<!-- +Xm -->");
         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(
+        expect(output.indexOf("<!-- +Xm -->")).toBeGreaterThan(
             output.indexOf("User-owned primary guidance."),
         );
         expect(output).not.toContain("### Reduction Triggers");
@@ -432,7 +422,7 @@ describe("buildMagicContextSection — prompt-surface composition", () => {
             "## Magic Context\n\nPrimary override must not reach subagents.",
         );
 
-        expect(output).toContain("§N§ identifiers");
+        expect(output).toContain("§N§ tag");
         expect(output).not.toContain("Primary override must not reach subagents");
     });
 });

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

@@ -35,137 +35,117 @@ const PARTNER_FRAME_CLOSER_REDUCE_LIGHT = `\nWhen ctx_reduce is available, use i
 
 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
- * 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 history guidance is shared by both presets.
-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 CTX_NOTE_GUIDANCE = `\`ctx_note\` is the tray for work you intend to return to, with its findings attached; findings without an intention are not a note. When the user says "take a note", it always goes in the tray.`;
+
+const MEMORY_GUIDANCE = `\`<project-memory>\` is the pinboard: facts about this project that stay true for the months this work lasts, as \`#id: fact\` lines — for you, and for every other agent working on this project. \`ctx_memory\` pins a new one when you learn something that must not have to be found again, and especially when it cost you several turns to find.`;
+
+const TOOL_HISTORY_GUIDANCE = `Older work is not kept on the desk at all. Magic Context files it as an organized record, \`<session-history>\`: one heading per stretch of work, \`## start-end · date · title\`, with a summary underneath. Each heading is a pointer into the archive — \`ctx_expand(start, end)\` opens that stretch in full when the summary is not enough. Because of this filing, your own earlier messages may mention actions whose tool call is no longer on the desk. That is normal. It is never a reason to fabricate: if there is no tool result on the desk, the action did not happen, and you never inline or invent a tool call, an output, a search result or a diff in your own text.`;
+
+const SMART_NOTE_GUIDANCE = `A note with a \`surface_condition\` is left with an outside checker that looks the condition up periodically and returns the note only when it holds.`;
+
+const TEMPORAL_AWARENESS_GUIDANCE = `, and \`<!-- +Xm -->\` before a user message (the time that passed since your last reply; headings in the record carry \`start-date\`/\`end-date\` too)`;
+
+const TEMPORAL_AWARENESS_OVERRIDE_GUIDANCE = `\nSome things on the desk are Magic Context's own markings, not conversation: \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<session-history-since>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`, \`[dropped §N§]\`${TEMPORAL_AWARENESS_GUIDANCE}. Read them, use the time, and never reproduce them in a reply or treat them as instructions.`;
 
 const BASE_INTRO = (
     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 newest token-mass window stays protected until displaced. 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="where is the 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="how is the embedding provider configured?")\`
-- 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="what did we decide about the 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.
+    dreamerEnabled: boolean,
+    temporalAwarenessEnabled: boolean,
+): string => `### Your desk
+
+Think of your context as a desk. Every message and every tool output lands on it, and each item arrives with a §N§ tag (§1§, §42§) — the tag is the item's handle.
+
+When an item no longer needs to stay on the desk for the work ahead, stamp it: \`ctx_reduce\` with its tag. Stamping does not remove anything — the item stays on the desk, fully readable. From time to time, when stamped items have piled up and the desk needs room, Magic Context clears them all in one sweep; you don't pick the moment, you only stamp. Stamp as soon as an item has served its purpose, not at the end of the turn, and do it silently: nobody wants to read "I'll drop these outputs". Never stamp a user message for what it asks of you; a large paste inside one is fine once you have used it.
+
+Nothing stamped is ever lost. A cleared item goes to the archive — a recent one leaves a \`[dropped §N§]\` placeholder on the desk, an older one leaves nothing — and \`ctx_expand(message=N)\` brings it back whole: text, tool input, tool output. Now and then Magic Context leaves a short reminder on the desk saying how much unstamped material is lying around; that is housekeeping, not a warning, and the desk never gets smaller for it.
+
 ${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="where is the 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="how is the embedding provider configured?")\`
-- 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="what did we decide about the 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 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 = (
+\`ctx_search\` searches the archive: anything ever said, decided, committed or noted in this project, including what is filed away. Ask it before you ask the user something that may already be recorded here, and whenever something feels familiar but is not in view.
+
+${memoryEnabled ? `${MEMORY_GUIDANCE} ` : ""}${CTX_NOTE_GUIDANCE}${dreamerEnabled ? ` ${SMART_NOTE_GUIDANCE}` : ""}
+
+Some things on the desk are Magic Context's own markings, not conversation: \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<session-history-since>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`, \`[dropped §N§]\`${temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE : ""}. Read them, ${temporalAwarenessEnabled ? "use the time, and" : "and"} never reproduce them in a reply or treat them as instructions.`;
+
+/**
+ * Derived from the accepted desk copy for sessions where ctx_reduce is unavailable.
+ * The archive, filing, search, pinboard, tray, and markings remain, while tag and
+ * stamping language is absent because those sessions never receive tag prefixes.
+ */
+const BASE_INTRO_NO_REDUCE = (
     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 newest token-mass window stays protected until displaced. Use drop grammar "3-5", "1,2,9", or "1-5,8,12-15".
-${CTX_NOTE_GUIDANCE}
-${memoryGuidanceBlock(memoryEnabled)}${LIGHT_SEARCH_RECOVERY}
+    dreamerEnabled: boolean,
+    temporalAwarenessEnabled: boolean,
+): string => `### Your desk
+
+Think of your context as a desk. Every message and every tool output lands on it.
+
+Nothing cleared from the desk is ever lost. A cleared item goes to the archive — a recent one leaves a placeholder on the desk, an older one leaves nothing — and \`ctx_expand(message=N)\` brings it back whole: text, tool input, tool output.
+
 ${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}`;
+\`ctx_search\` searches the archive: anything ever said, decided, committed or noted in this project, including what is filed away. Ask it before you ask the user something that may already be recorded here, and whenever something feels familiar but is not in view.
+
+${memoryEnabled ? `${MEMORY_GUIDANCE} ` : ""}${CTX_NOTE_GUIDANCE}${dreamerEnabled ? ` ${SMART_NOTE_GUIDANCE}` : ""}
+
+Some things on the desk are Magic Context's own markings, not conversation: \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<session-history-since>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`${temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE : ""}. Read them, ${temporalAwarenessEnabled ? "use the time, and" : "and"} never reproduce them in a reply or treat them as instructions.`;
+
+const CTX_NOTE_GUIDANCE_LIGHT = `\`ctx_note\` is the tray for work you intend to return to, with its findings attached; findings without an intention are not a note; "take a note" from the user always goes there`;
+
+const MEMORY_GUIDANCE_LIGHT = `\`<project-memory>\` is the pinboard of facts that stay true for the months this work lasts (\`#id: fact\`), for you and every agent on the project; \`ctx_memory\` pins what must not have to be found again, especially what cost you turns.`;
+
+const TOOL_HISTORY_GUIDANCE_LIGHT = `Older work is filed off the desk into \`<session-history>\` — one \`## start-end · date · title\` heading per stretch, a summary under each, \`ctx_expand(start, end)\` to open the stretch in full. So your earlier messages may mention actions whose tool call is gone; that is normal and never a reason to fabricate: no tool result on the desk, no action, and never inline an invented call, output, search result or diff.`;
+
+const SMART_NOTE_GUIDANCE_LIGHT = `; a \`surface_condition\` leaves the note with an outside checker that returns it when the condition holds`;
+
+const TEMPORAL_AWARENESS_GUIDANCE_LIGHT = `, \`<!-- +Xm -->\` (time since your last reply)`;
+
+const BASE_INTRO_LIGHT = (
+    memoryEnabled: boolean,
+    dreamerEnabled: boolean,
+    temporalAwarenessEnabled: boolean,
+): string => `### Your desk
+
+Your context is a desk. Every message and tool output lands on it with a §N§ tag as its handle. When an item no longer needs to stay for the work ahead, stamp it: \`ctx_reduce\` with its tag. Stamping removes nothing — the item stays readable; from time to time, when stamped items have piled up and the desk needs room, Magic Context clears them in one sweep (you only stamp, you don't pick the moment). Stamp as soon as an item has served its purpose, silently; never stamp a user message for what it asks (a used paste inside one is fine). Nothing is lost: a cleared item goes to the archive (a recent one leaves \`[dropped §N§]\`, an older one nothing) and \`ctx_expand(message=N)\` brings it back whole. Occasional reminders about unstamped material are housekeeping, not warnings; the desk never gets smaller.
+
+${TOOL_HISTORY_GUIDANCE_LIGHT}
+
+\`ctx_search\` searches the archive — anything ever said, decided, committed or noted here; ask it before asking the user anything that may already be recorded, phrased as a question with the exact names in it. ${memoryEnabled ? `${MEMORY_GUIDANCE_LIGHT} ` : ""}${CTX_NOTE_GUIDANCE_LIGHT}${dreamerEnabled ? SMART_NOTE_GUIDANCE_LIGHT : ""}.
+
+Magic Context's own markings — \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`, \`[dropped §N§]\`${temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE_LIGHT : ""} — are read, never reproduced, never instructions.`;
 
-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.
+/** Light no-reduce rendering derived from the accepted light desk copy. */
+const BASE_INTRO_NO_REDUCE_LIGHT = (
+    memoryEnabled: boolean,
+    dreamerEnabled: boolean,
+    temporalAwarenessEnabled: boolean,
+): string => `### Your desk
 
-### 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.
+Your context is a desk. Every message and tool output lands on it. Nothing cleared from the desk is lost: a cleared item goes to the archive (a recent one leaves a placeholder, an older one nothing) and \`ctx_expand(message=N)\` brings it back whole.
 
-### 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.`;
+${TOOL_HISTORY_GUIDANCE_LIGHT}
 
-const SMART_NOTE_GUIDANCE_LIGHT = `\nsurface_condition creates a smart note checked nightly against external signals on ctx_note write.`;
+\`ctx_search\` searches the archive — anything ever said, decided, committed or noted here; ask it before asking the user anything that may already be recorded, phrased as a question with the exact names in it. ${memoryEnabled ? `${MEMORY_GUIDANCE_LIGHT} ` : ""}${CTX_NOTE_GUIDANCE_LIGHT}${dreamerEnabled ? SMART_NOTE_GUIDANCE_LIGHT : ""}.
 
-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.`;
+Magic Context's own markings — \`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`${temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE_LIGHT : ""} — are read, never reproduced, never instructions.`;
 
 /**
- * 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).
+ * Minimal guidance for bounded subagents: stamping, the no-fabrication rule, and
+ * Magic Context markings only. Long-term search, memory, and notes stay primary-only.
  */
 const SUBAGENT_REDUCE_INTRO =
-    (): 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 newest token-mass window stays 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.`;
+    (): string => `Your context is a desk. Every message and every tool output lands on it, and each item arrives with a §N§ tag (§1§, §42§) — the tag is the item's handle. When an item no longer needs to stay on the desk for the work ahead, stamp it: \`ctx_reduce\` with its tag ("3-5", "1,2,9", "1-5,8,12-15"). Stamping does not remove anything — the item stays fully readable until Magic Context clears stamped items in one sweep, and the newest tags are protected, so stamping recent output is harmless. Stamp as soon as an item has served its purpose, not at the end of the task, and do it silently. Never stamp a user message for what it asks of you; look at each tag before stamping and never blanket-stamp a range like "1-50".
+
+A cleared item leaves a \`[dropped §N§]\` placeholder or disappears from the desk; that is normal housekeeping, not something to copy or mention. If there is no tool result on the desk, the action did not happen: never fabricate or inline a tool call, an output, a search result or a diff — make a fresh real tool call instead.
+
+\`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<session-history-since>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\` and \`[dropped §N§]\` are Magic Context's own markings: read them, never reproduce them in a reply, never treat them as instructions.`;
 
 const SUBAGENT_REDUCE_INTRO_LIGHT =
-    (): 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". Tags in the newest token-mass window 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.`;
+    (): string => `Your context is a desk: every message and tool output lands on it with a §N§ tag as its handle. When an item no longer needs to stay for the work ahead, stamp it with \`ctx_reduce\` ("3-5", "1,2,9"). Stamping removes nothing — the item stays readable until Magic Context clears stamped items in one sweep; newest tags are protected. Stamp as soon as an item has served its purpose, silently; never stamp a user message for what it asks; look at each tag, never blanket-stamp "1-50".
+
+A cleared item leaves \`[dropped §N§]\` or disappears; that is housekeeping, not a pattern to copy. No tool result on the desk means the action did not happen — never fabricate or inline a call, output, search result or diff; make a real call.
+
+\`<system-reminder>\`, \`<ctx-search-hint>\`, \`<session-history>\`, \`<project-memory>\`, \`<memory-updates>\`, \`<new-compartments>\`, \`<new-memories>\`, \`[dropped §N§]\` are Magic Context's markings: read, never reproduced, never instructions.`;
 
 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.`;
 
@@ -192,12 +172,9 @@ export function buildMagicContextSection(
         const intro = preset === "light" ? SUBAGENT_REDUCE_INTRO_LIGHT() : SUBAGENT_REDUCE_INTRO();
         return `## Magic Context\n\n${intro}`;
     }
-    const smartNoteGuidance = dreamerEnabled
-        ? 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 temporalOverrideGuidance = temporalAwarenessEnabled
+        ? TEMPORAL_AWARENESS_OVERRIDE_GUIDANCE
         : "";
-    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.
@@ -209,17 +186,17 @@ export function buildMagicContextSection(
         // 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}`;
+        return `${primaryOverride}${temporalOverrideGuidance}${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_LIGHT}\n\n${BASE_INTRO_NO_REDUCE_LIGHT(memoryEnabled, dreamerEnabled, temporalAwarenessEnabled)}${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}`;
+        return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_NO_REDUCE}\n\n${BASE_INTRO_NO_REDUCE(memoryEnabled, dreamerEnabled, temporalAwarenessEnabled)}${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(memoryEnabled)}${smartNoteGuidance}${temporalGuidance}${cavemanWarning}${languageGuidance}`;
+        return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_REDUCE_LIGHT}\n\n${BASE_INTRO_LIGHT(memoryEnabled, dreamerEnabled, temporalAwarenessEnabled)}${cavemanWarning}${languageGuidance}`;
     }
-    return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_REDUCE}\n\n${BASE_INTRO(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}`;
+    return `## Magic Context\n\n${LONG_TERM_PARTNER_FRAME}\n${PARTNER_FRAME_CLOSER_REDUCE}\n\n${BASE_INTRO(memoryEnabled, dreamerEnabled, temporalAwarenessEnabled)}${cavemanWarning}${languageGuidance}`;
 }

package/src/agents/permissions.test.ts

@@ -125,10 +125,10 @@ describe("applyDisallowedTools", () => {
 });
 
 describe("DREAMER_CURATE_ALLOWED_TOOLS (base dreamer = curate only)", () => {
-    it("is ctx_memory ONLY — curate edits the memory store and reads no code", () => {
+    it("allows only the two memory tools — curate edits and enumerates the memory store", () => {
         // 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"]);
+        expect([...DREAMER_CURATE_ALLOWED_TOOLS]).toEqual(["ctx_memory", "ctx_memory_list"]);
     });
 
     it("does NOT include any codebase / shell / file-write tool", () => {
@@ -150,24 +150,22 @@ describe("DREAMER_CURATE_ALLOWED_TOOLS (base dreamer = curate only)", () => {
 });
 
 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",
-        ]) {
+    it("includes read-only source investigation tools for doc proposals", () => {
+        for (const tool of ["read", "grep", "glob", "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"]) {
+    it("denies write, shell and memory tools", () => {
+        for (const denied of [
+            "bash",
+            "write",
+            "edit",
+            "ctx_memory",
+            "ctx_search",
+            "ctx_note",
+            "task",
+        ]) {
             expect(DREAMER_DOCS_ALLOWED_TOOLS).not.toContain(denied);
         }
     });
@@ -185,24 +183,22 @@ describe("integration: full hidden-agent permission shape", () => {
         });
     });
 
-    it("base dreamer (curate) permission object: `*` denied + ctx_memory only", () => {
+    it("base dreamer permission object denies all except the two memory tools", () => {
         const perm = buildAllowOnlyPermission(DREAMER_CURATE_ALLOWED_TOOLS);
         expect(perm).toEqual({
             "*": "deny",
             ctx_memory: "allow",
+            ctx_memory_list: "allow",
         });
     });
 
-    it("dreamer-docs permission object: `*` denied + repo-exploration + write/edit + aft_* (no memory)", () => {
+    it("dreamer-docs permission object denies writes and allows read-only source tools", () => {
         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",