@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/src/tools/index.ts

@@ -1,6 +1,6 @@
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
 import type { AgentTelemetryConfig, AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { FetchImpl, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { FetchImpl, Model, ToolChoice } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJobManager } from "../async/job-manager";
 import type { Rule } from "../capability/rule";
@@ -22,9 +22,11 @@ import type { AgentRegistry } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
+import type { UsageStatistics } from "../session/session-entries";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import { TaskTool } from "../task";
 import type { AgentOutputManager } from "../task/output-manager";
+import { canSpawnAtDepth } from "../task/types";
 import { countToolsForAutoDiscovery, resolveEffectiveToolDiscoveryMode } from "../tool-discovery/mode";
 import type { DiscoverableTool, DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
 import type { EventBus } from "../utils/event-bus";
@@ -44,6 +46,8 @@ import { GithubTool } from "./gh";
 import { InspectImageTool } from "./inspect-image";
 import { IrcTool, isIrcEnabled } from "./irc";
 import { JobTool } from "./job";
+import { LearnTool } from "./learn";
+import { ManageSkillTool } from "./manage-skill";
 import { MemoryEditTool } from "./memory-edit";
 import { MemoryRecallTool } from "./memory-recall";
 import { MemoryReflectTool } from "./memory-reflect";
@@ -82,6 +86,8 @@ export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./learn";
+export * from "./manage-skill";
 export * from "./memory-edit";
 export * from "./memory-recall";
 export * from "./memory-reflect";
@@ -144,6 +150,13 @@ export interface ToolSession {
 	cwd: string;
 	/** Whether UI is available */
 	hasUI: boolean;
+	/**
+	 * Suppress the spawn specialization/coordination advisory appended to `task`
+	 * results. Set by internal/programmatic callers (e.g. the commit agent's
+	 * file-analysis fan-out) whose results are consumed by code — not by a model
+	 * orchestrating further spawns — so the nudge would only be noise.
+	 */
+	suppressSpawnAdvisory?: boolean;
 	/** Optional fetch implementation injected into the URL read pipeline (tests, proxies). Defaults to global fetch. */
 	fetch?: FetchImpl;
 	/** Skip Python kernel availability check and warmup */
@@ -217,6 +230,8 @@ export interface ToolSession {
 	getModelString?: () => string | undefined;
 	/** Get the current session model string, regardless of how it was chosen */
 	getActiveModelString?: () => string | undefined;
+	/** Get the current session model object (provider/api capabilities), regardless of how it was chosen. */
+	getActiveModel?: () => Model | undefined;
 	/** Auth storage for passing to subagents (avoids re-discovery) */
 	authStorage?: import("../session/auth-storage").AuthStorage;
 	/** Model registry for passing to subagents (avoids re-discovery) */
@@ -253,7 +268,7 @@ export interface ToolSession {
 	/** Goal runtime for the active agent session. */
 	getGoalRuntime?: () => GoalRuntime | undefined;
 	/** Get cumulative session usage statistics (input/output tokens, cost). */
-	getUsageStatistics?: () => import("../session/session-manager").UsageStatistics;
+	getUsageStatistics?: () => UsageStatistics;
 	/** Current per-turn token budget {total, spent, hard} for the eval `budget` helper. */
 	getTurnBudget?: () => { total: number | null; spent: number; hard: boolean };
 	/** Record output tokens consumed by an eval-spawned subagent toward the current turn budget. */
@@ -428,6 +443,8 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	retain: MemoryRetainTool.createIf,
 	recall: MemoryRecallTool.createIf,
 	reflect: MemoryReflectTool.createIf,
+	learn: LearnTool.createIf,
+	manage_skill: ManageSkillTool.createIf,
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
@@ -508,6 +525,21 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 				if (!requestedTools.includes(name)) requestedTools.push(name);
 			}
 		}
+		// Auto-learn tools are gated by `autolearn.enabled` but, like the memory
+		// tools above, must also be force-included into an explicit requestedTools
+		// list so a restricted top-level session whose controller/guidance is
+		// active still exposes the tools the nudge points at. Gated to top-level
+		// (taskDepth 0): the controller only runs there, so a subagent's explicit
+		// tool whitelist must never be silently widened with write-capable tools.
+		if (session.settings.get("autolearn.enabled") && (session.taskDepth ?? 0) === 0) {
+			if (!requestedTools.includes("manage_skill")) requestedTools.push("manage_skill");
+			if (
+				["hindsight", "mnemopi", "local"].includes(session.settings.get("memory.backend") ?? "") &&
+				!requestedTools.includes("learn")
+			) {
+				requestedTools.push("learn");
+			}
+		}
 	}
 	// Resolve effective tool discovery mode.
 	// tools.discoveryMode controls the new modes; mcp.discoveryMode remains a back-compat alias for "mcp-only".
@@ -541,10 +573,16 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "retain" || name === "recall" || name === "reflect") {
 			return ["hindsight", "mnemopi"].includes(session.settings.get("memory.backend") ?? "");
 		}
+		if (name === "manage_skill") return session.settings.get("autolearn.enabled") && (session.taskDepth ?? 0) === 0;
+		if (name === "learn") {
+			return (
+				session.settings.get("autolearn.enabled") &&
+				(session.taskDepth ?? 0) === 0 &&
+				["hindsight", "mnemopi", "local"].includes(session.settings.get("memory.backend") ?? "")
+			);
+		}
 		if (name === "task") {
-			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;
-			const currentDepth = session.taskDepth ?? 0;
-			return maxDepth < 0 || currentDepth < maxDepth;
+			return canSpawnAtDepth(session.settings.get("task.maxRecursionDepth") ?? 2, session.taskDepth ?? 0);
 		}
 		return true;
 	};

