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

package/src/task/render.ts

@@ -47,6 +47,12 @@ interface TaskRenderContext {
 }
 type TaskRenderOptions = RenderResultOptions & { renderContext?: TaskRenderContext };
 
+const MAX_NESTED_TASK_RENDER_DEPTH = 8;
+
+function renderNestedCycleLine(theme: Theme): string {
+	return theme.fg("dim", "… nested task progress already shown");
+}
+
 /**
  * Get status icon for agent state.
  * For running status, uses animated spinner if spinnerFrame is provided.
@@ -687,6 +693,8 @@ function renderAgentProgress(
 	theme: Theme,
 	spinnerFrame?: number,
 	frozen = false,
+	seenNestedTasks?: WeakSet<object>,
+	nestedDepth = 0,
 ): string[] {
 	const lines: string[] = [];
 
@@ -859,7 +867,15 @@ function renderAgentProgress(
 	const inflight = progress.inflightTaskDetails;
 	if (completedTaskCalls.length > 0 || inflight) {
 		const snapshots = inflight ? [...completedTaskCalls, inflight] : completedTaskCalls;
-		const nestedLines = renderNestedTaskTree(snapshots, expanded, theme, spinnerFrame, frozen);
+		const nestedLines = renderNestedTaskTree(
+			snapshots,
+			expanded,
+			theme,
+			spinnerFrame,
+			frozen,
+			seenNestedTasks,
+			nestedDepth,
+		);
 		for (const line of nestedLines) {
 			lines.push(`${continuePrefix}${line}`);
 		}
@@ -984,6 +1000,8 @@ function renderAgentResult(
 	continuePrefix: string,
 	expanded: boolean,
 	theme: Theme,
+	seenNestedTasks?: WeakSet<object>,
+	nestedDepth = 0,
 ): string[] {
 	const lines: string[] = [];
 
@@ -1088,11 +1106,24 @@ function renderAgentResult(
 			// Skip review tools - handled above
 			if (toolName === "yield" || toolName === "report_finding") continue;
 
+			const isTaskTool = toolName === "task";
+			if (isTaskTool && (dataArray as unknown[]).length > 0) {
+				for (const line of renderNestedTaskResults(
+					dataArray as TaskToolDetails[],
+					expanded,
+					theme,
+					seenNestedTasks,
+					nestedDepth,
+				)) {
+					deferredToolLines.push(`${continuePrefix}${line}`);
+				}
+				continue;
+			}
+
 			const handler = subprocessToolRegistry.getHandler(toolName);
 			if (handler?.renderFinal && (dataArray as unknown[]).length > 0) {
-				const isTaskTool = toolName === "task";
 				const component = handler.renderFinal(dataArray as unknown[], theme, expanded);
-				const target = isTaskTool ? deferredToolLines : lines;
+				const target = lines;
 				if (!isTaskTool) {
 					hasCustomRendering = true;
 					target.push(`${continuePrefix}${theme.fg("dim", `Tool: ${toolName}`)}`);
@@ -1417,15 +1448,34 @@ function nestedMarkers(isLast: boolean, theme: Theme): { prefix: string; continu
 	};
 }
 
-function renderNestedTaskResults(detailsList: TaskToolDetails[], expanded: boolean, theme: Theme): string[] {
+function renderNestedTaskResults(
+	detailsList: TaskToolDetails[],
+	expanded: boolean,
+	theme: Theme,
+	seen: WeakSet<object> = new WeakSet<object>(),
+	depth = 0,
+): string[] {
 	const lines: string[] = [];
 	for (const details of detailsList) {
-		if (!details.results || details.results.length === 0) continue;
+		if (seen.has(details)) {
+			lines.push(renderNestedCycleLine(theme));
+			continue;
+		}
+		if (depth >= MAX_NESTED_TASK_RENDER_DEPTH) {
+			lines.push(theme.fg("dim", "… nested task depth limit reached"));
+			continue;
+		}
+		seen.add(details);
+		if (!details.results || details.results.length === 0) {
+			seen.delete(details);
+			continue;
+		}
 		const ordered = orderResultsForDisplay(details.results);
 		ordered.forEach((result, index) => {
 			const { prefix, continuePrefix } = nestedMarkers(index === ordered.length - 1, theme);
-			lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
+			lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme, seen, depth + 1));
 		});
+		seen.delete(details);
 	}
 	return lines;
 }
@@ -1441,16 +1491,28 @@ function renderNestedTaskTree(
 	theme: Theme,
 	spinnerFrame?: number,
 	frozen = false,
+	seen: WeakSet<object> = new WeakSet<object>(),
+	depth = 0,
 ): string[] {
 	const lines: string[] = [];
 	for (const details of detailsList) {
+		if (seen.has(details)) {
+			lines.push(renderNestedCycleLine(theme));
+			continue;
+		}
+		if (depth >= MAX_NESTED_TASK_RENDER_DEPTH) {
+			lines.push(theme.fg("dim", "… nested task depth limit reached"));
+			continue;
+		}
+		seen.add(details);
 		const hasResults = Boolean(details.results && details.results.length > 0);
 		if (hasResults) {
 			const ordered = orderResultsForDisplay(details.results);
 			ordered.forEach((result, index) => {
 				const { prefix, continuePrefix } = nestedMarkers(index === ordered.length - 1, theme);
-				lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
+				lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme, seen, depth + 1));
 			});
+			seen.delete(details);
 			continue;
 		}
 		const inflight = details.progress;
@@ -1458,9 +1520,22 @@ function renderNestedTaskTree(
 			const ordered = orderProgressForDisplay(inflight);
 			ordered.forEach((prog, index) => {
 				const { prefix, continuePrefix } = nestedMarkers(index === ordered.length - 1, theme);
-				lines.push(...renderAgentProgress(prog, prefix, continuePrefix, expanded, theme, spinnerFrame, frozen));
+				lines.push(
+					...renderAgentProgress(
+						prog,
+						prefix,
+						continuePrefix,
+						expanded,
+						theme,
+						spinnerFrame,
+						frozen,
+						seen,
+						depth + 1,
+					),
+				);
 			});
 		}
+		seen.delete(details);
 	}
 	return lines;
 }

package/src/task/types.ts

@@ -74,6 +74,11 @@ export interface SubagentLifecyclePayload {
 	detached?: boolean;
 }
 
+/** Display cap for a normalized one-line label (roster line, registry `displayName`, prompt field). */
+export const ROLE_LABEL_MAX = 80;
+/** Schema bound on the raw `role` input, before it is label-normalized at every use site. */
+export const ROLE_INPUT_MAX = 256;
+
 /**
  * One unit of work. The single-spawn schema is `{ agent, ...taskItemSchema }`;
  * the batch schema (`task.batch`) is `{ agent, context, tasks: taskItemSchema[] }`.
@@ -83,6 +88,13 @@ export interface SubagentLifecyclePayload {
 const taskItemShape = {
 	id: z.string().max(48).optional().describe("stable agent id; default generated"),
 	description: z.string().optional().describe("ui label, not seen by subagent"),
+	role: z
+		.string()
+		.max(ROLE_INPUT_MAX)
+		.optional()
+		.describe(
+			"specialist role/expertise this subagent embodies (e.g. 'Rust async-runtime specialist'); shapes its identity and display name",
+		),
 	assignment: z.string().describe("the work; self-contained instructions"),
 };
 const isolatedShape = {
@@ -104,6 +116,8 @@ export interface TaskItem {
 	id?: string;
 	/** UI label, not seen by the subagent. */
 	description?: string;
