one-code-extension 0.1.0

package/extensions/system-prompt/environment.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment facts for the system prompt's # Environment section.
+ * Collected once per (cwd, model) and cached so the prompt stays byte-stable
+ * across turns — required for provider prompt caching to pay off.
+ */
+
+import os from "node:os";
+import { findGitRoot } from "../lib/git.ts";
+import { projectMemoryDir } from "../lib/memory.ts";
+
+export interface EnvironmentInfo {
+	cwd: string;
+	isGitRepo: boolean;
+	platform: string;
+	osVersion: string;
+	shell: string;
+	date: string;
+	modelLine: string;
+	/** Per-project auto-memory directory; the memory extension guarantees it exists. */
+	memoryDir: string;
+}
+
+export function collectEnvironment(cwd: string, modelLine: string): EnvironmentInfo {
+	const gitRoot = findGitRoot(cwd);
+	return {
+		cwd,
+		isGitRepo: gitRoot !== undefined,
+		platform: process.platform,
+		osVersion: `${os.type()} ${os.release()}`,
+		shell: process.env.SHELL ? (process.env.SHELL.split("/").pop() ?? "unknown") : "unknown",
+		date: new Date().toISOString().slice(0, 10),
+		modelLine,
+		memoryDir: projectMemoryDir(cwd, os.homedir()),
+	};
+}

package/extensions/system-prompt/index.ts

@@ -0,0 +1,54 @@
+/**
+ * system-prompt extension — replaces pi's default system prompt with the
+ * adapted Claude Code prompt on every turn via before_agent_start.
+ *
+ * The environment block is cached per (cwd, model) so the generated prompt is
+ * byte-stable across turns and provider prompt caching stays effective. The
+ * scratchpad path embeds the session id, so it lives outside that cache —
+ * derived at session_start, constant within the session.
+ */
+
+import { mkdirSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveModelTier } from "../lib/model-tier.ts";
+import { sessionScratchpadDir } from "../lib/scratchpad.ts";
+import { collectEnvironment, type EnvironmentInfo } from "./environment.ts";
+import { buildClaudeCodeSystemPrompt } from "./template.ts";
+
+export default function systemPromptExtension(pi: ExtensionAPI) {
+	let cachedEnv: EnvironmentInfo | undefined;
+	let cachedKey = "";
+	let scratchpad: string | undefined;
+
+	pi.on("session_start", (_event, ctx) => {
+		// The prompt section promises a usable directory, so the extension that
+		// makes the promise creates it. Failure (unwritable /tmp) drops the
+		// section rather than promising a directory writes will error on.
+		const candidate = sessionScratchpadDir(ctx.cwd, ctx.sessionManager.getSessionId());
+		try {
+			mkdirSync(candidate, { recursive: true });
+			scratchpad = candidate;
+		} catch {
+			scratchpad = undefined;
+		}
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		// A named agent (or a `--system-prompt` launch) supplies its own prompt via
+		// customPrompt. Return nothing so pi's own builder uses it verbatim, rather
+		// than clobbering it with the tiered One Code prompt.
+		if (event.systemPromptOptions.customPrompt) return;
+
+		const model = ctx.model;
+		const modelLine = model ? `${model.id} (${model.provider})` : "unknown";
+		// Re-resolved every turn: the model (and so the tier) can change mid-session.
+		const tier = resolveModelTier(model);
+		const key = `${ctx.cwd}|${modelLine}|${tier}`;
+		if (!cachedEnv || cachedKey !== key) {
+			cachedEnv = collectEnvironment(ctx.cwd, modelLine);
+			cachedKey = key;
+		}
+
+		return { systemPrompt: buildClaudeCodeSystemPrompt(event.systemPromptOptions, cachedEnv, tier, scratchpad) };
+	});
+}

package/extensions/system-prompt/template.ts