package/src/tools/inspect-image.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
 import { type Api, completeSimple, type Model } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { extractTextContent } from "../commit/utils";
 
 import { expandRoleAlias, getModelMatchPreferences, resolveModelFromString } from "../config/model-resolver";
@@ -13,6 +13,7 @@ import {
 	type LoadedImageInput,
 	loadImageInput,
 	MAX_IMAGE_INPUT_BYTES,
+	webpExclusionForModel,
 } from "../utils/image-loading";
 import type { ToolSession } from "./index";
 import { ToolError } from "./tool-errors";
@@ -109,6 +110,7 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 				cwd: this.session.cwd,
 				autoResize: this.session.settings.get("images.autoResize"),
 				maxBytes: MAX_IMAGE_INPUT_BYTES,
+				excludeWebP: webpExclusionForModel(model),
 			});
 		} catch (error) {
 			if (error instanceof ImageInputTooLargeError) {

package/src/tools/irc.ts

@@ -12,13 +12,14 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { formatAge, formatDuration, prompt } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { IrcBus, type IrcDeliveryReceipt, type IrcMessage } from "../irc/bus";
 import type { Theme } from "../modes/theme/theme";
 import ircDescription from "../prompts/tools/irc.md" with { type: "text" };
 import type { AgentRegistry } from "../registry/agent-registry";
+import { canSpawnAtDepth } from "../task/types";
 import { Ellipsis, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from ".";
 import {
@@ -41,8 +42,10 @@ const DEFAULT_IRC_TIMEOUT_MS = 120_000;
  */
 export function isIrcEnabled(settings: Settings, taskDepth: number): boolean {
 	if (taskDepth > 0) return true;
+	// Top-level session: peers exist only if it can still spawn subagents — the
+	// same capacity gate the task tool uses, reused here to avoid drift.
 	const maxDepth = settings.get("task.maxRecursionDepth") ?? 2;
-	return maxDepth < 0 || taskDepth < maxDepth;
+	return canSpawnAtDepth(maxDepth, taskDepth);
 }
 
 const ircSchema = z.object({
@@ -66,6 +69,7 @@ interface IrcPeerInfo {
 	parentId?: string;
 	unread: number;
 	lastActivity: number;
+	activity?: string;
 }
 
 export interface IrcDetails {
@@ -146,6 +150,7 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 				parentId: ref.parentId,
 				unread: bus.unreadCount(ref.id),
 				lastActivity: ref.lastActivity,
+				activity: ref.activity,
 			}));
 		const lines: string[] = [];
 		if (peers.length === 0) {
@@ -154,6 +159,7 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 			lines.push(`${peers.length} peer(s):`);
 			for (const peer of peers) {
 				const extras = [
+					peer.activity || undefined,
 					peer.unread > 0 ? `unread ${peer.unread}` : undefined,
 					peer.parentId ? `parent ${peer.parentId}` : undefined,
 					`active ${formatDuration(Date.now() - peer.lastActivity)} ago`,
@@ -673,7 +679,9 @@ function renderListResult(details: Partial<IrcDetails>, expanded: boolean, theme
 				const kindText = peer.parentId ? `${peer.kind}${theme.sep.dot}of ${peer.parentId}` : peer.kind;
 				const unread = peer.unread > 0 ? ` ${formatBadge(`${peer.unread} unread`, "warning", theme)}` : "";
 				const age = messageAge(peer.lastActivity);
-				return `${peerStatusBadge(peer.status, theme)} ${theme.bold(replaceTabs(peer.id))} ${theme.fg("dim", kindText)}${unread}${age ? ` ${theme.fg("dim", age)}` : ""}`;
+				const activity = peer.activity ? ` ${theme.fg("dim", replaceTabs(peer.activity))}` : "";
+				const name = theme.fg("dim", replaceTabs(peer.displayName));
+				return `${peerStatusBadge(peer.status, theme)} ${theme.bold(replaceTabs(peer.id))} ${name} ${theme.fg("dim", kindText)}${activity}${unread}${age ? ` ${theme.fg("dim", age)}` : ""}`;
 			},
 		},
 		theme,

package/src/tools/job.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { AsyncJob, AsyncJobManager } from "../async";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { shimmerEnabled, shimmerText } from "../modes/theme/shimmer";
@@ -184,9 +184,16 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			return this.#buildResult(manager, [...cancelledJobs, ...jobsToWatch], cancelOutcomes);
 		}
 
-		// Wait until at least one running job finishes, the wait duration elapses, or the call is aborted.
+		// Wait until at least one running job finishes, the wait window elapses,
+		// or the call is aborted. With `async.pollWaitDuration` set to `smart`,
+		// the window adapts: it starts at the ladder floor and climbs as the agent
+		// polls in a tight loop, then resets to the floor once the agent steps
+		// away from polling (see AsyncJobManager.nextPollWaitMs). Any fixed value
+		// waits that exact duration every time.
 		const racePromises: Promise<unknown>[] = runningJobs.map(j => j.promise);
-		const waitMs = parseWaitDurationMs(this.session.settings.get("async.pollWaitDuration"));
+		const pollSetting = this.session.settings.get("async.pollWaitDuration");
+		const smartPoll = pollSetting === "smart";
+		const waitMs = smartPoll ? manager.nextPollWaitMs(ownerId) : parseWaitDurationMs(pollSetting);
 		const { promise: timeoutPromise, resolve: timeoutResolve } = Promise.withResolvers<void>();
 		const timeoutHandle = setTimeout(() => timeoutResolve(), waitMs);
 		racePromises.push(timeoutPromise);
@@ -232,6 +239,11 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			manager.unwatchJobs(watchedJobIds);
 			clearTimeout(timeoutHandle);
 			if (progressTimer) clearInterval(progressTimer);
+			if (smartPoll) {
+				// Reset the idle-gap clock: escalate if the agent polls again soon,
+				// drop back to the floor once it goes quiet for a while.
+				manager.recordPollWaitEnd(ownerId);
+			}
 		}
 
 		return this.#buildResult(manager, allTrackedJobs, cancelOutcomes);

package/src/tools/learn.ts

@@ -0,0 +1,144 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { z } from "zod/v4";
+import { sanitizeSkillName, writeManagedSkill } from "../autolearn/managed-skills";
+import { isNameClaimedByAuthoredSkill } from "../extensibility/skills";
+import { localBackend } from "../memory-backend/local-backend";
+import learnDescription from "../prompts/tools/learn.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const learnSchema = z.object({
+	memory: z.string().describe("the durable, self-contained lesson to remember (what, when, why)"),
+	context: z.string().describe("optional source context for the lesson").optional(),
+	skill: z
+		.object({
+			action: z.enum(["create", "update"]),
+			name: z.string().describe("kebab-case skill name"),
+			description: z.string().describe("one-line description of when to use the skill"),
+			body: z.string().describe("the SKILL.md body in markdown (no frontmatter)"),
+		})
+		.describe("also create or enhance a managed skill in the same call")
+		.optional(),
+});
+
+export type LearnParams = z.infer<typeof learnSchema>;
+
+/**
+ * Orchestrating "learn" tool: persists a lesson to long-term memory and,
+ * given a `skill` payload, mints/enhances a managed skill via the shared
+ * `writeManagedSkill` primitive. Gated behind `autolearn.enabled` plus a live
+ * memory backend — `hindsight`/`mnemopi` (remote/SQLite) or `local` (the
+ * file-based rollout backend, where lessons append to `learned.md`).
+ */
+export class LearnTool implements AgentTool<typeof learnSchema> {
+	readonly name = "learn";
+	readonly approval = (args: unknown) =>
+		(args as Partial<LearnParams>).skill || this.session.settings.get("memory.backend") === "local"
+			? "write"
+			: "read";
+	readonly label = "Learn";
+	readonly description = learnDescription;
+	readonly parameters = learnSchema;
+	readonly strict = true;
+	readonly loadMode = "essential" as const;
+	readonly summary = "Capture a reusable lesson to memory (and optionally a managed skill)";
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): LearnTool | null {
+		if (!session.settings.get("autolearn.enabled")) return null;
+		const backend = session.settings.get("memory.backend");
+		if (backend !== "hindsight" && backend !== "mnemopi" && backend !== "local") return null;
+		return new LearnTool(session);
+	}
+
+	async execute(_id: string, params: LearnParams): Promise<AgentToolResult> {
+		// 1) Persist or queue the lesson to long-term memory (mirrors MemoryRetainTool).
+		const backend = this.session.settings.get("memory.backend");
+		let memoryMessage = "Lesson stored";
+		if (backend === "mnemopi") {
+			const state = this.session.getMnemopiSessionState?.();
+			if (!state) {
+				throw new Error("Mnemopi backend is not initialised for this session.");
+			}
+			const id = state.rememberScoped(params.memory, {
+				source: "coding-agent-learn",
+				importance: 0.8,
+				metadata: {
+					session_id: state.sessionId,
+					cwd: state.session.sessionManager.getCwd(),
+					context: params.context ?? null,
+					tool: "learn",
+				},
+				scope: "bank",
+				extract: true,
+				extractEntities: true,
+				veracity: "tool",
+				memoryType: "fact",
+			});
+			// rememberScoped returns undefined when the retain failed (closed DB /
+			// disk error); mirror mnemopiBackend.save and fail loudly rather than
+			// reporting (and minting a skill for) a lesson that was silently dropped.
+			if (!id) {
+				throw new Error("Mnemopi did not store the lesson (no memory id returned).");
+			}
+		} else if (backend === "local") {
+			const result = await localBackend.save?.(
+				{ agentDir: this.session.settings.getAgentDir(), cwd: this.session.settings.getCwd() },
+				{ content: params.memory, context: params.context, source: "coding-agent-learn", importance: 0.8 },
+			);
+			if (!result || result.stored === 0) {
+				throw new Error("Lesson was empty after sanitization; nothing stored.");
+			}
+		} else {
+			const state = this.session.getHindsightSessionState?.();
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+			state.enqueueRetain(params.memory, params.context);
+			memoryMessage = "Lesson queued for retention";
+		}
+
+		// 2) Optionally mint/enhance a managed skill. A failure here is surfaced
+		// as a partial outcome — the lesson is already stored or queued.
+		if (params.skill) {
+			// A managed skill resolves below any authored skill of the same name, so
+			// minting one under a claimed name writes a file that never surfaces. The
+			// lesson is already stored/queued; refuse the skill rather than report a
+			// false "Created" (mirrors ManageSkillTool).
+			let safeSkillName: string | undefined;
+			try {
+				safeSkillName = sanitizeSkillName(params.skill.name);
+			} catch {
+				safeSkillName = undefined;
+			}
+			if (params.skill.action === "create" && safeSkillName && isNameClaimedByAuthoredSkill(safeSkillName)) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${memoryMessage}. Did not create managed skill "${params.skill.name}": an authored skill of that name already exists, and managed skills cannot override authored ones. Choose a different name.`,
+						},
+					],
+					isError: true,
+					details: { skill: null, shadowed: true },
+				};
+			}
+			try {
+				await writeManagedSkill(params.skill);
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				throw new Error(`${memoryMessage}, but the managed skill could not be written: ${reason}`);
+			}
+			const verb = params.skill.action === "create" ? "Created" : "Updated";
+			return {
+				content: [{ type: "text", text: `${memoryMessage}. ${verb} managed skill "${params.skill.name}".` }],
+				details: { skill: params.skill.name },
+			};
+		}
+
+		return {
+			content: [{ type: "text", text: `${memoryMessage}.` }],
+			details: { skill: null },
+		};
+	}
+}

package/src/tools/manage-skill.ts

@@ -0,0 +1,104 @@
+import * as path from "node:path";
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { z } from "zod/v4";
+import {
+	deleteManagedSkill,
+	getManagedSkillsDir,
+	sanitizeSkillName,
+	writeManagedSkill,
+} from "../autolearn/managed-skills";
+import { isNameClaimedByAuthoredSkill } from "../extensibility/skills";
+import manageSkillDescription from "../prompts/tools/manage-skill.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const manageSkillSchema = z
+	.object({
+		action: z.enum(["create", "update", "delete"]),
+		name: z.string().describe("kebab-case skill name"),
+		description: z
+			.string()
+			.describe("one-line description of when to use the skill (required for create/update)")
+			.optional(),
+		body: z
+			.string()
+			.describe("the SKILL.md body in markdown, no frontmatter (required for create/update)")
+			.optional(),
+	})
+	// Enforce the action/field contract at validation time rather than only in
+	// execute. Kept as a cross-field refine (not a discriminated union) so the
+	// wire schema stays a single root object — strict structured-output mode and
+	// the Anthropic tool-schema builder both require that.
+	.refine(p => p.action === "delete" || (p.description !== undefined && p.body !== undefined), {
+		message: '"create" and "update" require both "description" and "body".',
+		path: ["description"],
+	});
+
+export type ManageSkillParams = z.infer<typeof manageSkillSchema>;
+
+/**
+ * Direct create/update/delete of isolated managed skills. Gated behind
+ * `autolearn.enabled`; backend-independent (the skill side is standalone).
+ */
+export class ManageSkillTool implements AgentTool<typeof manageSkillSchema> {
+	readonly name = "manage_skill";
+	readonly approval = "write" as const;
+	readonly label = "Manage Skill";
+	readonly description = manageSkillDescription;
+	readonly parameters = manageSkillSchema;
+	readonly strict = true;
+	readonly loadMode = "essential" as const;
+	readonly summary = "Create, update, or delete an isolated managed skill";
+
+	// No session state needed: createIf reads settings; writes target the
+	// home-based managed-skills dir directly.
+	static createIf(session: ToolSession): ManageSkillTool | null {
+		if (!session.settings.get("autolearn.enabled")) return null;
+		return new ManageSkillTool();
+	}
+
+	async execute(_id: string, params: ManageSkillParams): Promise<AgentToolResult> {
+		if (params.action === "delete") {
+			await deleteManagedSkill(params.name);
+			return {
+				content: [{ type: "text", text: `Deleted managed skill "${params.name}".` }],
+				details: { action: "delete", name: params.name },
+			};
+		}
+
+		// Defensive narrowing: the schema refine already rejects create/update
+		// without both fields, so this is unreachable for valid input — it only
+		// proves the strings are present to `writeManagedSkill`'s typed contract.
+		if (!params.description || !params.body) {
+			throw new Error(`"${params.action}" requires both "description" and "body".`);
+		}
+		// A managed skill resolves below any authored skill of the same name
+		// (authored always wins in discovery), so creating one under a name an
+		// authored skill already claims writes a file that never surfaces. Refuse
+		// up front rather than report a false "Created". `sanitizeSkillName`
+		// normalizes to the on-disk name the discovery scan compares against.
+		if (params.action === "create" && isNameClaimedByAuthoredSkill(sanitizeSkillName(params.name))) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Cannot create managed skill "${params.name}": an authored skill of that name already exists, and managed skills cannot override authored ones. Choose a different name.`,
+					},
+				],
+				isError: true,
+				details: { action: "create", name: params.name, shadowed: true },
+			};
+		}
+		const { path: skillPath } = await writeManagedSkill({
+			action: params.action,
+			name: params.name,
+			description: params.description,
+			body: params.body,
+		});
+		const relativePath = path.relative(getManagedSkillsDir(), skillPath);
+		const verb = params.action === "create" ? "Created" : "Updated";
+		return {
+			content: [{ type: "text", text: `${verb} managed skill "${params.name}" (managed-skills/${relativePath}).` }],
+			details: { action: params.action, name: params.name },
+		};
+	}
+}