+	/** Specialist role/expertise this subagent embodies; shapes its system-prompt identity and display name. */
+	role?: string;
 	/** The work; required by the schema. */
 	assignment?: string;
 	/** Run this spawn in an isolated worktree (batch form; flat form carries it top-level). */
@@ -149,6 +163,8 @@ export interface TaskParams {
 	id?: string;
 	/** UI label (flat form), not seen by the subagent. */
 	description?: string;
+	/** Specialist role/expertise this subagent embodies; shapes its system-prompt identity and display name. */
+	role?: string;
 	/** The work (flat form). */
 	assignment?: string;
 	/** Batch form (`task.batch`): one subagent per item. */
@@ -159,6 +175,43 @@ export interface TaskParams {
 	isolated?: boolean;
 }
 
+/**
+ * One-line, length-capped label safe for a single roster line, a registry
+ * `displayName`, or a system-prompt field. Collapses every run of whitespace
+ * AND control/format characters — including U+0085 NEL, ESC/ANSI, and the
+ * zero-width separators that `\s` misses — to a single space, then caps length.
+ * So untrusted text (a spawn `role`, a peer activity gist) can neither break the
+ * line, inject prompt structure, nor smuggle terminal escapes. Caps at `max`
+ * characters (clamped to >= 1; default `ROLE_LABEL_MAX`), appending an ellipsis when truncated.
+ */
+export function oneLineLabel(text: string, max = ROLE_LABEL_MAX): string {
+	const oneLine = text.replace(/[\p{Cc}\p{Cf}\s]+/gu, " ").trim();
+	const cap = Math.max(1, max);
+	// Count/cut by code point, not UTF-16 code unit, so truncation can never
+	// split an astral character into a lone surrogate.
+	const chars = [...oneLine];
+	return chars.length > cap ? `${chars.slice(0, cap - 1).join("")}…` : oneLine;
+}
+
+/**
+ * Display name for a spawned subagent: its tailored `role` (label-normalized)
+ * when one is given, else the agent type's name. Empty/whitespace roles fall
+ * back to the agent name.
+ */
+export function resolveSubagentDisplayName(role: string | undefined, agentName: string): string {
+	const trimmed = role?.trim();
+	return trimmed ? oneLineLabel(trimmed) : agentName;
+}
+
+/**
+ * Whether an agent at `taskDepth` may still spawn children — i.e. it currently
+ * holds the `task` tool. Mirrors the task-tool availability gate;
+ * `maxRecursionDepth < 0` disables the cap entirely.
+ */
+export function canSpawnAtDepth(maxRecursionDepth: number, taskDepth: number): boolean {
+	return maxRecursionDepth < 0 || taskDepth < maxRecursionDepth;
+}
+
 /** A code review finding reported by the reviewer agent */
 export interface ReviewFinding {
 	title: string;

package/src/tools/ask.ts

@@ -23,6 +23,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { ExtensionUISelectItem } from "../extensibility/extensions";
 import { getMarkdownTheme, type Theme, theme } from "../modes/theme/theme";
 import askDescription from "../prompts/tools/ask.md" with { type: "text" };
+import { vocalizer } from "../tts/vocalizer";
 import { framedBlock, renderStatusLine } from "../tui";
 import type { ToolSession } from ".";
 import { formatErrorMessage, formatMeta, formatTitle } from "./render-utils";
@@ -487,6 +488,13 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 			};
 		}
 