@@ -0,0 +1,103 @@
+/**
+ * Claude Code system prompt, adapted for One Code, selected by model tier.
+ *
+ * The tier-specific section text lives in `tiers/` (one bundle per tier);
+ * this module is the tier-agnostic composer — it places the dynamic blocks
+ * (tools, memory, environment, scratchpad, project context, skills, cwd trailer)
+ * around the bundle's `lead`/`tail` sections. Sections tied to Anthropic-hosted
+ * features are dropped, and the environment block is generated dynamically.
+ *
+ * For a fixed tier this function must be pure and deterministic: same inputs,
+ * byte-identical output (prompt-cache stability). The frontier bundle reproduces
+ * the pre-tiering prompt exactly.
+ */
+
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { memoryPromptSection } from "../lib/memory.ts";
+import type { PromptTier } from "../lib/model-tier.ts";
+import { scratchpadPromptSection } from "../lib/scratchpad.ts";
+import type { EnvironmentInfo } from "./environment.ts";
+import type { PromptBundle } from "./tiers/common.ts";
+import { frontierBundle } from "./tiers/frontier.ts";
+import { lowBundle } from "./tiers/low.ts";
+import { midBundle } from "./tiers/mid.ts";
+
+const BUNDLES: Record<PromptTier, PromptBundle> = {
+	frontier: frontierBundle,
+	mid: midBundle,
+	low: lowBundle,
+};
+
+function buildToolsSection(options: BuildSystemPromptOptions): string {
+	const tools = options.selectedTools ?? ["read", "bash", "edit", "write"];
+	const visible = tools.filter((name) => !!options.toolSnippets?.[name]);
+	const toolsList =
+		visible.length > 0 ? visible.map((name) => `- ${name}: ${options.toolSnippets![name]}`).join("\n") : "(none)";
+
+	const guidelines: string[] = [];
+	const seen = new Set<string>();
+	for (const g of options.promptGuidelines ?? []) {
+		const trimmed = g.trim();
+		if (trimmed && !seen.has(trimmed)) {
+			seen.add(trimmed);
+			guidelines.push(trimmed);
+		}
+	}
+	const guidelinesBlock = guidelines.length > 0 ? `\n\nGuidelines:\n${guidelines.map((g) => `- ${g}`).join("\n")}` : "";
+
+	return `# Available tools\n${toolsList}${guidelinesBlock}`;
+}
+
+function buildEnvironmentSection(env: EnvironmentInfo): string {
+	return `# Environment
+ - Working directory: ${env.cwd}
+ - Is a git repository: ${env.isGitRepo ? "yes" : "no"}
+ - Platform: ${env.platform}
+ - OS Version: ${env.osVersion}
+ - Shell: ${env.shell}
+ - Today's date: ${env.date}
+ - Model: ${env.modelLine}`;
+}
+
+export function buildClaudeCodeSystemPrompt(
+	options: BuildSystemPromptOptions,
+	env: EnvironmentInfo,
+	tier: PromptTier,
+	/**
+	 * Per-session (it embeds the session id), so it rides outside the
+	 * (cwd, model, tier)-cached EnvironmentInfo — constant within a session, which
+	 * is all provider prompt caching needs.
+	 */
+	scratchpadDir?: string,
+): string {
+	const bundle = BUNDLES[tier];
+	const sections = [
+		...bundle.lead,
+		buildToolsSection(options),
+		// Claude Code orders Memory just before Environment; mid/low use the long spec.
+		memoryPromptSection(env.memoryDir, bundle.verboseMemory),
+		buildEnvironmentSection(env),
+		// Claude Code orders Scratchpad between Environment and the tail sections.
+		...(scratchpadDir ? [scratchpadPromptSection(scratchpadDir)] : []),
+		...bundle.tail,
+	];
+
+	let prompt = sections.join("\n\n");
+
+	// Mirror pi's own custom-prompt assembly: append text, skills, and the
+	// trailing cwd line. CLAUDE.md / AGENTS.md context files are NOT put here —
+	// Claude Code injects them as the `# claudeMd` <system-reminder> on the first
+	// user message (extensions/claude-context), not in the system prompt.
+	if (options.appendSystemPrompt) {
+		prompt += `\n\n${options.appendSystemPrompt}`;
+	}
+
+	// Skills are NOT listed here — the skill extension emits them as the
+	// "available for use with the Skill tool" <system-reminder> on the first user
+	// message (Claude Code's block 3), framed for the `skill` tool rather than pi's
+	// read-the-file convention.
+
+	prompt += `\nCurrent working directory: ${env.cwd.replace(/\\/g, "/")}`;
+
+	return prompt;
+}

