@xynogen/pix-todo 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@xynogen/pix-todo",
+	"version": "0.1.0",
+	"description": "Pi tool — durable execution checklist (todo)",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"todo"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-todo"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"typebox": "^1.1.38"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { TodoItem, TodoStatus, TodoTheme } from "./todo.js";
+export { default, renderTodoLines } from "./todo.js";

package/src/todo.test.ts

@@ -0,0 +1,646 @@
+import { describe, expect, test } from "bun:test";
+import registerTodo, { renderTodoLines, type TodoItem } from "./todo.ts";
+
+// Stub theme tags each fragment with its color/bold so assertions can verify
+// which status got which tint, without depending on real ANSI codes.
+const tagTheme = {
+	fg: (color: string, text: string) => `[${color}]${text}[/]`,
+	bold: (text: string) => `<b>${text}</b>`,
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Create a mock ExtensionAPI that captures the registered tool's execute fn. */
+function makeHost(
+	initialEntries: Array<{
+		type: string;
+		customType?: string;
+		data?: unknown;
+	}> = [],
+) {
+	let capturedExecute:
+		| ((
+				id: string,
+				params: Record<string, unknown>,
+		  ) => Promise<{
+				content: Array<{ type: string; text: string }>;
+				isError?: boolean;
+		  }>)
+		| null = null;
+	const appendCalls: Array<{ type: string; data: unknown }> = [];
+	const handlers: Record<
+		string,
+		Array<(event: unknown, ctx?: unknown) => unknown>
+	> = {};
+
+	const pi = {
+		registerTool(def: { name: string; execute: typeof capturedExecute }) {
+			capturedExecute = def.execute;
+		},
+		appendEntry(type: string, data: unknown) {
+			appendCalls.push({ type, data });
+		},
+		on(ev: string, fn: (event: unknown, ctx?: unknown) => unknown) {
+			(handlers[ev] ??= []).push(fn);
+		},
+		async emit(ev: string, event?: unknown, ctx?: unknown) {
+			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		},
+	} as never;
+
+	const sessionManager = {
+		getEntries() {
+			return initialEntries;
+		},
+	};
+
+	return {
+		pi,
+		sessionManager,
+		get execute() {
+			return capturedExecute!;
+		},
+		appendCalls,
+		async emit(ev: string, event?: unknown, ctx?: unknown) {
+			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		},
+	};
+}
+
+async function run(
+	execute: (
+		id: string,
+		params: Record<string, unknown>,
+	) => Promise<{
+		content: Array<{ type: string; text: string }>;
+		isError?: boolean;
+	}>,
+	params: Record<string, unknown>,
+) {
+	return execute("call-1", params);
+}
+
+function text(result: { content: Array<{ type: string; text: string }> }) {
+	return result.content.map((c) => c.text).join("\n");
+}
+
+// ─── parseItems (via set/add) ───────────────────────────────────────────────
+
+describe("todo actions", () => {
+	test("list on empty returns (no todos)", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toBe("(no todos)");
+	});
+
+	test("set creates items from newline text", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, {
+			action: "set",
+			items: "alpha\nbravo\ncharlie",
+		});
+		const out = text(result);
+		expect(out).toContain("Todos 0/3 done");
+		expect(out).toContain("○ 1. alpha");
+		expect(out).toContain("○ 2. bravo");
+		expect(out).toContain("○ 3. charlie");
+	});
+
+	test("set creates items from numbered list", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, {
+			action: "set",
+			items: "1. alpha\n2. bravo",
+		});
+		expect(text(result)).toContain("○ 1. alpha");
+	});
+
+	test("set creates items from bullet list", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, {
+			action: "set",
+			items: "- alpha\n* bravo",
+		});
+		expect(text(result)).toContain("○ 1. alpha");
+		expect(text(result)).toContain("○ 2. bravo");
+	});
+
+	test("set ignores empty lines", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, {
+			action: "set",
+			items: "alpha\n\nbravo\n  \ncharlie",
+		});
+		expect(text(result)).toContain("Todos 0/3 done");
+	});
+
+	test("set with empty items returns error", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "set", items: "" });
+		expect(result.isError).toBe(true);
+		expect(text(result)).toContain("non-empty");
+	});
+
+	test("set with only whitespace returns error", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "set", items: "  \n  " });
+		expect(result.isError).toBe(true);
+	});
+
+	test("set resets ids on re-set", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "first\nsecond" });
+		const result = await run(host.execute, { action: "set", items: "new" });
+		expect(text(result)).toContain("○ 1. new");
+		expect(text(result)).toContain("Todos 0/1 done");
+	});
+
+	test("add appends items", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha" });
+		const result = await run(host.execute, {
+			action: "add",
+			items: "bravo\ncharlie",
+		});
+		const out = text(result);
+		expect(out).toContain("○ 1. alpha");
+		expect(out).toContain("○ 2. bravo");
+		expect(out).toContain("○ 3. charlie");
+		expect(out).toContain("Todos 0/3 done");
+	});
+
+	test("add with ids continuing sequence", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "first\nsecond\nthird" });
+		const result = await run(host.execute, { action: "add", items: "fourth" });
+		expect(text(result)).toContain("○ 4. fourth");
+	});
+
+	test("add with empty items returns error", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "add", items: "" });
+		expect(result.isError).toBe(true);
+		expect(text(result)).toContain("non-empty");
+	});
+
+	test("update changes status", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha\nbravo" });
+		const result = await run(host.execute, {
+			action: "update",
+			id: 1,
+			status: "done",
+		});
+		const out = text(result);
+		expect(out).toContain("● 1. alpha");
+		expect(out).toContain("○ 2. bravo");
+		expect(out).toContain("Todos 1/2 done");
+	});
+
+	test("update changes text", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "old name" });
+		const result = await run(host.execute, {
+			action: "update",
+			id: 1,
+			text: "new name",
+		});
+		expect(text(result)).toContain("○ 1. new name");
+	});
+
+	test("update changes status and text together", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha" });
+		const result = await run(host.execute, {
+			action: "update",
+			id: 1,
+			status: "blocked",
+			text: "alpha (waiting)",
+		});
+		const out = text(result);
+		expect(out).toContain("⊘ 1. alpha (waiting)");
+		expect(out).toContain("Todos 0/1 done");
+	});
+
+	test("update unknown id returns error", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, {
+			action: "update",
+			id: 999,
+			status: "done",
+		});
+		expect(result.isError).toBe(true);
+		expect(text(result)).toContain("999");
+	});
+
+	test("update without status or text does nothing", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "unchanged" });
+		const result = await run(host.execute, { action: "update", id: 1 });
+		expect(text(result)).toContain("○ 1. unchanged");
+	});
+
+	test("clear empties list", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha\nbravo" });
+		const result = await run(host.execute, { action: "clear" });
+		expect(text(result)).toContain("Todos cleared");
+		// next list should show empty
+		const list = await run(host.execute, { action: "list" });
+		expect(text(list)).toBe("(no todos)");
+	});
+
+	test("clear resets id counter", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha\nbravo\ncharlie" });
+		await run(host.execute, { action: "clear" });
+		const result = await run(host.execute, { action: "set", items: "new" });
+		expect(text(result)).toContain("○ 1. new");
+	});
+
+	test("unknown action returns error", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "bogus" });
+		expect(result.isError).toBe(true);
+		expect(text(result)).toContain("Unknown action");
+	});
+
+	test("all status glyphs render correctly", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
+		await run(host.execute, { action: "update", id: 1, status: "pending" });
+		await run(host.execute, { action: "update", id: 2, status: "in_progress" });
+		await run(host.execute, { action: "update", id: 3, status: "done" });
+		await run(host.execute, { action: "update", id: 4, status: "blocked" });
+		const out = text(await run(host.execute, { action: "list" }));
+		expect(out).toContain("○ 1. a");
+		expect(out).toContain("◐ 2. b");
+		expect(out).toContain("● 3. c");
+		expect(out).toContain("⊘ 4. d");
+		expect(out).toContain("Todos 1/4 done");
+	});
+});
+
+// ─── Persistence ────────────────────────────────────────────────────────────
+
+describe("persistence", () => {
+	test("set persists todos", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		host.appendCalls.length = 0;
+		await run(host.execute, { action: "set", items: "alpha\nbravo" });
+		expect(host.appendCalls.length).toBe(1);
+		expect(host.appendCalls[0].type).toBe("todo-state");
+		const data = host.appendCalls[0].data as {
+			todos: Array<{ id: number; text: string; status: string }>;
+			nextTodoId: number;
+		};
+		expect(data.todos).toHaveLength(2);
+		expect(data.nextTodoId).toBe(3);
+	});
+
+	test("add persists todos", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha" });
+		host.appendCalls.length = 0;
+		await run(host.execute, { action: "add", items: "bravo" });
+		expect(host.appendCalls.length).toBe(1);
+	});
+
+	test("update persists todos", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha" });
+		host.appendCalls.length = 0;
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+		expect(host.appendCalls.length).toBe(1);
+	});
+
+	test("clear persists", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		await run(host.execute, { action: "set", items: "alpha" });
+		host.appendCalls.length = 0;
+		await run(host.execute, { action: "clear" });
+		expect(host.appendCalls.length).toBe(1);
+		const data = host.appendCalls[0].data as {
+			todos: Array<unknown>;
+			nextTodoId: number;
+		};
+		expect(data.todos).toEqual([]);
+		expect(data.nextTodoId).toBe(1);
+	});
+});
+
+// ─── Session restore ────────────────────────────────────────────────────────
+
+describe("restore", () => {
+	test("restores todos from last todo-state entry", async () => {
+		const host = makeHost([
+			{
+				type: "custom",
+				customType: "todo-state",
+				data: {
+					todos: [{ id: 1, text: "restored", status: "done" }],
+					nextTodoId: 2,
+				},
+			},
+		]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toContain("● 1. restored");
+		expect(text(result)).toContain("Todos 1/1 done");
+	});
+
+	test("restores nextTodoId so new items continue sequence", async () => {
+		const host = makeHost([
+			{
+				type: "custom",
+				customType: "todo-state",
+				data: {
+					todos: [{ id: 5, text: "existing", status: "pending" }],
+					nextTodoId: 6,
+				},
+			},
+		]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "add", items: "new" });
+		expect(text(result)).toContain("○ 6. new");
+	});
+
+	test("restores nextTodoId from max id when nextTodoId missing", async () => {
+		const host = makeHost([
+			{
+				type: "custom",
+				customType: "todo-state",
+				data: {
+					todos: [
+						{ id: 3, text: "old", status: "done" },
+						{ id: 7, text: "newer", status: "pending" },
+					],
+				},
+			},
+		]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "add", items: "next" });
+		expect(text(result)).toContain("○ 8. next");
+	});
+
+	test("ignores non-todo-state entries", async () => {
+		const host = makeHost([
+			{ type: "message", data: "hello" },
+			{ type: "custom", customType: "other-thing", data: {} },
+			{
+				type: "custom",
+				customType: "todo-state",
+				data: {
+					todos: [{ id: 1, text: "real", status: "pending" }],
+					nextTodoId: 2,
+				},
+			},
+		]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toContain("○ 1. real");
+	});
+
+	test("no todo-state entries starts empty", async () => {
+		const host = makeHost([{ type: "message", data: "hello" }]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toBe("(no todos)");
+	});
+
+	test("empty entries list starts empty", async () => {
+		const host = makeHost([]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toBe("(no todos)");
+	});
+
+	test("restore with empty todos array works", async () => {
+		const host = makeHost([
+			{
+				type: "custom",
+				customType: "todo-state",
+				data: { todos: [], nextTodoId: 1 },
+			},
+		]);
+		registerTodo(host.pi);
+		await host.emit(
+			"session_start",
+			{},
+			{ sessionManager: host.sessionManager },
+		);
+		const result = await run(host.execute, { action: "list" });
+		expect(text(result)).toBe("(no todos)");
+	});
+});
+
+describe("renderTodoLines (colored TUI render)", () => {
+	const items: TodoItem[] = [
+		{ id: 1, text: "alpha", status: "done" },
+		{ id: 2, text: "bravo", status: "in_progress" },
+		{ id: 3, text: "charlie", status: "pending" },
+		{ id: 4, text: "delta", status: "blocked" },
+	];
+
+	test("empty list renders muted placeholder", () => {
+		expect(renderTodoLines([], tagTheme)).toBe("[muted](no todos)[/]");
+	});
+
+	test("tints each glyph by status", () => {
+		const out = renderTodoLines(items, tagTheme);
+		expect(out).toContain("[success]●[/]"); // done
+		expect(out).toContain("[accent]◐[/]"); // in_progress
+		expect(out).toContain("[muted]○[/]"); // pending
+		expect(out).toContain("[error]⊘[/]"); // blocked
+	});
+
+	test("highlights the in-progress row bold + accent", () => {
+		const out = renderTodoLines(items, tagTheme);
+		expect(out).toContain("<b>[accent]2. bravo[/]</b>");
+	});
+
+	test("dims completed rows and uses text color for active-but-not-running", () => {
+		const out = renderTodoLines(items, tagTheme);
+		expect(out).toContain("[muted]1. alpha[/]"); // done body muted
+		expect(out).toContain("[text]3. charlie[/]"); // pending body text
+	});
+
+	test("shows the done/total count header", () => {
+		const out = renderTodoLines(items, tagTheme);
+		expect(out).toContain("[muted]Todos 1/4 done:[/]");
+	});
+});

package/src/todo.ts

@@ -0,0 +1,218 @@
+/**
+ * todo.ts — durable execution checklist tool
+ *
+ * Extracted from the plan extension: the checklist is BUILD-phase execution
+ * state that survives context compaction and session restore (persisted via
+ * appendEntry("todo-state")). It is universal — other tools and workflow
+ * extensions (like plan) drive it — so it lives in pix-core and registers the
+ * `todo` tool. State, persistence, and restore are owned end to end here; the
+ * checklist is seeded by the model via the tool's `set` action.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+export type TodoStatus = "pending" | "in_progress" | "done" | "blocked";
+
+export interface TodoItem {
+	id: number;
+	text: string;
+	status: TodoStatus;
+}
+
+const TODO_GLYPH: Record<TodoStatus, string> = {
+	pending: "○",
+	in_progress: "◐",
+	done: "●",
+	blocked: "⊘",
+};
+
+/** Theme color key per status — drives both glyph and (for active) row tint. */
+const TODO_COLOR: Record<TodoStatus, string> = {
+	pending: "muted",
+	in_progress: "accent",
+	done: "success",
+	blocked: "error",
+};
+
+export type TodoTheme = {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+};
+
+/** Colored checklist for the TUI: glyphs tinted by status, active row bold. */
+export function renderTodoLines(items: TodoItem[], theme: TodoTheme): string {
+	if (!items.length) return theme.fg("muted", "(no todos)");
+	const done = items.filter((t) => t.status === "done").length;
+	const head = theme.fg("muted", `Todos ${done}/${items.length} done:`);
+	const lines = items.map((t) => {
+		const color = TODO_COLOR[t.status];
+		const glyph = theme.fg(color, TODO_GLYPH[t.status]);
+		const body = `${t.id}. ${t.text}`;
+		// Highlight the in-flight task so the eye lands on it first.
+		const label =
+			t.status === "in_progress"
+				? theme.bold(theme.fg("accent", body))
+				: theme.fg(t.status === "done" ? "muted" : "text", body);
+		return `${glyph} ${label}`;
+	});
+	return `${head}\n${lines.join("\n")}`;
+}
+
+const parseItems = (raw: string): string[] =>
+	raw
+		.split("\n")
+		.map((l) => l.replace(/^\s*(?:\d+[.)]|[-*•])\s*/, "").trim())
+		.filter(Boolean);
+
+export default function registerTodo(pi: ExtensionAPI): void {
+	let todos: TodoItem[] = [];
+	let nextTodoId = 1;
+
+	function persistTodos() {
+		pi.appendEntry("todo-state", { todos, nextTodoId });
+	}
+
+	function todoSummary(): string {
+		if (!todos.length) return "(no todos)";
+		const done = todos.filter((t) => t.status === "done").length;
+		const lines = todos.map(
+			(t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`,
+		);
+		return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
+	}
+
+	// Durable execution checklist for BUILD mode. Survives context compaction
+	// and session restore. Workflows like plan instruct the model to seed it
+	// from a plan's "Implementation Phases" so it stays anchored to plan.md.
+	pi.registerTool({
+		name: "todo",
+		label: "Todo",
+		description:
+			"Track BUILD-phase execution progress. Durable across context compaction. Actions: list, set (replace all items from newline/numbered text), add, update (change one item's status), clear.",
+		promptSnippet:
+			"todo(action, items?, id?, status?, text?) — action: list|set|add|update|clear. Use to track implementation progress, especially when executing a plan.",
+		promptGuidelines: [
+			"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
+			"Mark each item in_progress before working it and done when finished via `todo(action:'update', id, status)`.",
+			"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
+		],
+		parameters: Type.Object({
+			action: Type.Union(
+				[
+					Type.Literal("list"),
+					Type.Literal("set"),
+					Type.Literal("add"),
+					Type.Literal("update"),
+					Type.Literal("clear"),
+				],
+				{ description: "Operation to perform" },
+			),
+			items: Type.Optional(
+				Type.String({
+					description:
+						"For set/add: newline-separated or numbered list of todo texts.",
+				}),
+			),
+			id: Type.Optional(
+				Type.Number({ description: "For update: target todo id." }),
+			),
+			status: Type.Optional(
+				Type.Union(
+					[
+						Type.Literal("pending"),
+						Type.Literal("in_progress"),
+						Type.Literal("done"),
+						Type.Literal("blocked"),
+					],
+					{ description: "For update: new status." },
+				),
+			),
+			text: Type.Optional(
+				Type.String({
+					description: "For update: replacement text (optional).",
+				}),
+			),
+		}),
+		renderResult(_result, _options, theme) {
+			return new Text(renderTodoLines(todos, theme as TodoTheme), 0, 0);
+		},
+
+		async execute(_id, params) {
+			// AgentToolResult now requires a `details` field. These todo results have
+			// no structured details, so emit `undefined` via small local helpers.
+			const ok = (text: string) => ({
+				content: [{ type: "text" as const, text }],
+				details: undefined,
+			});
+			const fail = (text: string) => ({
+				content: [{ type: "text" as const, text }],
+				details: undefined,
+				isError: true,
+			});
+			switch (params.action) {
+				case "list":
+					return ok(todoSummary());
+
+				case "set": {
+					const texts = parseItems(params.items ?? "");
+					if (!texts.length) return fail("set requires non-empty `items`.");
+					nextTodoId = 1;
+					todos = texts.map((text) => ({
+						id: nextTodoId++,
+						text,
+						status: "pending" as TodoStatus,
+					}));
+					persistTodos();
+					return ok(todoSummary());
+				}
+
+				case "add": {
+					const texts = parseItems(params.items ?? "");
+					if (!texts.length) return fail("add requires non-empty `items`.");
+					for (const text of texts)
+						todos.push({ id: nextTodoId++, text, status: "pending" });
+					persistTodos();
+					return ok(todoSummary());
+				}
+
+				case "update": {
+					const t = todos.find((x) => x.id === params.id);
+					if (!t) return fail(`No todo with id ${params.id}.`);
+					if (params.status) t.status = params.status;
+					if (params.text) t.text = params.text;
+					persistTodos();
+					return ok(todoSummary());
+				}
+
+				case "clear":
+					todos = [];
+					nextTodoId = 1;
+					persistTodos();
+					return ok("Todos cleared.");
+
+				default:
+					return fail(`Unknown action: ${String(params.action)}`);
+			}
+		},
+	});
+
+	// Restore the checklist from session entries so it survives restart.
+	pi.on("session_start", async (_event, ctx) => {
+		const entries = ctx.sessionManager.getEntries() as Array<{
+			type: string;
+			customType?: string;
+			data?: { todos?: TodoItem[]; nextTodoId?: number };
+		}>;
+		const lastTodo = entries
+			.filter((e) => e.type === "custom" && e.customType === "todo-state")
+			.pop();
+		if (Array.isArray(lastTodo?.data?.todos)) {
+			todos = lastTodo.data.todos;
+			nextTodoId =
+				lastTodo.data.nextTodoId ??
+				todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
+		}
+	});
+}