mason: improve Pi todowrite UX

Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>

Author: ualtinok

CONFIGURATION.md

@@ -110,6 +110,7 @@ Higher-tier models with longer cache windows benefit from a longer TTL. Setting
 | `commit_cluster_trigger` | `object` | See below | Controls the commit-cluster historian trigger. |
 | `system_prompt_injection` | `object` | See below | Controls whether and where Magic Context augments the system prompt; lets you opt specific agents out. |
 | `keep_subagents` | `boolean` | `false` | Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success, so their full transcript stays in the host session store for inspection. Kept sessions accumulate until cleared manually — leave `false` for normal use. |
+| `todowrite` | `object` | See below | **Pi only.** Controls Magic Context's built-in `todowrite` tool and persistent task overlay. OpenCode has its own built-in `todowrite`, so this setting has no effect there. |
 | `sqlite` | `object` | See below | Per-connection SQLite tuning for Magic Context's own `context.db`. |
 
 ### `language`
@@ -162,6 +163,26 @@ Controls whether and where Magic Context augments the system prompt (its guidanc
 - **`enabled`** — when `false`, NO injection happens for ANY agent. Global escape hatch; Magic Context's transform and compaction still run, but nothing is added to the system prompt.
 - **`skip_signatures`** — substring opt-out list. If an agent's system prompt contains any of these strings, Magic Context skips ALL injection for that call. Use it to exempt a specific custom agent by putting the signature (e.g. the default `<!-- magic-context: skip -->`) in that agent's prompt.
 
+### `todowrite` (Pi only)
+
+Pi does not ship a built-in `todowrite` tool, so Magic Context registers an OpenCode-parity task-list tool by default. Disable it if another Pi extension already provides todo UX:
+
+```jsonc
+{
+  "todowrite": {
+    "enabled": true,  // default: true
+    "overlay": true   // default: true
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Register Magic Context's Pi `todowrite` tool and `/todos` command. Set `false` when using another todo extension. |
+| `overlay` | `boolean` | `true` | Show the persistent todo overlay above the editor while tasks are active. |
+
+Pi registers tools, slash commands, and widgets once at extension boot. If you `/cd` into a project with a different `todowrite.enabled` value, run `/reload` or restart Pi for the tool surface to change.
+
 ### `sqlite`
 
 Per-connection PRAGMAs applied to Magic Context's own `context.db` at open. These tune SQLite's runtime behaviour only — they do not change the schema or what is stored, and they do not touch OpenCode's or Pi's databases.

assets/magic-context.schema.json

@@ -1209,6 +1209,26 @@
       "description": "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect.",
       "type": "boolean"
     },
+    "todowrite": {
+      "default": {
+        "enabled": true,
+        "overlay": true
+      },
+      "description": "Pi-only todowrite tool and overlay controls. Pi registers tools and widgets at extension boot, so changing this after /cd requires /reload or restart.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "description": "Pi only: register Magic Context's todowrite task-list tool. Disable if you use your own todo extension. OpenCode ships its own built-in todowrite; this setting has no effect there.",
+          "type": "boolean"
+        },
+        "overlay": {
+          "default": true,
+          "description": "Pi only: show the persistent todo overlay above the editor while tasks are active.",
+          "type": "boolean"
+        }
+      }
+    },
     "smart_drops": {
       "default": false,
       "description": "Content-aware reclaim of provably-superseded tool output, layered on the existing execute-pass auto-drop. When on: superseded todowrite (keep newest 1), spent ctx_reduce (keep newest 5), and zero-value meta (bash_status, bash_kill, ctx_note read/dismiss) outputs are dropped; older edits to a file are compressed to a filePath-preserving marker while the newest edit per file stays full. Only acts on passes already busting the cache, so it never originates a cache bust. Honors the protected-tag reserve. Experimental: opt-in, default off until cache stability is proven; when off the wire is byte-identical to the positional-only reclaim. Requires a restart.",

packages/dashboard/src/components/ConfigEditor/ConfigEditor.tsx

@@ -1748,6 +1748,14 @@ function ConfigForm(props: {
               return v == null ? true : Boolean(v);
             };
             const keepSubagents = () => Boolean(getNestedValue(formData(), "keep_subagents"));
+            const todowrite = () =>
+              (getNestedValue(formData(), "todowrite") as
+                | { enabled?: boolean; overlay?: boolean }
+                | undefined) ?? {};
+            const todowriteEnabled = () => todowrite().enabled ?? true;
+            const todowriteOverlay = () => todowrite().overlay ?? true;
+            const setTodowrite = (patch: Record<string, unknown>) =>
+              handleFieldChange("todowrite", { ...todowrite(), ...patch });
             const smartDrops = () => Boolean(getNestedValue(formData(), "smart_drops"));
             const sqlite = () =>
               (getNestedValue(formData(), "sqlite") as
@@ -1823,6 +1831,55 @@ function ConfigForm(props: {
                     </label>
                   </div>
 
+                  {/* Pi todowrite */}
+                  <div class="config-field">
+                    <div class="config-field-header">
+                      <span class="config-field-label">Pi Todowrite Tool</span>
+                      <span class="config-field-key">todowrite.enabled</span>
+                    </div>
+                    <span class="config-field-desc">
+                      Register Magic Context&apos;s Pi <code>todowrite</code> task-list tool.
+                      Disable this if you use another Pi todo extension. OpenCode has its own
+                      built-in todowrite, so this setting only affects Pi. Requires /reload or
+                      restart after changing.
+                    </span>
+                    <label class="toggle-switch">
+                      <input
+                        type="checkbox"
+                        checked={todowriteEnabled()}
+                        onChange={(e) => setTodowrite({ enabled: e.currentTarget.checked })}
+                      />
+                      <span class="toggle-slider" />
+                      <span class="toggle-label">
+                        {todowriteEnabled() ? "Enabled" : "Disabled"}
+                      </span>
+                    </label>
+                  </div>
+
+                  <Show when={todowriteEnabled()}>
+                    <div class="config-field">
+                      <div class="config-field-header">
+                        <span class="config-field-label">Pi Todo Overlay</span>
+                        <span class="config-field-key">todowrite.overlay</span>
+                      </div>
+                      <span class="config-field-desc">
+                        Show the persistent todo overlay above the editor while tasks are active.
+                        The /todos command and tool remain available when only the overlay is off.
+                      </span>
+                      <label class="toggle-switch">
+                        <input
+                          type="checkbox"
+                          checked={todowriteOverlay()}
+                          onChange={(e) => setTodowrite({ overlay: e.currentTarget.checked })}
+                        />
+                        <span class="toggle-slider" />
+                        <span class="toggle-label">
+                          {todowriteOverlay() ? "Enabled" : "Disabled"}
+                        </span>
+                      </label>
+                    </div>
+                  </Show>
+
                   {/* Smart drops */}
                   <div class="config-field">
                     <div class="config-field-header">

packages/dashboard/src/components/ConfigEditor/config-field-coverage.ts

@@ -63,6 +63,7 @@ export const RENDERED_PREFIXES: readonly string[] = [
   // Advanced
   "auto_update",
   "keep_subagents",
+  "todowrite",
   "smart_drops",
   "sqlite",
   "system_prompt_injection.enabled",

packages/docs/src/content/docs/reference/configuration.md

@@ -36,6 +36,9 @@ Global on/off switches for the plugin and its agent-facing surface.
 | `language` | string | — | Output language for Magic Context's generated content and guidance, as a 2-letter ISO 639-1 code (e.g. "tr", "es", "de", "ja", "pt"). When set, the historian, dreamer, sidekick, and the agent-guidance block instruct the model to write its PROSE in this language while keeping all structural tokens (XML tags, the five memory category names, code identifiers, file paths) in English. USER-LEVEL ONLY (ignored in project config for security). Unset = today's behavior (model mirrors the conversation; English scaffolding). Changing it triggers one cache re-materialization; existing compartments/memories keep their original language until naturally rewritten. |
 | `auto_update` | boolean | — | Enable automatic npm self-update checks for the OpenCode plugin. Security: USER-only in config loader, so hostile project configs cannot suppress updates. |
 | `keep_subagents` | boolean | `false` | Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect. |
+| `todowrite` | object | — | Pi-only todowrite tool and overlay controls. Pi registers tools and widgets at extension boot, so changing this after /cd requires /reload or restart. |
+| `todowrite.enabled` | boolean | `true` | Pi only: register Magic Context's todowrite task-list tool. Disable if you use your own todo extension. OpenCode ships its own built-in todowrite; this setting has no effect there. |
+| `todowrite.overlay` | boolean | `true` | Pi only: show the persistent todo overlay above the editor while tasks are active. |
 
 ## Context management
 

packages/pi-plugin/src/index.ts

@@ -143,6 +143,11 @@ import {
 } from "./system-prompt";
 import { withTimeout } from "./timeout";
 import { registerMagicContextTools } from "./tools";
+import {
+	registerTodoOverlay,
+	registerTodoStateLifecycle,
+	setTodoSnapshot,
+} from "./tools/todo-view-pi";
 
 const PREFIX = "[magic-context][pi]";
 
@@ -737,12 +742,19 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
 	const bootProjectDeps = buildProjectDeps(projectDir, projectIdentity, config);
 	projectDepsByDir.set(projectDir, bootProjectDeps);
+	const todowriteEnabled = bootProjectDeps.config.todowrite.enabled !== false;
+	const todowriteOverlayEnabled =
+		todowriteEnabled && bootProjectDeps.config.todowrite.overlay !== false;
 
 	// Register the agent-facing tools. Reuses the same business logic
 	// the OpenCode plugin uses (insertMemory, unifiedSearch, addNote, …)
 	// via the shared cortexkit DB. Cross-harness memory sharing is automatic
 	// because both plugins resolve the same project identity for the same
 	// directory.
+	// Pi registers tools, commands, and widgets once at extension boot. Therefore
+	// `todowrite.enabled` follows the boot project's config: after `/cd` into a
+	// project with a different value, users need `/reload` or a Pi restart for the
+	// tool/command/overlay surface to change, matching Pi's registration lifecycle.
 	registerMagicContextTools(pi, {
 		db,
 		ensureProjectRegistered: ensureProjectRegisteredFromPiDirectory,
@@ -771,9 +783,28 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		dreamerEnabled: isDreamerRunnable(config),
 		resolveDreamerEnabled: (ctx) =>
 			resolveCurrentProjectDeps(ctx).dreamerEnabled,
+		todowriteEnabled,
 	});
 	info(
-		"registered tools: ctx_search, ctx_memory, ctx_note, ctx_expand, ctx_reduce",
+		todowriteEnabled
+			? "registered tools: ctx_search, ctx_memory, ctx_note, ctx_expand, todowrite, ctx_reduce; registered /todos"
+			: "registered tools: ctx_search, ctx_memory, ctx_note, ctx_expand, ctx_reduce (todowrite disabled)",
+	);
+
+	const readLastTodoState = (sessionId: string) =>
+		getOrCreateSessionMeta(db, sessionId).lastTodoState;
+	if (todowriteEnabled) {
+		registerTodoStateLifecycle(pi, { readLastTodoState });
+	}
+	const todoOverlay = todowriteOverlayEnabled
+		? registerTodoOverlay(pi, {
+				readLastTodoState,
+			})
+		: undefined;
+	info(
+		todowriteOverlayEnabled
+			? "registered todowrite overlay"
+			: "registered todowrite overlay: DISABLED (todowrite.enabled=false or todowrite.overlay=false)",
 	);
 
 	// Register the per-LLM-call transform pipeline. Tags eligible message
@@ -1439,6 +1470,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				const sessionMeta = Array.isArray(todos)
 					? getOrCreateSessionMeta(db, sessionId)
 					: null;
+				if (todowriteEnabled && Array.isArray(todos)) {
+					setTodoSnapshot(sessionId, todos);
+					todoOverlay?.update(sessionId);
+				}
 
 				// Synthetic-todowrite snapshot capture (Pi parity with
 				// OpenCode hook-handlers.ts:386-401). Persist normalized
@@ -1714,6 +1749,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 							if (!Array.isArray(todos)) continue;
 							const normalized = normalizeTodoStateJson(todos);
 							if (normalized === null) continue;
+							if (todowriteEnabled) {
+								setTodoSnapshot(sessionId, todos);
+								todoOverlay?.update(sessionId);
+							}
 							updateSessionMeta(db, sessionId, {
 								lastTodoState: normalized,
 							});

packages/pi-plugin/src/subagent-entry.ts

@@ -110,10 +110,12 @@ export default function magicContextSubagentExtension(pi: ExtensionAPI): void {
 				// child session, so session-scoped ctx_note/ctx_expand would write
 				// orphaned notes / expand an empty transcript. Drop them; keep ctx_search.
 				sessionScopedToolsDisabled: true,
+				todowriteEnabled: cfg.todowrite.enabled !== false,
+				todowriteCommandEnabled: false,
 			});
 
 			log(
-				`[pi-subagent] registered tools: ctx_search${dreamerActionsEnabled ? ", ctx_memory" : ""}` +
+				`[pi-subagent] registered tools: ctx_search${dreamerActionsEnabled ? ", ctx_memory" : ""}${cfg.todowrite.enabled !== false ? ", todowrite" : ""}` +
 					` (ctx_note/ctx_expand omitted: --no-session child;` +
 					` memory=${cfg.memory.enabled}, embedding=${cfg.embedding.provider !== "off"},` +
 					` git_commits=${cfg.memory.git_commit_indexing.enabled}, dreamer_actions=${dreamerActionsEnabled})`,

packages/pi-plugin/src/tools/index.test.ts

@@ -8,22 +8,29 @@ describe("registerMagicContextTools", () => {
 		const db = createTestDb();
 		try {
 			const registered: string[] = [];
+			const commands: string[] = [];
 			const pi = {
 				registerTool: (tool: { name: string }) => {
 					registered.push(tool.name);
 				},
+				registerCommand: (name: string) => {
+					commands.push(name);
+				},
 			} as never;
 
 			registerMagicContextTools(pi, {
 				db,
 				memoryToolEnabled: false,
 				sessionScopedToolsDisabled: true,
+				todowriteCommandEnabled: false,
 			});
 
 			expect(registered).toContain("ctx_search");
 			expect(registered).not.toContain("ctx_memory");
 			expect(registered).not.toContain("ctx_note");
 			expect(registered).not.toContain("ctx_expand");
+			expect(registered).toContain("todowrite");
+			expect(commands).not.toContain("todos");
 		} finally {
 			closeQuietly(db);
 		}
@@ -43,6 +50,7 @@ describe("registerMagicContextTools", () => {
 				}) => {
 					registered.set(tool.name, tool);
 				},
+				registerCommand: () => undefined,
 			} as never;
 
 			registerMagicContextTools(pi, {
@@ -75,4 +83,62 @@ describe("registerMagicContextTools", () => {
 			closeQuietly(db);
 		}
 	});
+
+	it("registers todowrite and /todos by default", () => {
+		const db = createTestDb();
+		try {
+			const registered: string[] = [];
+			const commands: string[] = [];
+			const pi = {
+				registerTool: (tool: { name: string }) => registered.push(tool.name),
+				registerCommand: (name: string) => commands.push(name),
+			} as never;
+
+			registerMagicContextTools(pi, { db });
+
+			expect(registered).toContain("todowrite");
+			expect(commands).toContain("todos");
+		} finally {
+			closeQuietly(db);
+		}
+	});
+
+	it("omits todowrite and /todos when todowrite is disabled", () => {
+		const db = createTestDb();
+		try {
+			const registered: string[] = [];
+			const commands: string[] = [];
+			const pi = {
+				registerTool: (tool: { name: string }) => registered.push(tool.name),
+				registerCommand: (name: string) => commands.push(name),
+			} as never;
+
+			registerMagicContextTools(pi, { db, todowriteEnabled: false });
+
+			expect(registered).toContain("ctx_search");
+			expect(registered).not.toContain("todowrite");
+			expect(commands).not.toContain("todos");
+		} finally {
+			closeQuietly(db);
+		}
+	});
+
+	it("can keep /todos off for lean subagent entries", () => {
+		const db = createTestDb();
+		try {
+			const registered: string[] = [];
+			const commands: string[] = [];
+			const pi = {
+				registerTool: (tool: { name: string }) => registered.push(tool.name),
+				registerCommand: (name: string) => commands.push(name),
+			} as never;
+
+			registerMagicContextTools(pi, { db, todowriteCommandEnabled: false });
+
+			expect(registered).toContain("todowrite");
+			expect(commands).not.toContain("todos");
+		} finally {
+			closeQuietly(db);
+		}
+	});
 });

packages/pi-plugin/src/tools/index.ts

@@ -19,6 +19,7 @@ import { createCtxMemoryTool } from "./ctx-memory";
 import { createCtxNoteTool } from "./ctx-note";
 import { createCtxReduceTool } from "./ctx-reduce";
 import { createCtxSearchTool } from "./ctx-search";
+import { registerTodosCommand } from "./todo-view-pi";
 import { createTodowriteTool } from "./todowrite";
 
 export interface RegisterToolsOptions {
@@ -55,6 +56,10 @@ export interface RegisterToolsOptions {
 	 *  child session, so ctx_note would write notes orphaned under the hidden
 	 *  child id and ctx_expand would expand the child's empty transcript. */
 	sessionScopedToolsDisabled?: boolean;
+	/** When false, omit Magic Context's Pi todowrite tool entirely. */
+	todowriteEnabled?: boolean;
+	/** Main Pi entry registers /todos; lean subagent entries keep commands off. */
+	todowriteCommandEnabled?: boolean;
 }
 
 export function registerMagicContextTools(
@@ -100,13 +105,18 @@ export function registerMagicContextTools(
 		pi.registerTool(createCtxExpandTool({ db: opts.db }));
 	}
 
-	// `todowrite` parity with OpenCode. Pi-coding-agent has no built-in
-	// task list tool, so without this the synthetic-todowrite injector
-	// would never have anything to surface. The tool just captures the
-	// `todos` arg and echoes a pretty-printed JSON ack; `message_end`
-	// in index.ts snapshots `params.todos` into `session_meta.last_todo_state`
-	// for downstream synthesis. See `tools/todowrite.ts` header for rationale.
-	pi.registerTool(createTodowriteTool());
+	if (opts.todowriteEnabled !== false) {
+		// `todowrite` parity with OpenCode. Pi-coding-agent has no built-in
+		// task list tool, so without this the synthetic-todowrite injector
+		// would never have anything to surface. The tool just captures the
+		// `todos` arg and echoes a pretty-printed JSON ack; `message_end`
+		// in index.ts snapshots `params.todos` into `session_meta.last_todo_state`
+		// for downstream synthesis. See `tools/todowrite.ts` header for rationale.
+		pi.registerTool(createTodowriteTool());
+		if (opts.todowriteCommandEnabled !== false) {
+			registerTodosCommand(pi);
+		}
+	}
 
 	// ctx_reduce is session-scoped just like ctx_note/ctx_expand: it resolves the
 	// CURRENT session id at call time. Omit it for `--no-session` children where