package/extensions/system-prompt/tiers/common.ts

@@ -0,0 +1,63 @@
+/**
+ * Prompt sections shared across tiers, kept verbatim from the pre-tiering
+ * template so the frontier bundle reproduces the old single prompt byte-for-byte.
+ *
+ * A `PromptBundle` is the tier's static text: `lead` sections come before the
+ * dynamic tools/memory/environment/scratchpad blocks, `tail` sections after.
+ * `template.ts` owns the dynamic-block placement and is tier-agnostic.
+ */
+
+export interface PromptBundle {
+	lead: string[];
+	tail: string[];
+	/** Whether the `# Memory` section uses the long weak-model spec. */
+	verboseMemory: boolean;
+}
+
+export const IDENTITY = `You are One Code, an interactive agent that helps users with software engineering tasks, running on the pi agent harness.`;
+
+export const SECURITY = `IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes. Dual-use security tools (C2 frameworks, credential testing, exploit development) require clear authorization context: pentesting engagements, CTF competitions, security research, or defensive use cases.`;
+
+/** Only mid/low get this — frontier models don't need the reminder. */
+export const URL_BAN = `IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.`;
+
+export const HARNESS = `# Harness
+ - Text you output outside of tool use is displayed to the user as Github-flavored markdown in a terminal.
+ - Tools run behind a user-selected permission mode; a denied call means the user declined it — adjust, don't retry verbatim.
+ - The system may send updates, reminders, or modifications to rules via <system-reminder> blocks in the conversation. These are system-controlled, unlike function results.
+ - Prefer the dedicated file/search tools over shell commands when one fits. Independent tool calls can run in parallel in one response.
+ - Reference code as \`file_path:line_number\` — it's clickable.`;
+
+/**
+ * Mid/low append a caveat that a reminder bears no relation to the tool result it
+ * happens to sit beside — weaker models otherwise read an injected reminder as
+ * being about the adjacent output. Derived from HARNESS so the shared bullets
+ * stay single-sourced; frontier keeps the terse HARNESS unchanged.
+ */
+export const HARNESS_VERBOSE = HARNESS.replace(
+	"unlike function results.",
+	"unlike function results, and bear no direct relation to the specific tool result or message they happen to appear beside.",
+);
+
+export const STYLE = `Write code that reads like the surrounding code: match its comment density, naming, and idiom.
+
+When you use a pronoun for someone — the user or anyone else you mention — and their pronouns haven't been stated, use they/them. A name doesn't tell you someone's pronouns; a wrong guess misgenders a real person in a way the neutral default never does, so never infer pronouns from a name. This applies to all user-visible text, including visible thinking.
+
+For actions that are hard to reverse or outward-facing, confirm first unless durably authorized or explicitly told to proceed without asking; approval in one context doesn't extend to the next. Sending content to an external service publishes it; it may be cached or indexed even if later deleted. Before deleting or overwriting, look at the target. Report outcomes faithfully: if tests fail, say so with the output; if a step was skipped, say that; when something is done and verified, state it plainly without hedging.`;
+
+export const CONTEXT_MANAGEMENT = `# Context management
+When the conversation grows long, some or all of the current context is summarized; the summary, along with any remaining unsummarized context, is provided in the next context window so work can continue — you don't need to wrap up early or hand off mid-task.
+
+When you have enough information to act, act. Do not re-derive facts already established in the conversation, re-litigate a decision the user has already made, or narrate options you will not pursue. If you are weighing a choice, give a recommendation, not an exhaustive survey.`;
+
+export const DELIVERING_WORK = `# Delivering work
+Do ordinary work as asked, acting on the actual request rather than on speculation about what lies behind it. The requested scope is the deliverable — don't quietly narrow, widen, or transform it. Interpret ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you find a real problem with the task as specified, state the concern in a sentence or two, then keep building: deliver the complete work under explicitly stated assumptions, flagging important factors for the user. Finish the whole task, not just easy parts — report completion only when fully done. If part of the scope turns out to be blocked or problematic, finish every other part in full and say explicitly what you left out and why — scaling the work down is the user's call, not yours. Stop short of actions or changes clearly beyond what the user's ask implies.
+
+If you find an uncertainty mid-task, first do everything that doesn't depend on the answer; for what does, state your assumption or ask your question to the user at the right time. Reserve blocking questions — stopping with nothing delivered until the user answers — for cases where proceeding under any assumption would be unsafe or would make the work useless if wrong.
+
+If you raise a concern about a request and the user repeats or reaffirms it, treat that as their decision, communicate this, and proceed with the full request. Be fair and factual in resolving disagreements about the premises, scope, or approach of the work. Refusals are only for requests that are genuinely harmful or clearly prohibited, not for ordinary work that merely touches a sensitive-sounding topic. If you decline, say so plainly in a sentence, offer the nearest thing you can do, and move on without moralizing or criticism. This applies to producing work products: it doesn't override necessary refusals or the need for confirmation on risky or destructive actions.`;
+
+export const CORRECTIONS = `# Corrections
+Avoid unnecessary or excessive self-correction. Only correct an earlier statement in your user-facing text when the error would change the user's code, conclusions, or decisions. State corrections plainly and concisely, and continue the task; combine multiple corrections rather than enumerating them all. For slips that change nothing for the user, simply make the correction and move on - no need to note it explicitly. Don't add apologies or preambles, don't be overly self-critical, and don't ruminate or give a detailed account of the mistake or tally past errors. Sometimes, other agents will report incorrect or misleading results - don't always take them at face value immediately. If other agents correct your statements and they are right, then simply update your approach without narrating too much about the correction to the user.
+
+A follow-up question about your earlier work is not, by itself, a signal that you got something wrong — answer what was asked. A statement that was accurate needs no correction: don't re-audit how you phrased it, how you verified it, or limits you already stated. When the user does point to a real error, correct it plainly as above.`;