+		// Speak the question(s) aloud before surfacing them. Ask vocalizes in every
+		// mode — it's the assistant addressing the user — gated only by speech.enabled
+		// (the vocalizer re-checks the setting and no-ops when disabled).
+		if (this.session.settings.get("speech.enabled")) {
+			vocalizer.speak(params.questions.map(q => q.question).join("\n"));
+		}
+
 		const askQuestion = async (
 			q: AskParams["questions"][number],
 			options?: { previous?: QuestionResult; navigation?: NavigationControls },

package/src/tools/bash.ts

@@ -1385,9 +1385,10 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 		},
 		mergeCallAndResult: true,
 		inline: true,
-		// Pending preview caps the command to a viewport-sized tail window that
-		// shifts while args stream; keep it out of native scrollback mid-run.
-		provisionalPendingPreview: true,
+		// Collapsed pending preview caps the command to a viewport-sized tail
+		// window that shifts while args stream. Expanded output is top-anchored
+		// enough for the transcript to commit its settled prefix.
+		provisionalPendingPreview: "collapsed",
 	};
 }
 

package/src/tools/eval-render.ts

@@ -754,8 +754,9 @@ export const evalToolRenderer = {
 
 	mergeCallAndResult: true,
 	inline: true,
-	// Pending preview shows tail-window code cells; the result render
+	// Collapsed pending preview shows tail-window code cells; the result render
 	// interleaves each cell's output under its code, re-laying-out every row
-	// below the first cell. Keep the preview out of native scrollback mid-run.
-	provisionalPendingPreview: true,
+	// below the first cell. Expanded output is top-anchored enough for the
+	// transcript to commit its settled prefix.
+	provisionalPendingPreview: "collapsed",
 };

package/src/tools/index.ts

@@ -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 */
@@ -255,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. */
@@ -430,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> = {
@@ -510,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".
@@ -543,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/irc.ts

@@ -19,6 +19,7 @@ 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

@@ -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 },
+		};
+	}
+}