package/src/tools/memory-edit.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import memoryEditDescription from "../prompts/tools/memory-edit.md" with { type: "text" };
 import type { ToolSession } from ".";
 

package/src/tools/memory-recall.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { logger, untilAborted } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { formatCurrentTime, formatMemories } from "../hindsight/content";
 import recallDescription from "../prompts/tools/recall.md" with { type: "text" };
 import type { ToolSession } from ".";

package/src/tools/memory-reflect.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { logger, untilAborted } from "@oh-my-pi/pi-utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { ensureBankExists } from "../hindsight/bank";
 import reflectDescription from "../prompts/tools/reflect.md" with { type: "text" };
 import type { ToolSession } from ".";

package/src/tools/memory-retain.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
 import type { ToolSession } from ".";
 

package/src/tools/plan-mode-guard.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { HL_FILE_HASH_LENGTH, HL_FILE_HASH_SEP, HL_FILE_PREFIX, HL_FILE_SUFFIX } from "@oh-my-pi/hashline";
 import { resolveLocalRoot, resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
@@ -7,6 +8,7 @@ import { ToolError } from "./tool-errors";
 
 const VAULT_SCHEME_PREFIX = "vault:";
 const LOCAL_SCHEME_PREFIX = "local:";
+const HL_TRAILING_TAG_RE = new RegExp(`${HL_FILE_HASH_SEP}[0-9A-Fa-f]{${HL_FILE_HASH_LENGTH}}$`);
 
 /** Resolve the absolute path of the session's `local://` artifact sandbox.
  *  Returns `null` when the session has no artifact wiring (e.g. tests). */
@@ -30,29 +32,57 @@ function isWithinRoot(absolutePath: string, root: string): boolean {
 	return absolutePath.startsWith(sep);
 }
 
-/** True when `targetPath` addresses the session-local artifact sandbox.
- *  Accepts both `local://…` URLs and absolute paths pointing inside the
- *  resolved sandbox root — the latter is what `read local://…` echoes back
- *  in the `[path#tag]` header. Those files are not part of the working tree,
- *  so plan mode treats them as freely writable scratch/plan space. */
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export function unwrapHashlineHeaderPath(targetPath: string): string {
+	const trimmed = targetPath.trimEnd();
+	if (
+		trimmed.length < HL_FILE_PREFIX.length + HL_FILE_SUFFIX.length ||
+		trimmed[0] !== HL_FILE_PREFIX ||
+		trimmed[trimmed.length - 1] !== HL_FILE_SUFFIX
+	) {
+		return targetPath;
+	}
+	const inner = trimmed.slice(HL_FILE_PREFIX.length, trimmed.length - HL_FILE_SUFFIX.length);
+	const tagMatch = HL_TRAILING_TAG_RE.exec(inner);
+	const pathPart = tagMatch ? inner.slice(0, tagMatch.index) : inner;
+	// A valid header is exactly `PATH` or `PATH#XXXX`; reject any other shape
+	// (selectors, non-hex tags, embedded `#`) so we never silently rewrite a
+	// path the model did not author.
+	if (pathPart.length === 0 || pathPart.includes(HL_FILE_HASH_SEP)) return targetPath;
+	return pathPart;
+}
+
+/** True when `targetPath` resolves into the session-local artifact sandbox.
+ *  Routes through {@link resolvePlanPath} so the guard and the eventual write
+ *  always agree on the absolute target (including bracketed hashline headers,
+ *  `local://` URLs, and bare absolute paths). Files inside the sandbox are not
+ *  part of the working tree, so plan mode treats them as freely writable
+ *  scratch/plan space. */
 function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean {
-	const normalized = normalizeLocalScheme(targetPath);
-	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) return true;
-	if (!path.isAbsolute(normalized)) return false;
 	const root = localSandboxRoot(session);
 	if (!root) return false;
-	// Compare both raw and realpath-normalized forms so that
-	// `/tmp/…` vs `/private/tmp/…` (macOS) and other symlink-collapsed
-	// roots both resolve to the same sandbox identity.
-	const resolved = path.resolve(normalized);
-	if (isWithinRoot(resolved, root)) return true;
+	let resolved: string;
+	try {
+		resolved = resolvePlanPath(session, targetPath);
+	} catch {
+		return false;
+	}
+	if (!path.isAbsolute(resolved)) return false;
+	const absolute = path.resolve(resolved);
+	if (isWithinRoot(absolute, root)) return true;
+	// Compare realpath-normalized forms so that `/tmp/…` vs `/private/tmp/…`
+	// (macOS) and other symlink-collapsed roots both resolve to the same
+	// sandbox identity.
 	try {
 		const realRoot = fs.realpathSync.native(root);
-		if (isWithinRoot(resolved, realRoot)) return true;
-		// `resolved` itself may live in `/tmp/...` while `realRoot` is `/private/tmp/...`;
-		// realpath the parent dir of `resolved` so we catch that direction too.
-		const realParent = fs.realpathSync.native(path.dirname(resolved));
-		return isWithinRoot(path.join(realParent, path.basename(resolved)), realRoot);
+		if (isWithinRoot(absolute, realRoot)) return true;
+		const realParent = fs.realpathSync.native(path.dirname(absolute));
+		return isWithinRoot(path.join(realParent, path.basename(absolute)), realRoot);
 	} catch {
 		return false;
 	}
@@ -61,9 +91,13 @@ function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean
 /**
  * Resolve a write/edit target to its absolute filesystem path, honoring the
  * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
  */
 export function resolvePlanPath(session: ToolSession, targetPath: string): string {
-	const normalized = normalizeLocalScheme(targetPath);
+	const unwrapped = unwrapHashlineHeaderPath(targetPath);
+	const normalized = normalizeLocalScheme(unwrapped);
 	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) {
 		return resolveLocalUrlToPath(normalized, {
 			getArtifactsDir: session.getArtifactsDir,