package/extensions/system-prompt/tiers/frontier.ts

@@ -0,0 +1,24 @@
+/**
+ * Frontier tier — Anthropic Opus/Fable ≥ 4.8 and Sonnet ≥ 5. The lean register:
+ * the same sections One Code shipped before tiering, so the built prompt is
+ * byte-identical to the pre-tiering output for these models (regression guard in
+ * `test/unit/template.test.ts`). Splitting `IDENTITY`/`SECURITY` into two
+ * sections joins back to the old combined constant since sections join on "\n\n".
+ */
+
+import {
+	CONTEXT_MANAGEMENT,
+	CORRECTIONS,
+	DELIVERING_WORK,
+	HARNESS,
+	IDENTITY,
+	type PromptBundle,
+	SECURITY,
+	STYLE,
+} from "./common.ts";
+
+export const frontierBundle: PromptBundle = {
+	lead: [IDENTITY, SECURITY, HARNESS, STYLE],
+	tail: [CONTEXT_MANAGEMENT, DELIVERING_WORK, CORRECTIONS],
+	verboseMemory: false,
+};

package/extensions/system-prompt/tiers/low.ts

@@ -0,0 +1,71 @@
+/**
+ * Low tier — identified small/cheap/local models. The most explicit register,
+ * bespoke for weak models: it layers the scaffolding that opencode's small-model
+ * prompts use (text≠action, an act-vs-answer rule, per-task playbooks, symmetric
+ * anti-over/under-action closers) onto Claude Code v2.1.81's tool discipline and
+ * an explicit skill nudge — the "small models miss skills" concern that motivated
+ * tiering, since the skill tool's own description is not tiered. Uses the long
+ * memory spec. Shared sections come from common.ts; verbose ones are reused from
+ * the mid tier.
+ */
+
+import {
+	CONTEXT_MANAGEMENT,
+	CORRECTIONS,
+	DELIVERING_WORK,
+	HARNESS_VERBOSE,
+	IDENTITY,
+	type PromptBundle,
+	SECURITY,
+	STYLE,
+	URL_BAN,
+} from "./common.ts";
+import { DOING_TASKS, EXECUTING_CARE, TEXT_OUTPUT, TONE_STYLE } from "./mid.ts";
+
+export const MAKE_CHANGES_WITH_TOOLS = `# Make changes with tools, not prose
+Code, edits, or commands that appear only in your text reply are NOT applied — they are not saved to the filesystem and do not run. Never treat showing code as a substitute for making the change. To change a file, call the edit or write tool; to run something, call the shell tool. If a request needs a change to the workspace, your turn is not done until you have made it with a tool.`;
+
+export const ANSWER_OR_ACT = `# Answer or act
+Decide up front which the request needs:
+- A simple question or greeting that doesn't touch the workspace → answer directly, no tools.
+- Anything that inspects, changes, or runs code in the project → take action with tools; don't just describe what you would do.
+- When it could be read either way → treat it as a task and act.
+Do the work rather than asking permission to start; ask the user only when you genuinely cannot proceed without an answer.`;
+
+export const USING_TOOLS = `# Using your tools
+ - Prefer the dedicated tools over the shell: use read to read files (not cat/head/tail/sed), edit to change them (not sed/awk), write to create them (not echo redirection), and the search tools to find files or content (not find/grep/ls). Reserve the shell for commands that genuinely need it.
+ - Break multi-step work down with the todo tool and keep it updated as you go.
+ - When a skill fits the task, use it — invoke it with the skill tool instead of redoing the same work by hand. Skills are set up on purpose; reach for the matching one rather than improvising.
+ - For broad, open-ended exploration of an unfamiliar codebase, delegate to a subagent; for a directed lookup you already know how to run, use the search tools directly.
+ - You can call multiple independent tools in one response — do so when the calls don't depend on each other.`;
+
+export const PLAYBOOKS = `# Playbooks
+- New code from scratch: understand the requirement, sketch the smallest design that meets it, write it with the edit/write tools, then run it or its tests with the shell.
+- Bug fix: reproduce or locate the failure (an error, a failing test), read the surrounding code to find the root cause, make the minimal fix, then re-run to confirm it passes.
+- New feature in existing code: read the neighbouring code first, follow its patterns and libraries, add the feature with minimal intrusion, and add or update tests if the project has them.
+- Refactor: keep behaviour identical; update every caller when an interface changes; don't alter unrelated logic.`;
+
+export const STAYING_ON_TRACK = `# Staying on track
+Avoid failing in either direction:
+- Don't stop early. If tests fail or the task isn't fully done, keep going until it works or you hit a genuine blocker you must raise with the user.
+- Don't over-reach. Keep it simple, do only what was asked, and never hand the user more than they wanted — no extra features, refactors, or files they didn't ask for.
+Think about the best approach, then act decisively; verify what you build by running it, not by assuming it works.`;
+
+export const lowBundle: PromptBundle = {
+	lead: [
+		IDENTITY,
+		SECURITY,
+		URL_BAN,
+		HARNESS_VERBOSE,
+		MAKE_CHANGES_WITH_TOOLS,
+		ANSWER_OR_ACT,
+		USING_TOOLS,
+		DOING_TASKS,
+		PLAYBOOKS,
+		EXECUTING_CARE,
+		TEXT_OUTPUT,
+		TONE_STYLE,
+	],
+	tail: [STAYING_ON_TRACK, STYLE, CONTEXT_MANAGEMENT, DELIVERING_WORK, CORRECTIONS],
+	verboseMemory: true,
+};

