one-code-extension 0.4.1 → 0.5.0

package/extensions/subagents/agents.ts

@@ -15,9 +15,11 @@
  */
 
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
-import { claudeUserDir } from "../lib/paths.ts";
+import { projectConfigDir, userConfigDir } from "../lib/config-mode.ts";
+import { SUBAGENT_HANDBACK } from "../lib/subagent-handback.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
 
 export interface AgentDefinition {
@@ -66,24 +68,65 @@ function collectMarkdownFiles(dir: string, out: string[] = []): string[] {
 	return out;
 }
 
+/**
+ * Split one frontmatter tool string the way Claude Code does: on commas and
+ * spaces, except inside a rule's parentheses, so `Bash(git push:*), Write` is
+ * two entries and `Agent(worker, researcher)` is one.
+ */
+function splitToolSpecs(text: string): string[] {
+	const specs: string[] = [];
+	let current = "";
+	let inParens = false;
+	for (const char of text) {
+		if (char === "(") inParens = true;
+		else if (char === ")") inParens = false;
+		else if ((char === "," || /\s/.test(char)) && !inParens) {
+			if (current.trim()) specs.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (current.trim()) specs.push(current.trim());
+	return specs;
+}
+
+/**
+ * The tool a spec names. A rule-shaped entry (`Bash(git push:*)`) names its
+ * whole tool: Claude Code grants or removes the entire tool for it in an agent
+ * file, never only the rule's commands, so `disallowedTools: Bash(git push:*)`
+ * removes `bash`. Anything that is not `Name(…)` is taken as a plain name.
+ */
+function specToolName(spec: string): string {
+	const open = spec.indexOf("(");
+	return open > 0 && spec.endsWith(")") ? spec.slice(0, open) : spec;
+}
+
 /**
  * A frontmatter tool list (comma string or YAML list) as pi tool names: Claude
  * Code spellings map through the alias table (`Glob` → `find`, `WebFetch` →
  * `web_fetch`, `Task` → `Agent`, …), pi names and `mcp__*` pass through,
- * duplicates collapse. Exported for tests.
+ * rule-shaped entries reduce to their tool, duplicates collapse. A list that
+ * contains `*` returns `["*"]`; `parseAgentFile` reads that as "all tools".
+ * Exported for tests.
  */
 export function parseToolList(raw: unknown): string[] | undefined {
-	const list =
-		typeof raw === "string"
-			? raw
-					.split(",")
-					.map((t) => t.trim())
-					.filter(Boolean)
-			: Array.isArray(raw)
-				? raw.filter((t): t is string => typeof t === "string").map((t) => t.trim()).filter(Boolean)
-				: undefined;
-	if (!list || list.length === 0) return undefined;
-	return [...new Set(list.map(normalizeToolName))];
+	const entries =
+		typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw.filter((t): t is string => typeof t === "string") : undefined;
+	const specs = entries?.flatMap(splitToolSpecs);
+	if (!specs || specs.length === 0) return undefined;
+	if (specs.includes("*")) return ["*"];
+	return [...new Set(specs.map((spec) => normalizeToolName(specToolName(spec))))];
+}
+
+/**
+ * An agent file's `tools` allowlist. Claude Code reads a list containing `*`
+ * as "all tools", the same as no list; kept as `["*"]` the allowlist matched
+ * no tool and every spawn failed.
+ */
+function parseAllowlist(raw: unknown): string[] | undefined {
+	const tools = parseToolList(raw);
+	return tools?.includes("*") ? undefined : tools;
 }
 
 export function parseAgentFile(path: string, content: string): AgentDefinition | undefined {
@@ -98,7 +141,7 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
 	return {
 		name,
 		description: typeof fm.description === "string" ? fm.description : "",
-		tools: parseToolList(fm.tools),
+		tools: parseAllowlist(fm.tools),
 		excludeTools: disallowed.length > 0 ? [...new Set(disallowed)] : undefined,
 		// "inherit" is Claude Code's way of saying "use the session model".
 		model: typeof fm.model === "string" && fm.model !== "inherit" ? fm.model : undefined,
@@ -109,11 +152,25 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
 
 /**
  * Lowest to highest precedence: the catalog bundled with this package, then the
- * user's `~/.claude/agents`, then the project's `.claude/agents`. A user or
- * project definition with the same name replaces a bundled one.
+ * user's `~/.claude/agents`, then the project's `.claude/agents` (`~/.onecode`
+ * and `.onecode` in independent mode, lib/config-mode.ts). A user or project
+ * definition with the same name replaces a bundled one.
  */
 export function agentDirs(cwd: string, home: string, bundled?: string): string[] {
-	return [...(bundled ? [bundled] : []), join(claudeUserDir(home), "agents"), join(cwd, ".claude", "agents")];
+	return [...(bundled ? [bundled] : []), join(userConfigDir(home), "agents"), join(projectConfigDir(cwd), "agents")];
+}
+
+/** The agent files the package ships (general-purpose, explore, plan, …). */
+export const BUNDLED_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+
+/**
+ * Every agent-file source in rank order, as the Agent tool loads them:
+ * bundled, then plugin agents, then the user and project folders. Workflows
+ * resolve `agentType` from the same list (the code-defined guide is the Agent
+ * tool's alone).
+ */
+export function agentFileSources(cwd: string, home: string, pluginAgentDirs: readonly (string | AgentSource)[]): Array<string | AgentSource> {
+	return [BUNDLED_AGENTS_DIR, ...pluginAgentDirs, ...agentDirs(cwd, home)];
 }
 
 /** A directory whose agents are exposed as `<namespace>:<name>` (plugins). */
@@ -122,10 +179,19 @@ export interface AgentSource {
 	namespace?: string;
 }
 
+/** Agents defined in code (`one-code-guide`), taken as they are: never copied, so a lazy prompt stays lazy. */
+export interface CodeAgents {
+	agents: readonly AgentDefinition[];
+}
+
 /** Later sources override earlier ones on name collisions. */
-export function discoverAgents(sources: Array<string | AgentSource>): AgentDefinition[] {
+export function discoverAgents(sources: Array<string | AgentSource | CodeAgents>): AgentDefinition[] {
 	const byName = new Map<string, AgentDefinition>();
 	for (const source of sources) {
+		if (typeof source !== "string" && "agents" in source) {
+			for (const agent of source.agents) byName.set(agent.name, agent);
+			continue;
+		}
 		const { dir, namespace } = typeof source === "string" ? { dir: source, namespace: undefined } : source;
 		for (const file of collectMarkdownFiles(dir)) {
 			try {
@@ -145,11 +211,12 @@ export function discoverAgents(sources: Array<string | AgentSource>): AgentDefin
  * Tools a child cannot function without, re-added when an agent file's `tools`
  * allowlist omits them: pi's allowlist filters built-ins, extension tools AND
  * injected custom tools by exact name, so a CC-style `tools: Read, Grep` would
- * otherwise also strip the child's report channel (`SendMessage` → main), its
- * deferred-tool loader and the runtime's `structured_output`. Claude Code's
- * allowlist never strips its own plumbing either.
+ * otherwise also strip the child's report channels (`SendMessage` → main and
+ * the final `SubagentHandback`), its deferred-tool loader and the runtime's
+ * `structured_output`. Claude Code's allowlist never strips its own plumbing
+ * either.
  */
-const ALLOWLIST_ESSENTIALS = ["SendMessage", "tool_search", "structured_output"];
+const ALLOWLIST_ESSENTIALS = ["SendMessage", SUBAGENT_HANDBACK, "tool_search", "structured_output"];
 
 /** Apply an agent's allowlist to pi's `tools` option, keeping the essentials. */
 export function childToolAllowlist(tools: string[] | undefined): string[] | undefined {
@@ -168,3 +235,29 @@ export function usableAllowlistedTools(registered: string[], allowlist: string[]
 	const available = new Set(registered);
 	return allowlist.filter((name) => available.has(name));
 }
+
+/**
+ * pi's session tool options for a named agent: its allowlist with the child's
+ * plumbing re-added, and its denylist. The one builder both runners use (the
+ * subagent runner and the workflow runner), so an agent file means the same
+ * thing wherever it runs; the workflow runner once passed the raw allowlist and
+ * no denylist, which stripped `structured_output` and ignored `disallowedTools`
+ * (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 H2, H3).
+ */
+export function agentToolOptions(agent: AgentDefinition | undefined): { tools?: string[]; excludeTools?: string[] } {
+	return { tools: childToolAllowlist(agent?.tools), excludeTools: agent?.excludeTools };
+}
+
+/**
+ * The fail-loud error for an agent whose `tools` allowlist matched no tool the
+ * session registered, or undefined when the agent is usable. pi drops unknown
+ * names silently, so without this the agent would run with no tools and
+ * "complete" with an excuse.
+ */
+export function unusableAllowlistError(agent: AgentDefinition | undefined, registered: string[]): string | undefined {
+	if (!agent?.tools || usableAllowlistedTools(registered, agent.tools).length > 0) return undefined;
+	return (
+		`Agent "${agent.name}" lists tools (${agent.tools.join(", ")}) that match no available tool. ` +
+		"Use Claude Code names (Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, NotebookEdit, Skill, Agent, SendMessage) or pi names (read, edit, write, bash, grep, find, ls, …) in the agent file's `tools` list."
+	);
+}

package/extensions/subagents/announce.ts

@@ -0,0 +1,69 @@
+/** Pure state for resumed-session subagent capability announcements. */
+
+export type SubagentCapability = "models" | "agents" | "delegation";
+export interface SubagentBaseline {
+	models: string | null;
+	agents: string | null;
+	delegation: string | null;
+	/** Account refusals the narrow tail correction has already communicated. */
+	refusedModels: string[];
+}
+
+export function emptySubagentBaseline(): SubagentBaseline {
+	return { models: null, agents: null, delegation: null, refusedModels: [] };
+}
+
+/** Stored baseline validation deliberately permits arbitrary reminder text. */
+export function subagentBaseline(value: unknown): SubagentBaseline | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	const output = emptySubagentBaseline();
+	for (const key of ["models", "agents", "delegation"] as const) {
+		if (input[key] !== null && typeof input[key] !== "string") return undefined;
+		output[key] = (input[key] as string | null | undefined) ?? null;
+	}
+	// v1 phase-2 snapshots did not carry this field; absence means no known
+	// refusal, not malformed state. Keep the list JSON-safe and deterministic.
+	if (input.refusedModels !== undefined && (!Array.isArray(input.refusedModels) || !input.refusedModels.every((model) => typeof model === "string"))) return undefined;
+	output.refusedModels = [...new Set((input.refusedModels as string[] | undefined) ?? [])];
+	return output;
+}
+
+/** A restored first-prepend block is a usable fallback for snapshots predating structured baselines. */
+export function subagentBaselineFromStack(stack: readonly { key?: string; text: string }[]): SubagentBaseline {
+	const baseline = emptySubagentBaseline();
+	const keys: Record<SubagentCapability, string> = {
+		models: "subagent-models", agents: "subagent-agents", delegation: "subagent-delegation",
+	};
+	for (const capability of Object.keys(keys) as SubagentCapability[]) {
+		const entry = stack.find((item) => item.key === keys[capability]);
+		baseline[capability] = entry?.text ?? null;
+	}
+	return baseline;
+}
+
+export type SubagentAnnouncement =
+	| { kind: "none"; baseline: SubagentBaseline }
+	| { kind: "standing"; baseline: SubagentBaseline }
+	| { kind: "addendum"; text: string; baseline: SubagentBaseline };
+
+/**
+ * Fresh sessions may rewrite message 1; resumed sessions must leave its locked
+ * block alone and describe a real capability change at the tail instead.
+ */
+export function planSubagentAnnouncement(input: {
+	restored: boolean;
+	baseline: SubagentBaseline;
+	capability: SubagentCapability;
+	text: string | null;
+}): SubagentAnnouncement {
+	if (input.baseline[input.capability] === input.text) return { kind: "none", baseline: input.baseline };
+	const baseline = { ...input.baseline, [input.capability]: input.text };
+	if (!input.restored) return { kind: "standing", baseline };
+	if (input.text !== null) return { kind: "addendum", text: input.text, baseline };
+	return {
+		kind: "addendum",
+		text: "The subagent delegation guidance previously shown for this conversation is no longer active.",
+		baseline,
+	};
+}

package/extensions/subagents/default-model.ts

@@ -10,15 +10,14 @@
  *   not read: both project files live in the repository, and a checked-in `env`
  *   block must not get to pick which provider receives subagent tasks — the
  *   same containment rule as `autoMode` config.
- * - `subagentModel` — One Code's own top-level setting, same shape as
- *   `autoMode.classifierModel`. Wins over the env var when both are set,
+ * - `subagentModel` — One Code's own top-level setting. Wins over the env var when both are set,
  *   because it is the more specific statement of intent. It is One Code's key,
  *   not Claude Code's: it is written to and read from `~/.onecode/settings.json`
  *   (+ managed settings), never from `~/.claude`, where an old One Code build may
  *   have left a stale value the current session cannot reach. Claude Code's own
  *   `CLAUDE_CODE_SUBAGENT_MODEL` env block is still honoured from `~/.claude`
  *   (that key *is* Claude Code's). See "Own state, borrowed config" in
- *   docs/decisions/memory-state.md.
+ *   working-docs/decisions/memory-state.md.
  *
  * The env var additionally applies only to Claude-family sessions (see
  * `applicableSubagentDefault`): it is Claude Code's knob, and its typical

package/extensions/subagents/delegation-steer.ts

@@ -16,8 +16,8 @@
  */
 
 export const DELEGATION_STEER = [
-	'Delegation policy: when a request requires reading or searching MANY files (a codebase overview, "find every place where…", a consistency audit, exploring unfamiliar code), do NOT sweep the files yourself.',
-	'Make ONE Agent tool call with subagent_type: "explore" and the complete question as the task. The agent searches in its own separate context and returns just the answer; reading file after file yourself fills your context and degrades your answer.',
-	"Search directly only for a single targeted lookup (one known file or symbol).",
-	"When the agent has answered, report its answer and move on — do not re-read the files it already covered.",
+	"Delegation policy: when a request requires reading MANY files (a codebase overview, how a feature works across modules, exploring unfamiliar code), do NOT sweep the files yourself.",
+	'Make one Agent tool call per independent question, with subagent_type: "explore" and the complete question as the task; for several independent questions, issue those calls together in one message. The agent searches in its own separate context and returns just the answer; reading file after file yourself fills your context and degrades your answer.',
+	"Search directly for a single targeted lookup: one known file or symbol, or a word one grep can find everywhere.",
+	"When the agent has answered, report its answer and move on — do not re-read the files it already covered, except one you are about to edit (an edit needs a read first).",
 ].join("\n");

package/extensions/subagents/fork-cache.ts

@@ -0,0 +1,76 @@
+/**
+ * The fork's side of reading the parent's prompt cache (decisions/caching.md,
+ * "A call that inherits the session's context reads the session's cache").
+ *
+ * A fork's own session builds its requests from its own system prompt, tools
+ * and reminder stack, so every fork re-read the parent's whole transcript
+ * uncached: on a parent near a 1M-token window, the whole window per fork.
+ * This inline extension, loaded last in a fork's session, sends the parent's
+ * last captured request instead, with the fork's own messages after it:
+ *
+ * - `context_with_system` (it runs after every `context` handler, so the
+ *   fork's reminder stack is already on the messages it drops) removes the
+ *   messages the capture carries, leaving pi to convert only the fork's tail;
+ * - `before_provider_request` (inline extensions load after the path ones, so
+ *   tool-search has already edited the body) replaces everything but the tail
+ *   with the captured body (`forkRequestPayload`);
+ * - `before_provider_headers` sends the parent's session-affinity headers, so a
+ *   gateway such as OpenRouter routes the fork to the host holding the cache.
+ *
+ * Both steps check the same thing first (the capture's model and its boundary
+ * message in this context); when either fails, or the tail leaves less than
+ * `MIN_REPLAY_OUTPUT_TOKENS` of the captured output room, the request goes out
+ * the ordinary way, whole, and uncached. That happens only for a fork that
+ * compacted its own history away, runs on another model, or has nearly
+ * filled the window.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { type AffinityModel, affinityHeaders, captureMatches, forkOutputRoom, forkRequestPayload, MIN_REPLAY_OUTPUT_TOKENS, type RequestCapture, toolNames, uncoveredMessages } from "../lib/request-replay.ts";
+
+type ModelRef = { api?: string; provider?: string; id?: string };
+
+export function forkCacheExtension(capture: RequestCapture) {
+	return (pi: ExtensionAPI) => {
+		// The fork advertises the parent's tools, where SendMessage is deferred
+		// (subagents/index.ts). Defer the fork's own SendMessage the same way, so a
+		// tool_search load reaches it: on a model without tool references the load
+		// appends it, and elsewhere the parent's compatible schema (to: "main")
+		// already declares it. Inline extensions load after tool-search.
+		pi.events.emit(DEFER_CHANNEL, { name: "SendMessage", keywords: ["message", "main", "report", "progress"] });
+		/** Set by the context step for the request it shaped; the payload step splices only then. */
+		let shaped = false;
+		/** The tool names of the fork's first request: anything added later was loaded during the run. */
+		let baseline: Set<string> | undefined;
+
+		pi.on("context_with_system", (event, ctx) => {
+			shaped = false;
+			const covers = capture.covers;
+			if (!covers || !captureMatches(capture, ctx.model as ModelRef | undefined)) return undefined;
+			const tail = uncoveredMessages(event.messages as { role: string; timestamp?: number }[], covers);
+			if (!tail) return undefined;
+			// Too little output room left after the prefix: send the fork whole
+			// (pi's overflow handling then compacts it) rather than a splice the
+			// window cannot hold. The messages' JSON overstates the wire tail.
+			const room = forkOutputRoom(capture, tail.filter((message) => message.role !== "system"));
+			if (room !== undefined && room < MIN_REPLAY_OUTPUT_TOKENS) return undefined;
+			shaped = true;
+			return { messages: tail as typeof event.messages };
+		});
+
+		// Route to the parent's host: a gateway picks it by the session-affinity
+		// headers, and the parent's cache lives there. Harmless on a whole request.
+		pi.on("before_provider_headers", (event, ctx) => {
+			if (!capture.sessionId || !captureMatches(capture, ctx.model as ModelRef | undefined)) return;
+			Object.assign(event.headers, affinityHeaders(ctx.model as AffinityModel, capture.sessionId));
+		});
+
+		pi.on("before_provider_request", (event, ctx) => {
+			if (!shaped || !captureMatches(capture, ctx.model as ModelRef | undefined)) return undefined;
+			shaped = false;
+			const payload = event.payload as Record<string, unknown>;
+			baseline ??= new Set(toolNames(payload.tools));
+			return forkRequestPayload(capture, payload, baseline);
+		});
+	};
+}

package/extensions/subagents/guide-agent.ts

@@ -0,0 +1,189 @@
+/**
+ * The `one-code-guide` agent — One Code's counterpart of Claude Code's built-in
+ * `claude-code-guide` (2.1.283): a read-only agent the model spawns when the
+ * user asks how One Code works, which answers from the documentation on disk
+ * rather than from memory, and knows the user's live setup.
+ *
+ * Claude Code's guide fetches its docs over the web and runs on `haiku`. Ours
+ * reads the user guide shipped in this package and the running pi's docs and
+ * examples (lib/guide-docs.ts), so the answer matches the installed version,
+ * and runs on the session's subagent model (no `model` here, so the usual
+ * resolution applies). It answers about One Code only, and when One Code lacks
+ * something it suggests how to add it, down to a custom pi extension.
+ *
+ * Built in code, not as an `agents/*.md` file, because the prompt names paths
+ * and configuration known only at runtime. It is the lowest-precedence
+ * definition, so a user or project agent file of the same name replaces it.
+ * Pure (no pi imports): the subagents extension gathers the inputs. The brand
+ * text lives here only, so a downstream fork swaps this one module.
+ */
+
+import type { AgentDefinition } from "./agents.ts";
+import { claudeSourcesOn, projectConfigDirName } from "../lib/config-mode.ts";
+
+export const GUIDE_AGENT = "one-code-guide";
+
+const REPO_URL = "https://github.com/IsuruMaduranga/one-code";
+
+/**
+ * Claude Code's guide tools where search runs through the shell (its
+ * embedded-search shape): bash for `grep`/`find`, read, and the web tools.
+ * pi's own grep/find/ls are active only on the tiny tier (search-tools), so an
+ * allowlist naming them left the child without search.
+ */
+export const GUIDE_TOOLS = ["bash", "read", "web_fetch", "web_search"];
+
+export const GUIDE_DESCRIPTION =
+	'Use this agent when the user asks questions ("Can One Code...", "Does One Code...", "How do I...") about One Code itself: features, slash commands, settings, permission modes and auto mode, hooks, skills, plugins, MCP servers, subagents and workflows, models and providers, keyboard shortcuts, installation and troubleshooting. Also use it when the user wants One Code to do something it does not do yet: it suggests an existing feature or setting, or how to add it with a skill, agent, hook, MCP server or a custom pi extension. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed one-code-guide agent that you can continue via SendMessage.';
+
+export interface GuideInstall {
+	/** `app` for the bundled `onecode`, `extension` for One Code on the user's own pi. */
+	shape: "app" | "extension";
+	/** How the app was installed (`npm`, `brew`), when known. */
+	method?: string;
+	/** pi's agent directory for this session (`getAgentDir()`). */
+	agentDir: string;
+	/** The One Code version, when known. */
+	version?: string;
+}
+
+/** The user's live setup, listed so the answer can build on it. Names only. */
+export interface GuideSetup {
+	skills: string[];
+	agents: string[];
+	plugins: string[];
+	/** Every configured MCP server, with its status when it is not connected. */
+	mcpServers: { name: string; status?: string }[];
+	/** Extensions dropped into the user's pi extensions directory. */
+	extensions: string[];
+	/** pi packages the user installed, One Code's own entry excluded. */
+	packages: string[];
+	/** Keys set in pi's settings file for this session (values omitted). */
+	settingsKeys: string[];
+}
+
+export interface GuideInput {
+	docs: { guide: string; piDocs?: string; piExamples?: string };
+	install: GuideInstall;
+	setup: GuideSetup;
+}
+
+/**
+ * The packages and settings keys in pi's settings file (its raw text), minus
+ * One Code's own package entry (`ownRoot`, this package's directory, which the
+ * app registers on every launch). Unreadable text gives nothing.
+ */
+export function settingsSetup(raw: string | undefined, ownRoot: string): Pick<GuideSetup, "packages" | "settingsKeys"> {
+	let settings: unknown;
+	try {
+		settings = raw === undefined ? undefined : JSON.parse(raw);
+	} catch {
+		return { packages: [], settingsKeys: [] };
+	}
+	if (typeof settings !== "object" || settings === null || Array.isArray(settings)) return { packages: [], settingsKeys: [] };
+	const record = settings as Record<string, unknown>;
+	const sources = (Array.isArray(record.packages) ? record.packages : [])
+		.map((entry) => (typeof entry === "string" ? entry : (entry as { source?: unknown } | null)?.source))
+		.filter((source): source is string => typeof source === "string");
+	const own = (source: string) => source === ownRoot || /[/\\]one-code-extension$/.test(source) || /^npm:one-code-extension(@.*)?$/.test(source);
+	return { packages: sources.filter((source) => !own(source)), settingsKeys: Object.keys(record).sort() };
+}
+
+function installSection({ shape, method, agentDir, version }: GuideInstall): string {
+	const v = version ? ` ${version}` : "";
+	if (shape === "app") {
+		return `This session runs the bundled One Code app (\`onecode\`${v}${method ? `, installed with ${method}` : ""}). It carries its own pinned pi and keeps pi's state in its agent directory, \`${agentDir}\`. pi's commands work through it: \`onecode install <source>\` installs a pi package (npm, git or a local path) into that directory's \`settings.json\`, \`onecode remove <source>\` removes one, and \`onecode list\` lists them. A plain \`pi\` command on the same machine is a separate installation and does not see these.`;
+	}
+	return `This session runs One Code as an extension on the user's own pi installation${v ? ` (One Code${v})` : ""}. pi's agent directory is \`${agentDir}\`; \`pi install <source>\`, \`pi remove <source>\` and \`pi list\` manage packages there.`;
+}
+
+/**
+ * Whether a repository-supplied name may be listed in the guide's system
+ * prompt: an identifier (letters, digits, `_ . : @ -`, at most 64), never free
+ * text a cloned repo could use to smuggle instructions in.
+ */
+export function listableName(name: string): boolean {
+	return /^[A-Za-z0-9_.:@-]{1,64}$/.test(name);
+}
+
+function setupSection(setup: GuideSetup): string | undefined {
+	const rows: string[] = [];
+	const list = (label: string, items: string[]) => {
+		if (items.length > 0) rows.push(`**${label}:** ${items.join(", ")}`);
+	};
+	// Skill folders, agent files and .mcp.json servers can come from a cloned
+	// repository, so only identifier-shaped names reach the system prompt.
+	list("Custom skills", setup.skills.filter(listableName));
+	list("Custom agents", setup.agents.filter(listableName));
+	list("Enabled plugins", setup.plugins);
+	list(
+		"Configured MCP servers",
+		setup.mcpServers.filter((server) => listableName(server.name)).map((server) => (server.status ? `${server.name} (${server.status})` : server.name)),
+	);
+	list("Installed pi packages", setup.packages);
+	list("Extensions in the user extensions directory", setup.extensions);
+	list("Settings keys configured (values omitted)", setup.settingsKeys);
+	if (rows.length === 0) return undefined;
+	return `# User's Current Configuration\nThe user has the following custom setup in their environment:\n${rows.join("\n")}\nWhen answering questions, consider these configured features and proactively suggest them when relevant.`;
+}
+
+export function guideSystemPrompt({ docs, install, setup }: GuideInput): string {
+	const piDocs = docs.piDocs ? `\`${docs.piDocs}\`` : "pi's `docs/` folder (not found on this machine; use https://pi.dev/docs/latest)";
+	const piExamples = docs.piExamples ? `\`${docs.piExamples}\`` : "pi's `examples/` folder (not found on this machine)";
+	const extensionsDir = `${install.agentDir}/extensions/`;
+	const prompt = `You are the One Code guide agent. Your primary responsibility is helping users understand and use One Code effectively, and showing them how to make it do more.
+
+**What One Code is:** a coding agent that recreates the Claude Code experience on any model provider. It is built as a package of extensions for the pi agent harness, so everything it does is an ordinary pi extension, and users can extend it the same way.
+
+**How this session is installed:** ${installSection(install)}
+
+**Documentation sources (all on this machine, matching the installed version):**
+- **One Code user guide** (\`${docs.guide}\`): start with its \`README.md\`, the index of every page. Read it for any question about One Code's features, commands, settings, permissions and auto mode, hooks, skills, plugins, MCP, subagents, workflows, models, the terminal interface, Windows, troubleshooting, and how One Code differs from Claude Code.
+- **pi documentation** (${piDocs}): read it for what One Code inherits from pi and for extending it: \`extensions.md\` (writing an extension), \`packages.md\` (installing and publishing packages), \`settings.md\`, \`keybindings.md\`, \`providers.md\` and \`models.md\`.
+- **pi examples** (${piExamples}): working extensions to base a suggestion on (\`examples/extensions/\`).
+
+**Approach:**
+1. Read the One Code guide's index and pick the pages that cover the question
+2. Read those pages; search the docs with \`grep\` and \`find\` through the shell when the index does not name the topic
+3. For customization and extension questions, read pi's docs and examples too
+4. Read the user's own configuration (settings files, ${claudeSourcesOn() ? "CLAUDE.md" : "AGENTS.md, ONECODE.md"}, \`${projectConfigDirName()}/\`) when it bears on the answer
+5. Provide clear, actionable guidance based on the documentation, citing the file each fact came from
+
+**When One Code does not do what the user wants,** say so plainly, then suggest the smallest change that gets them there, in this order:
+1. An existing feature, command or setting that covers it
+2. Configuration they can add themselves: a skill, a custom agent, a hook, an MCP server, or a plugin (the guide explains each)
+3. A custom pi extension. Describe what it would do and which pi events or APIs it would use, from pi's \`extensions.md\` and the examples. To try it, the user drops a \`.ts\` file (or a folder with an \`index.ts\`) into \`${extensionsDir}\` for every project, or \`.pi/extensions/\` in one project (loaded once the project is trusted), then restarts or runs \`/reload\`. To share it, they make it a pi package and install it with the commands above. Community packages may already exist: search https://pi.dev/packages first, and tell the user to review a package's source before installing it, because extensions run with full access.
+4. If it is a gap or a bug in One Code itself, suggest opening an issue at ${REPO_URL}/issues
+
+**Guidelines:**
+- Your training data does not know One Code. Never answer from memory: every fact about One Code comes from the documentation above. If the docs do not cover the topic, say so rather than guess.
+- Answer questions about One Code (and pi, as far as it shapes One Code) only. For anything else, say it is outside what you cover and suggest asking in the main conversation.
+- Read files with the read tool, not the shell. Use the shell only for read-only searches (\`grep\`, \`find\`). Never edit, write, install or delete anything: when a suggestion needs a file written or a package installed, describe it; the main agent or the user does it.
+- Keep responses concise and actionable
+- Include specific examples, commands or code snippets when helpful
+- Reference the documentation file paths in your responses
+- Help users discover features by proactively suggesting related commands, shortcuts, or capabilities
+
+Complete the user's request by providing accurate, documentation-based guidance.`;
+	const setupText = setupSection(setup);
+	return setupText ? `${prompt}\n\n${setupText}` : prompt;
+}
+
+/**
+ * The definition, with the prompt built on first read: the catalog lists the
+ * guide on every agent listing and spawn, and only a spawn of the guide needs
+ * its prompt (the setup it lists costs a settings read and directory scans).
+ */
+export function guideAgentDefinition(input: () => GuideInput): AgentDefinition {
+	let prompt: string | undefined;
+	return {
+		name: GUIDE_AGENT,
+		description: GUIDE_DESCRIPTION,
+		tools: GUIDE_TOOLS,
+		get systemPrompt() {
+			prompt ??= guideSystemPrompt(input());
+			return prompt;
+		},
+		source: "built-in",
+	};
+}

package/extensions/subagents/hand-back-review.ts

@@ -42,6 +42,8 @@ export function awaitHandBackReview(
 	run: { taskId: string; name: string },
 	actions: ChildAction[] | undefined,
 	timeoutMs = HAND_BACK_REVIEW_TIMEOUT_MS,
+	/** The main-session call that started the turn (SubagentActionsPayload.startedBy). */
+	startedBy?: string,
 ): Promise<HandBackVerdict | undefined> {
 	if (!actions?.length) return Promise.resolve(undefined);
 	return new Promise((resolve) => {
@@ -59,6 +61,7 @@ export function awaitHandBackReview(
 			actions,
 			background: true,
 			agentName: run.name,
+			...(startedBy ? { startedBy } : {}),
 			onReview: finish,
 		} satisfies SubagentActionsPayload);
 	});