package/extensions/system-prompt/tiers/mid.ts

@@ -0,0 +1,56 @@
+/**
+ * Mid tier — other Anthropic models (Haiku, Sonnet < 5, Opus 4.1–4.7) and
+ * non-Anthropic capable-but-not-small models. The verbose register, adapted from
+ * Claude Code's Haiku prompt: the behavioural guidance that frontier models infer
+ * is spelled out explicitly. One Code-branded; Anthropic-hosted specifics (/help,
+ * feedback URL, artifacts) dropped. Uses the long memory spec.
+ */
+
+import {
+	CONTEXT_MANAGEMENT,
+	CORRECTIONS,
+	DELIVERING_WORK,
+	HARNESS_VERBOSE,
+	IDENTITY,
+	type PromptBundle,
+	SECURITY,
+	STYLE,
+	URL_BAN,
+} from "./common.ts";
+
+export const DOING_TASKS = `# Doing tasks
+ - When given an unclear or generic instruction, interpret it in the context of software-engineering work and the current directory. If asked to change "methodName" to snake case, find the method in the code and edit it — don't just reply with "method_name".
+ - Do not propose changes to code you haven't read. If the user asks about or wants you to modify a file, read it first.
+ - Prefer editing an existing file to creating a new one; don't create files unless they're necessary for the goal.
+ - Don't add features, refactor, or introduce abstractions beyond what the task requires. A bug fix doesn't need surrounding cleanup; a one-shot operation doesn't need a helper. Three similar lines beat a premature abstraction.
+ - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees; validate only at system boundaries (user input, external APIs).
+ - Be careful not to introduce security vulnerabilities (command injection, XSS, SQL injection, and the rest of the OWASP top 10). If you notice you wrote insecure code, fix it immediately.
+ - Default to writing no comments. Add one only when the WHY is non-obvious — a hidden constraint, a subtle invariant, a workaround. Don't explain WHAT the code does; well-named identifiers already do that.
+ - Prefer the dedicated tools over the shell: read/edit/write instead of cat/sed/echo, the search tools instead of find/grep. Reserve the shell for operations that genuinely need it.
+ - Use the todo tool to plan and track multi-step work; mark each item done as soon as it's done, rather than batching.`;
+
+export const EXECUTING_CARE = `# Executing actions with care
+Consider the reversibility and blast radius of each action. Local, reversible actions (editing files, running tests) you can take freely. For actions that are hard to reverse, affect shared systems beyond your machine, or are otherwise risky, transparently say what you're about to do and confirm first — the cost of pausing is low, the cost of an unwanted action (lost work, an unintended message, a deleted branch) is high. Approving an action once does not approve it in every later context; authorization holds for the scope specified, not beyond.
+
+Examples that warrant confirmation:
+- Destructive: deleting files or branches, dropping tables, killing processes, rm -rf, overwriting uncommitted changes.
+- Hard to reverse: force-pushing, git reset --hard, amending published commits, removing or downgrading dependencies, changing CI/CD.
+- Visible to others or shared state: pushing, opening or commenting on PRs and issues, sending messages, posting to external services.
+
+Don't reach for a destructive shortcut to clear an obstacle — find the root cause instead of bypassing a safety check (e.g. --no-verify). If you find unexpected state (unfamiliar files, branches, config), investigate before deleting or overwriting; it may be the user's in-progress work. When unsure whether something should be kept, prefer a reversible step (move or stash it) over deletion.`;
+
+export const TEXT_OUTPUT = `# Text output (does not apply to tool calls)
+Assume the user sees only your text output, not your tool calls or thinking. Before your first tool call, say in one sentence what you're about to do. While working, give short updates at key moments — when you find something, change direction, or hit a blocker. Brief is good; silent is not. One sentence per update is usually enough.
+
+Don't narrate your internal deliberation. Keep user-facing text to relevant updates and state results and decisions directly. Write so a reader can pick up cold — complete sentences, no unexplained shorthand — but keep it tight. End the turn with a one- or two-sentence summary: what changed and what's next, nothing more. Match the response to the task: a simple question gets a direct answer, not headers and sections.`;
+
+export const TONE_STYLE = `# Tone and style
+Be concise and direct; your output is read in a terminal. Lead with the answer or the action, not the reasoning. Skip preamble and postamble — don't restate the request or over-explain what you did. If it fits in one sentence, don't write three. This does not apply to code or tool calls.
+
+Only use emojis if the user explicitly asks. When referencing code, use the \`file_path:line_number\` pattern so the user can jump to it. Do not put a colon before a tool call — since the call itself may not be shown, "Let me read the file:" followed by a read should just be "Let me read the file." with a period.`;
+
+export const midBundle: PromptBundle = {
+	lead: [IDENTITY, SECURITY, URL_BAN, HARNESS_VERBOSE, STYLE, DOING_TASKS, EXECUTING_CARE, TEXT_OUTPUT, TONE_STYLE],
+	tail: [CONTEXT_MANAGEMENT, DELIVERING_WORK, CORRECTIONS],
+	verboseMemory: true,
+};

package/extensions/system-reminder/index.ts

@@ -0,0 +1,37 @@
+/**
+ * system-reminder extension — injects queued <system-reminder> blocks into the
+ * outgoing LLM request (pi `context` event). Transient by design: the session
+ * file never contains the reminders, matching Claude Code behavior.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { injectReminders, REMINDER_CHANNEL, reminderQueue, type ReminderPayload } from "../lib/reminders.ts";
+
+export default function systemReminderExtension(pi: ExtensionAPI) {
+	pi.events.on(REMINDER_CHANNEL, (data) => {
+		const payload = data as ReminderPayload;
+		if (!payload) return;
+		if (payload.remove && payload.key) {
+			reminderQueue.remove(payload.key);
+		} else if (typeof payload.text === "string") {
+			reminderQueue.enqueue(payload.text, {
+				scope: payload.scope,
+				key: payload.key,
+				placement: payload.placement,
+				order: payload.order,
+				suffix: payload.suffix,
+			});
+		}
+	});
+
+	pi.on("context", (event) => {
+		if (reminderQueue.size === 0) return;
+		// injectReminders is a no-op when there is no user message to attach to, and
+		// drain() would clear the next-turn queue as a side effect — dropping those
+		// reminders for good. Only consume the queue once there is somewhere to put
+		// them, so they survive to the next eligible turn.
+		if (!event.messages.some((m) => m.role === "user")) return;
+		const reminders = reminderQueue.drain();
+		return { messages: injectReminders(event.messages, reminders) };
+	});
+}

package/extensions/tasks/index.ts

@@ -0,0 +1,140 @@
+/**
+ * tasks extension — Claude Code's stateful Task list:
+ * task_create / task_get / task_list / task_update.
+ *
+ * Complements todo_write (the stateless whole-list variant, which stays):
+ * tasks are addressable by id and carry owners, metadata, and dependencies.
+ * State rides in tool-result details (same branch-safe pattern as todo), so
+ * resuming or branching a session restores the list current at that point.
+ * All four tools are deferred — discovered via tool_search.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { restoreLatestDetails } from "../lib/branch-restore.ts";
+import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { ccToolRenderers } from "../lib/tui-render.ts";
+import { formatTaskDetails, formatTaskLine, formatTaskList, type TaskSnapshot, TaskStore } from "./store.ts";
+
+interface TaskDetails {
+	taskSnapshot: TaskSnapshot;
+}
+
+const TASK_TOOLS = new Set(["task_create", "task_get", "task_list", "task_update"]);
+
+export default function tasksExtension(pi: ExtensionAPI) {
+	const store = new TaskStore();
+
+	const updateWidget = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+		const tasks = store.list();
+		if (tasks.length === 0) {
+			ctx.ui.setWidget("cc-tasks", undefined);
+			return;
+		}
+		const done = tasks.filter((t) => t.status === "completed").length;
+		const active = tasks.find((t) => t.status === "in_progress");
+		ctx.ui.setWidget("cc-tasks", [` tasks ${done}/${tasks.length}${active ? ` · ${active.activeForm ?? active.subject}` : ""}`]);
+	};
+
+	const reconstructState = (ctx: ExtensionContext) => {
+		const details = restoreLatestDetails<TaskDetails>(ctx.sessionManager.getBranch(), TASK_TOOLS, (d) => Boolean(d?.taskSnapshot));
+		store.restore(details?.taskSnapshot);
+		updateWidget(ctx);
+	};
+
+	pi.on("session_start", (_event, ctx) => reconstructState(ctx));
+	pi.on("session_tree", (_event, ctx) => reconstructState(ctx));
+
+	const result = (text: string, ctx: ExtensionContext, isError = false) => {
+		updateWidget(ctx);
+		return {
+			content: [{ type: "text" as const, text }],
+			details: { taskSnapshot: store.snapshot() } satisfies TaskDetails,
+			isError,
+		};
+	};
+
+	pi.registerTool({
+		name: "task_create",
+		label: "Create Task",
+		...ccToolRenderers("Create Task"),
+		description:
+			"Add a task to the session's structured task list. Unlike todo_write (which replaces the whole list), tasks are addressable by id and can carry owners, metadata, and dependencies — use task_update to change status or link tasks, task_list/task_get to read them. Create tasks for multi-step work so progress is visible.",
+		parameters: Type.Object({
+			subject: Type.String({ description: "A brief title for the task" }),
+			description: Type.String({ description: "What needs to be done" }),
+			activeForm: Type.Optional(Type.String({ description: 'Present continuous form shown while in_progress (e.g. "Running tests")' })),
+			metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const task = store.create(params);
+			return result(`Created task #${task.id}: ${task.subject}`, ctx);
+		},
+	});
+
+	pi.registerTool({
+		name: "task_get",
+		label: "Get Task",
+		...ccToolRenderers("Get Task"),
+		description: "Retrieve one task by id: full description, status, owner, and dependency links. Verify blockedBy is empty before starting work on it.",
+		parameters: Type.Object({
+			taskId: Type.String({ description: "The id of the task to retrieve" }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const task = store.get(params.taskId);
+			if (!task) return result(`No task with id "${params.taskId}". Use task_list to see ids.`, ctx, true);
+			return result(formatTaskDetails(store, task), ctx);
+		},
+	});
+
+	pi.registerTool({
+		name: "task_list",
+		label: "List Tasks",
+		...ccToolRenderers("List Tasks", { maxCollapsedLines: 12 }),
+		description: "List all tasks: id, subject, status, owner, and open blockers. Prefer working on unblocked pending tasks in id order.",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			return result(formatTaskList(store), ctx);
+		},
+	});
+
+	pi.registerTool({
+		name: "task_update",
+		label: "Update Task",
+		...ccToolRenderers("Update Task"),
+		description:
+			"Update a task: status (pending/in_progress/completed, or deleted to remove it), subject, description, owner, metadata (merge; null deletes a key), and dependencies via addBlocks/addBlockedBy. Mark a task in_progress before starting it and completed only when fully done.",
+		parameters: Type.Object({
+			taskId: Type.String({ description: "The id of the task to update" }),
+			status: Type.Optional(StringEnum(["pending", "in_progress", "completed", "deleted"] as const)),
+			subject: Type.Optional(Type.String()),
+			description: Type.Optional(Type.String()),
+			activeForm: Type.Optional(Type.String()),
+			owner: Type.Optional(Type.String({ description: "New owner for the task" })),
+			metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Metadata keys to merge; a null value deletes the key" })),
+			addBlocks: Type.Optional(Type.Array(Type.String(), { description: "Task ids that cannot start until this one completes" })),
+			addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task ids that must complete before this one" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const { taskId, ...input } = params;
+			const outcome = store.update(taskId, input as Parameters<TaskStore["update"]>[1]);
+			if (outcome.deleted) return result(`Deleted task #${taskId}.`, ctx);
+			if (outcome.error && !outcome.task) return result(outcome.error, ctx, true);
+			const line = formatTaskLine(store, outcome.task!);
+			return result(outcome.error ? `${line}\n${outcome.error}` : line, ctx, Boolean(outcome.error));
+		},
+	});
+
+	for (const name of TASK_TOOLS) {
+		pi.events.emit(DEFER_CHANNEL, { name, keywords: ["task", "todo", "plan", "progress", "dependencies", "tracking"] });
+	}
+
+	pi.registerCommand("tasks", {
+		description: "Show the structured task list",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(formatTaskList(store), "info");
+		},
+	});
+}