one-code-extension 0.5.0 → 0.6.0

package/extensions/plan-mode/index.ts

@@ -19,15 +19,14 @@
  * that prompt. before_agent_start also re-announces the existing state.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerFormTool } from "../lib/tool-variants.ts";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { oneCodeStateDir } from "../lib/paths.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
-import { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.ts";
 import { canShowCustomUi } from "../lib/headless-output.ts";
 import { ccToolRenderers, safeThemePaint } from "../lib/tui-render.ts";
 import { userDenialText } from "../lib/user-denial.ts";
@@ -35,6 +34,18 @@ import type { PermissionMode } from "../permissions/matcher.ts";
 import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
 import { buildPlanModeReminder } from "./reminder.ts";
 import { randomSlug } from "./slug.ts";
+import { readState, recordState } from "../lib/ledger/state.ts";
+
+/** A plan file larger than this is named after a compaction, not inlined: the model reads it when it needs it. */
+const PLAN_REFERENCE_CHARS = 40_000;
+
+/** The plan the summary replaced, re-attached after a compaction. */
+function planFileReferenceText(path: string, content: string): string {
+	if (content.length > PLAN_REFERENCE_CHARS) return `A plan file exists from plan mode at: ${path}\n\nIt is too large to include here (${content.length.toLocaleString("en-US")} characters); read it before continuing.\n\nIf this plan is relevant to the current work and not already complete, continue working on it.`;
+	return `A plan file exists from plan mode at: ${path}\n\nPlan contents:\n\n${content}\n\nIf this plan is relevant to the current work and not already complete, continue working on it.`;
+}
+
+import { PLAN_ENTRY_STATE, parsePlanRun, type PlanRun } from "./run-state.ts";
 import {
 	approvedPlanText,
 	ENTER_PLAN_MODE_DESCRIPTION,
@@ -57,7 +68,7 @@ import {
 	selectPlanChoice,
 } from "./viewer.ts";
 
-import { MODE_CHANNEL, PLAN_FILE_CHANNEL, PLAN_FILE_ENTRY, planFileOnBranch } from "../lib/plan-mode-channels.ts";
+import { MODE_CHANNEL, PLAN_FILE_CHANNEL, PLAN_FILE_ENTRY, planFileOnBranch, planFileRecords, type PlanFileRecord } from "../lib/plan-mode-channels.ts";
 import { panelUi } from "../lib/panel-focus.ts";
 export { MODE_CHANNEL, PLAN_FILE_CHANNEL };
 
@@ -77,48 +88,102 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	/** The last mode broadcast by permissions; undefined until the first status arrives. */
 	let currentMode: string | undefined;
 	/**
-	 * The mode the session was in when it entered plan mode, offered first on
-	 * exit (Claude Code's ExitPlanMode restores `prePlanMode`). Unknown for a
-	 * session that STARTED in plan mode — the first status seen is plan itself —
-	 * so that session gets the fixed list. Until 2026-09-05 the exit could only
-	 * escalate: a default-mode session that planned was offered auto
-	 * (PERMISSIONS-REVIEW-2026-09-05 M4).
+	 * The live mode the last switch into plan mode came from. It is recorded on
+	 * the branch only when that switch begins a run (`refresh` finds no run
+	 * recorded for the branch's plan file). A switch that merely restores a run,
+	 * permissions following a /tree to a branch in plan mode, keeps the branch's
+	 * own value, since the live mode before it belongs to the abandoned branch.
 	 */
-	let modeBeforePlan: PermissionMode | undefined;
-	let planFilePath: string | undefined;
+	let enteredFrom: PermissionMode | undefined;
+	/** Whether the session can enter bypassPermissions, as permissions last said: the exit offers it back only then. */
+	let bypassAvailable = false;
+
 	/**
-	 * Whether the plan file existed when plan mode came on, which picks Claude
-	 * Code's "Plan File Info" line. Fixed for the mode's whole run, so the sticky
-	 * block stays byte-identical turn after turn (plan-mode/reminder.ts);
-	 * cleared when the mode ends.
+	 * The current run as the branch recorded it when plan mode came on: its plan
+	 * file, whether that file existed then (which picks Claude Code's "Plan File
+	 * Info" line, fixed for the run so the sticky block stays byte-identical turn
+	 * after turn, plan-mode/reminder.ts), and the mode it came from, offered
+	 * first on exit (Claude Code's ExitPlanMode restores `prePlanMode`). Read
+	 * from the branch every time, never kept here, so a /reload, a resume and a
+	 * /tree each see the run of the branch they land on. Until 2026-09-05 the
+	 * exit could only escalate: a default-mode session that planned was offered
+	 * auto (PERMISSIONS-REVIEW-2026-09-05 M4).
 	 */
-	let planExistedAtEntry: boolean | undefined;
-
-	/** Restore the branch's plan file, else allocate a fresh slug. */
-	const ensurePlanFile = (ctx: ExtensionContext): string => {
-		if (planFilePath) return planFilePath;
-
-		planFilePath = planFileOnBranch(ctx.sessionManager.getBranch());
-		if (planFilePath) return planFilePath;
+	const runOnBranch = (ctx: ExtensionContext, path: string): PlanRun | undefined => parsePlanRun(readState(ctx, PLAN_ENTRY_STATE), path);
+	/** Record the current run on the branch, for `runOnBranch` to read back. */
+	const recordRun = (path: string, run: PlanRun) => recordState(pi, PLAN_ENTRY_STATE, { path, ...run });
 
+	const freshPlanPath = (): string => {
 		let path = join(PLANS_DIR(), `${randomSlug()}.md`);
 		for (let attempt = 0; attempt < 5 && existsSync(path); attempt++) {
 			path = join(PLANS_DIR(), `${randomSlug()}.md`);
 		}
-		planFilePath = path;
-		pi.appendEntry(PLAN_FILE_ENTRY, { path });
 		return path;
 	};
 
-	/** Re-announce path + reminder; every-turn re-emits replace by key. */
+	/**
+	 * A fork's own copy of the plan another session recorded, as Claude Code
+	 * gives a forked session, so the two sessions never overwrite each other's plan
+	 * (decisions/modes.md). The copy this session already made of it, on any
+	 * of its branches, is reused. The run moves to the copy with the mode it
+	 * came from, and says whether the copy exists (the parent's run may have
+	 * begun before its plan did).
+	 */
+	const forkPlanFile = (ctx: ExtensionContext, parent: PlanFileRecord, sessionId: string): string => {
+		const made = planFileRecords(ctx.sessionManager.getEntries()).find((r) => r.sessionId === sessionId && r.copiedFrom === parent.path);
+		const path = made?.path ?? freshPlanPath();
+		if (!made && existsSync(parent.path)) {
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				copyFileSync(parent.path, path);
+			} catch (error) {
+				if (ctx.hasUI) ctx.ui.notify(`Could not copy the plan at ${parent.path} for this fork (${(error as Error).message}); its plan starts empty at ${path}.`, "warning");
+			}
+		}
+		const run = runOnBranch(ctx, parent.path);
+		pi.appendEntry(PLAN_FILE_ENTRY, { path, sessionId, copiedFrom: parent.path } satisfies PlanFileRecord);
+		// The standing block names the new path anyway, so it also says whether the copy exists.
+		if (run) recordRun(path, { ...run, existed: existsSync(path) });
+		return path;
+	};
+
+	/**
+	 * The branch's plan file, else a fresh slug recorded on the branch. A
+	 * record another session made (a fork copies its parent's entries) gets
+	 * this session's own copy, and so does a record that names no session (an
+	 * older session's): only a record this session made is its own.
+	 * Never cached: on /tree, permissions' session_tree switches the mode (and
+	 * this extension refreshes) before this extension's own session_tree runs,
+	 * so a cached path would be the abandoned branch's.
+	 */
+	const ensurePlanFile = (ctx: ExtensionContext, onBranch = planFileRecords(ctx.sessionManager.getBranch()).at(-1)): string => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (onBranch?.sessionId === sessionId) return onBranch.path;
+		if (onBranch) return forkPlanFile(ctx, onBranch, sessionId);
+
+		const path = freshPlanPath();
+		pi.appendEntry(PLAN_FILE_ENTRY, { path, sessionId } satisfies PlanFileRecord);
+		return path;
+	};
+
+	/** A branch that names a plan file owns it before anything reads it: a fork copies its parent's now. */
+	const ownPlanFile = (ctx: ExtensionContext) => {
+		const onBranch = planFileRecords(ctx.sessionManager.getBranch()).at(-1);
+		if (onBranch?.path) ensurePlanFile(ctx, onBranch);
+	};
+
+	/** Re-announce path + reminder; a re-emit replaces the sticky state by key. */
 	const refresh = (ctx: ExtensionContext, toolCallId?: string) => {
 		const path = ensurePlanFile(ctx);
-		planExistedAtEntry ??= existsSync(path);
-		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "plan-mode", value: { path, existed: planExistedAtEntry } });
+		let run = runOnBranch(ctx, path);
+		if (!run) {
+			// A run begins: record what it began with.
+			run = { existed: existsSync(path), ...(enteredFrom ? { modeBeforePlan: enteredFrom } : {}) };
+			recordRun(path, run);
+		}
 		pi.events.emit(PLAN_FILE_CHANNEL, { path });
 		pi.events.emit(REMINDER_CHANNEL, {
-			text: buildPlanModeReminder(path, planExistedAtEntry),
-			scope: "every-turn",
+			text: buildPlanModeReminder(path, run.existed),
 			key: "permission-mode",
 			placement: "sticky-append",
 			toolCallId,
@@ -151,8 +216,12 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		if (typeof status?.mode !== "string") return;
 		const previous = currentMode;
 		currentMode = status.mode;
-		if (currentMode === "plan" && previous !== "plan") modeBeforePlan = previous as PermissionMode | undefined;
-		if (currentMode !== "plan") planExistedAtEntry = undefined;
+		bypassAvailable = status.bypassAvailable === true;
+		// Unknown for a session that STARTED in plan mode (the first status seen
+		// is plan itself): a run it begins offers the fixed list on exit.
+		if (currentMode === "plan" && previous !== "plan") enteredFrom = previous as PermissionMode | undefined;
+		// The run ended: the next entry decides afresh.
+		if (previous === "plan" && currentMode !== "plan") recordState(pi, PLAN_ENTRY_STATE, null);
 		// Entering plan mode mid-turn: permissions' setMode has just closed the
 		// shared "permission-mode" key (before broadcasting this status, so this
 		// re-add is not undone) and will announce the change on the next tool
@@ -164,14 +233,14 @@ export default function planModeExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", (_event, ctx) => {
 		lastCtx = ctx;
-		const restored = restoredContext(pi.events);
-		const baseline = restored?.baselines["plan-mode"] as { path?: unknown; existed?: unknown } | undefined;
-		const path = planFileOnBranch(ctx.sessionManager.getBranch());
-		if (currentMode === "plan" && restored?.baselines["permission-mode"] === "plan" &&
-			path && baseline?.path === path && typeof baseline.existed === "boolean") {
-			planFilePath = path;
-			planExistedAtEntry = baseline.existed;
-		}
+		ownPlanFile(ctx);
+		if (currentMode === "plan") refresh(ctx);
+	});
+	// The plan file and its run follow the branch (both are read from it): a
+	// /tree switch takes the selected branch's, or allocates one there.
+	pi.on("session_tree", (_event, ctx) => {
+		lastCtx = ctx;
+		ownPlanFile(ctx);
 		if (currentMode === "plan") refresh(ctx);
 	});
 
@@ -180,6 +249,30 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		if (currentMode === "plan") refresh(ctx);
 	});
 
+	// A compaction summarizes the plan away and opens an epoch, where nothing
+	// above has to stay byte-stable (R3-M20). The plan file is re-attached
+	// whenever one exists, plan mode or not, as Claude Code does; in plan mode
+	// the run is recorded again, so the new epoch's block says whether the file
+	// exists now.
+	pi.on("session_compact", (_event, ctx) => {
+		lastCtx = ctx;
+		const path = planFileOnBranch(ctx.sessionManager.getBranch());
+		if (!path) return;
+		if (currentMode === "plan") {
+			recordRun(path, { ...runOnBranch(ctx, path), existed: existsSync(path) });
+			refresh(ctx);
+		}
+		let content = "";
+		try {
+			content = existsSync(path) ? readFileSync(path, "utf8") : "";
+		} catch {
+			// The re-attach is best effort, like the other post-compaction restores:
+			// an unreadable path (a directory, no permission) attaches nothing.
+		}
+		if (!content.trim()) return;
+		pi.events.emit(REMINDER_CHANNEL, { text: planFileReferenceText(path, content), placement: "user-prepend", orTail: true, untilCompaction: true });
+	});
+
 	/**
 	 * enter_plan_mode's description follows the model's tier: Claude Code's,
 	 * which prefers plan mode, on frontier and workhorse, and One Code's, which
@@ -272,11 +365,15 @@ export default function planModeExtension(pi: ExtensionAPI) {
 			// The mode the session was in before planning leads the list (Claude
 			// Code restores it), then auto mode when a classifier model is reachable —
 			// the same gate the mode cycle uses (permissions/index.ts autoInCycle) —
-			// and the fixed choices. Each approving choice carries the mode it
-			// switches to; the final "Keep planning" choice has none and leaves the
-			// session in plan mode.
+			// and the fixed choices. A bypass before planning is offered back only
+			// when this session can grant it (a resume without the bypass flag
+			// cannot, and the request would land in default). Each approving
+			// choice carries the mode it switches to; the final "Keep planning"
+			// choice has none and leaves the session in plan mode.
 			const autoAvailable = ctx.modelRegistry.getAvailable().length > 0;
-			const restore = modeBeforePlan && (modeBeforePlan !== "auto" || autoAvailable) ? modeBeforePlan : undefined;
+			const modeBeforePlan = runOnBranch(ctx, path)?.modeBeforePlan;
+			const offerable = (mode: PermissionMode) => (mode !== "auto" || autoAvailable) && (mode !== "bypassPermissions" || bypassAvailable);
+			const restore = modeBeforePlan && offerable(modeBeforePlan) ? modeBeforePlan : undefined;
 			const fixedModes: PermissionMode[] = [...(autoAvailable ? (["auto"] as const) : []), "acceptEdits", "default"];
 			const options: { label: string; mode?: PermissionMode; restore?: boolean }[] = [
 				...(restore ? [{ label: `Approve — back to ${MODE_NAMES[restore]} (the mode before planning)`, mode: restore, restore: true }] : []),

package/extensions/plan-mode/run-state.ts

@@ -0,0 +1,26 @@
+/**
+ * A plan-mode run as the branch records it (pure, no pi imports): its plan
+ * file's path, whether that file existed when the run began, and the mode the
+ * run came from. plan-mode/index.ts reads and writes the record.
+ */
+import type { PermissionMode } from "../permissions/matcher.ts";
+import { normalizePermissionMode } from "../permissions/settings.ts";
+
+/** The `one-code:state` key of the current plan-mode run. */
+export const PLAN_ENTRY_STATE = "plan-mode:entry";
+
+/** A plan-mode run as the branch records it, beside its plan file's path. */
+export type PlanRun = { existed: boolean; modeBeforePlan?: PermissionMode };
+
+/**
+ * The run `stored` records for the plan file at `path`, or undefined when it
+ * records another file or is malformed. A mode it came from that is unknown,
+ * or plan itself, is dropped: the exit then offers its fixed list.
+ */
+export function parsePlanRun(stored: unknown, path: string): PlanRun | undefined {
+	const record = stored as { path?: unknown; existed?: unknown; modeBeforePlan?: unknown } | null | undefined;
+	if (record?.path !== path || typeof record.existed !== "boolean") return undefined;
+	const mode = normalizePermissionMode(record.modeBeforePlan);
+	const before = mode !== "plan" ? mode : undefined;
+	return { existed: record.existed, ...(before ? { modeBeforePlan: before } : {}) };
+}

package/extensions/plugins/index.ts

@@ -16,6 +16,7 @@
  * ~/.claude is read-only here, always.
  */
 
+import { randomUUID } from "node:crypto";
 import { readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -569,11 +570,13 @@ function registerPluginCommand(pi: ExtensionAPI, plugin: Plugin, name: string, p
 			// user turn: persist it past the cap so the model gets a preview plus
 			// the path, never a wall of text (review L3).
 			const dir = sessionResultsDir(ctx);
+			const runId = randomUUID();
 			let expanded: string;
 			try {
 				// Placeholders run where the session works: an entered worktree, not the checkout it left.
 				expanded = await expandTemplate(body, args, workCwd(ctx.cwd), {
-					persist: (text, index) => persistIfLarge(text, { dir, id: `plugin-cmd-${name}-${index}` }),
+					// A unique id per run: the directory is shared across sessions and processes.
+					persist: (text, index) => persistIfLarge(text, { dir, id: `plugin-cmd-${name}-${runId}-${index}` }),
 					run: async (command, cwd) => {
 						const decide = getPermissionBridge();
 						if (!decide) throw new Error("The permission gate is unavailable. Load the permissions extension before running shell placeholders.");

package/extensions/powershell/index.ts

@@ -91,4 +91,6 @@ export function powershellTool(pi: ExtensionAPI, { announce }: { announce: boole
 
 	pi.on("session_start", (_event, ctx) => reconcile(ctx));
 	pi.on("model_select", () => reconcile());
+	// pi restores the selected branch's tool loadout at a /tree switch.
+	pi.on("session_tree", () => reconcile());
 }

package/extensions/recap/index.ts

@@ -15,7 +15,8 @@
  * compaction extension publishes the capture). Without a capture for the
  * session model, or on a provider API the replay does not cover, it falls back
  * to a small standalone call on a cheap same-containment model
- * (pickEconomicalContainedModel): the last 30 messages and name-only stubs of
+ * (pickEconomicalContainedModel): the current branch's last 30 messages (read
+ * from the session when the recap runs) and name-only stubs of
  * the active tools (some providers reject a history carrying tool_use blocks
  * with no tools declared). The result is a display-only entry (appendEntry,
  * not in LLM context). Best-effort throughout: any failure just shows nothing.
@@ -34,7 +35,7 @@ import { recordUsage } from "../lib/usage-bus.ts";
 import { pickEconomicalContainedModel } from "../lib/model-tier.ts";
 import { CONVERSATION_CACHE_PLACEMENT } from "../lib/side-call-cache.ts";
 import { releaseSideCalls, runSideCall } from "../lib/side-call-run.ts";
-import { answerText, stripImageBlocks, toolStubs, withoutSystemMessages } from "../lib/side-call.ts";
+import { answerText, branchMessages, stripImageBlocks, toolStubs, withoutSystemMessages } from "../lib/side-call.ts";
 import { unrefTimers } from "../lib/timer-ops.ts";
 import { dimMarkedLine } from "../lib/tui-render.ts";
 import { RECAP_PROMPT, recapLine, recentForRecap, REFERENCE_MARK } from "./prompt.ts";
@@ -64,13 +65,7 @@ export default function recapExtension(pi: ExtensionAPI) {
 		return dimMarkedLine(theme, REFERENCE_MARK, recapLine(content));
 	});
 
-	// The exact request messages the session last sent (after every extension's
-	// mutations), captured like the compaction extension does.
-	let capturedMessages: AgentMessage[] | undefined;
-	pi.on("context", (event) => {
-		capturedMessages = event.messages;
-	});
-	// The same request as it went on the wire, and the reply that answered it.
+	// The session's last request as it went on the wire, and the reply that answered it.
 	const exchange = followLastExchange(pi);
 
 	let lastCtx: ExtensionContext | undefined;
@@ -126,8 +121,11 @@ export default function recapExtension(pi: ExtensionAPI) {
 
 	async function generate() {
 		const ctx = lastCtx;
-		const messages = capturedMessages;
-		if (!ctx?.hasUI || !messages?.length || scheduler.hasFiredSinceTurn) return;
+		if (!ctx?.hasUI || scheduler.hasFiredSinceTurn) return;
+		// The current branch, read now: a /tree or a compaction since the last
+		// request changed it, and pi fires no `context` event for either.
+		const messages = branchMessages(ctx);
+		if (!messages.length) return;
 		abortInFlight();
 		const controller = new AbortController();
 		inFlight = controller;
@@ -159,11 +157,10 @@ export default function recapExtension(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
 		lastCtx = ctx;
 		// A new session (including after /clear): drop any timer armed by the
-		// previous session and its captured messages, so a stale recap can never
-		// surface against the fresh conversation.
+		// previous session, so a stale recap can never surface against the
+		// fresh conversation.
 		scheduler.reset();
 		abortInFlight();
-		capturedMessages = undefined;
 		if (!ctx.hasUI) return;
 		// Reset the idle clock on any keystroke — the closest signal to CC's
 		// terminal-blur trigger pi exposes. Registered ONCE (session_start fires

package/extensions/search-tools/index.ts

@@ -27,6 +27,8 @@ export default function searchToolsExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", apply);
 	pi.on("model_select", apply);
+	// pi restores the selected branch's tool loadout at a /tree switch.
+	pi.on("session_tree", apply);
 
 	// Overlapping context windows repeat lines (grep-merge.ts); without context
 	// lines there are no windows to overlap.

package/extensions/skill/announce.ts

@@ -0,0 +1,30 @@
+/**
+ * What to tell the model when the skill set changes (pure).
+ *
+ * The skills listing is a `first-prepend` reminder on message 1, so once a
+ * request has gone out it is the record every later request in the epoch
+ * replays (extensions/ledger); rewriting it would also break the binding of
+ * every earlier signed thinking block (findings §46). As in Claude Code, a
+ * skill that becomes listable later is announced on the request's tail under
+ * the listing's own header, and a skill that leaves the listing is not
+ * announced: the skill tool refuses it by name. A compaction opens an epoch
+ * and re-lists every skill.
+ */
+
+import { skillListingVisibility } from "../lib/skill-overrides.ts";
+import type { ListedSkill } from "./listing.ts";
+
+/** The header Claude Code puts over its skills listing, initial or later. */
+export const SKILL_LISTING_HEADER = "The following skills are available for use with the Skill tool:";
+
+/**
+ * The names the listing shows. `readable` is the read-the-file framing for a
+ * session without the skill tool, which also leaves out plugin commands and
+ * skills without a file (listing.ts `readableSkillListing`).
+ */
+export function listableSkillNames(skills: ReadonlyArray<ListedSkill & { path?: string; kind?: string }>, readable: boolean): string[] {
+	return skills
+		.filter((skill) => !skill.disableModelInvocation && skillListingVisibility(skill.state) !== "hidden")
+		.filter((skill) => !readable || (!skill.kind && skill.path))
+		.map((skill) => skill.name);
+}

package/extensions/skill/index.ts

@@ -25,7 +25,7 @@ import { pluginRoot } from "../lib/plugin-root.ts";
 import { defaultDiscoverRoots, discoverPlugins } from "../lib/plugins.ts";
 import { awaitOneShotTurn, sessionOutlivesTurn } from "../lib/notifications.ts";
 import { PROMPT_OPTIONS_CHANNEL, type PromptOptionsAnnouncement } from "../lib/prompt-options.ts";
-import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { CONTEXT_ORDER, REMINDER_CHANNEL, RENDER_CHANNEL, type RenderRequest } from "../lib/reminders.ts";
 import {
 	nextSkillState,
 	readSkillStates,
@@ -45,7 +45,6 @@ import {
 	launchingSkill,
 	missingArgumentsNote,
 	parseSkillCommand,
-	redactOffSkillMessages,
 	resolveSkill,
 	SKILL_INVOCATION_TYPE,
 	type SkillInvocationDetails,
@@ -58,6 +57,7 @@ import { codeReviewBody } from "./code-review.ts";
 import { decodeSkillsKey } from "./panel/keys.ts";
 import { frontmatterFlag, readableSkillListing, skillListingBudget, skillListingText, usageScore, withoutPiSkillsBlock } from "./listing.ts";
 import { renderSkillsPanel, type SkillsPaint } from "./panel/render.ts";
+import { listableSkillNames, SKILL_LISTING_HEADER } from "./announce.ts";
 import { applySkillsKey, followRow, initialSkillsState, type SkillsRow, visibleRows } from "./panel/state.ts";
 import { announceArgumentHint, type CommandHint, frontmatterCommandHint } from "../lib/argument-hints.ts";
 import { parseSlashCommand, SKILL_BODY_CHANNEL, type SkillBodyQuery, SLASH_EXPAND_CHANNEL, type SlashExpandQuery } from "../lib/skill-body.ts";
@@ -142,6 +142,25 @@ export default function skillExtension(pi: ExtensionAPI) {
 		sessionUsage = undefined;
 		sessionModel = ctx.model;
 	});
+	/** The index as the current run's first request read it; a new run, or pi's skills for it, reads it again. */
+	let runIndex: IndexedSkill[] | undefined;
+	pi.on("agent_start", () => {
+		runIndex = undefined;
+	});
+	// Inside an epoch the listing on message 1 is the record: a skill that became
+	// listable since rides the request's tail with only its own line, decided
+	// when the request goes out from what the epoch has told.
+	pi.events.on(RENDER_CHANNEL, (data) => {
+		const request = data as RenderRequest;
+		if (request.epoch) return;
+		const told = request.told.get("skills") ?? new Set<string>();
+		// Read once per run: a run makes many requests, and the index reads every skill file.
+		const all = (runIndex ??= index());
+		const added = new Set(listableNow(all).filter((name) => !told.has(name)));
+		if (added.size === 0) return;
+		const text = listingText(all.filter((skill) => added.has(skill.name)));
+		if (text) request.blocks.push({ text, facts: [{ kind: "skills", names: [...added] }] });
+	});
 	pi.on("model_select", (event) => {
 		sessionModel = event.model;
 	});
@@ -162,32 +181,44 @@ export default function skillExtension(pi: ExtensionAPI) {
 				disableModelInvocation: record.disableModelInvocation === true || (path ? readModelInvocationDisabled(path) : false),
 			};
 		});
-		// Claude Code lists skills as a <system-reminder> on the first user message
-		// (its block 3), framed for the Skill tool — not in the system prompt. A
-		// session without that tool (an agent limited to read and bash, a main
-		// session started with fewer tools) gets the same block framed for reading
-		// the file, since pi's own section is dropped from every prompt below.
+		announceSkills();
+	};
+	/**
+	 * Claude Code lists skills as a <system-reminder> on the first user message
+	 * (its block 3), framed for the Skill tool — not in the system prompt. A
+	 * session without that tool (an agent limited to read and bash, a main
+	 * session started with fewer tools) gets the same block framed for reading
+	 * the file, since pi's own section is dropped from every prompt below.
+	 * `skills` is the whole index or, for a later notice, only the new ones.
+	 */
+	const listingText = (skills: IndexedSkill[]): string | undefined => {
 		const tools = pi.getActiveTools();
-		if (!tools.includes("skill")) {
-			const readable = readableSkillListing(index(), tools.includes("read") ? "the read tool" : "the shell");
-			if (readable) pi.events.emit(REMINDER_CHANNEL, { text: readable, scope: "every-turn", key: "skills", placement: "first-prepend", order: CONTEXT_ORDER.skills });
+		if (!tools.includes("skill")) return readableSkillListing(skills, tools.includes("read") ? "the read tool" : "the shell");
+		const listing = describe(skills);
+		return listing === "(no skills available)" ? undefined : `${SKILL_LISTING_HEADER}\n\n${listing}`;
+	};
+	const listableNow = (skills: IndexedSkill[]) => listableSkillNames(skills, !pi.getActiveTools().includes("skill"));
+	/** The listing as live state: what an epoch's message 1 says (the render step above announces later skills). */
+	const announceSkills = () => {
+		const all = index();
+		const text = listingText(all);
+		if (!text) {
+			pi.events.emit(REMINDER_CHANNEL, { key: "skills", remove: true });
 			return;
 		}
-		const listing = describe();
-		if (listing !== "(no skills available)") {
-			pi.events.emit(REMINDER_CHANNEL, {
-				text: `The following skills are available for use with the Skill tool:\n\n${listing}`,
-				scope: "every-turn",
-				key: "skills",
-				placement: "first-prepend",
-				order: CONTEXT_ORDER.skills,
-			});
-		}
+		pi.events.emit(REMINDER_CHANNEL, {
+			text,
+			key: "skills",
+			placement: "first-prepend",
+			order: CONTEXT_ORDER.skills,
+			facts: [{ kind: "skills", names: listableNow(all) }],
+		});
 	};
 	pi.on("before_agent_start", (event, ctx) => {
 		prompted = true;
 		sessionModel = ctx.model ?? sessionModel;
 		adoptPiSkills(event.systemPromptOptions.skills ?? [], ctx.cwd);
+		runIndex = undefined;
 		// The listing above is the one skills instruction: drop pi's own section
 		// from the prompt (a child agent's own prompt carries it; the main
 		// session's prompt is rebuilt without it).
@@ -349,10 +380,10 @@ export default function skillExtension(pi: ExtensionAPI) {
 	let sessionUsage: { usage: ReturnType<typeof readUsage>; now: Date } | undefined;
 
 	/** The listing, within Claude Code's budget for the session model's context window. */
-	const describe = () => {
+	const describe = (source: IndexedSkill[] = index()) => {
 		sessionUsage ??= { usage: readUsage(pluginRoot(getAgentDir())), now: new Date() };
 		const { usage, now } = sessionUsage;
-		const skills = index().map((skill) => ({
+		const skills = source.map((skill) => ({
 			...skill,
 			bundled: isBundled(skill.path),
 			usage: usageScore(usage[usageKey(skill.kind ?? "skill", skill.name)], now),
@@ -421,10 +452,11 @@ export default function skillExtension(pi: ExtensionAPI) {
 				};
 			}
 
-			// "off" is the only state that refuses invocation (matching Claude Code,
-			// where invoking an off skill by name returns the skillOverrides error).
-			// "user-only" is invocable — it's just hidden from the model's listing,
-			// so the model won't auto-trigger it, but /skill-name still runs it.
+			// An off skill is refused (matching Claude Code, where invoking an off
+			// skill by name returns the skillOverrides error). A user-only skill is
+			// hidden from the model and runs only as the user's `/<name>`, which does
+			// not come through this tool; a listing frozen before the user hid it can
+			// still name it, so the tool refuses it too (./announce.ts).
 			if (found.state === "off") {
 				const where = found.source === "plugin" ? "/plugins" : "/skills";
 				return {
@@ -433,6 +465,13 @@ export default function skillExtension(pi: ExtensionAPI) {
 					isError: true,
 				};
 			}
+			if (found.state === "user-only") {
+				return {
+					content: [{ type: "text", text: `Skill "${found.name}" is set to user-only — only the user can run it, by typing /${found.name}.` }],
+					details: { skill: found.name, state: found.state } as Record<string, unknown>,
+					isError: true,
+				};
+			}
 
 			// Only the user may start a skill marked `disable-model-invocation`
 			// (a typed `/<name>` runs through deliverSkill, not this tool).
@@ -719,28 +758,6 @@ export default function skillExtension(pi: ExtensionAPI) {
 		if (piSkills.some((skill) => !registeredSkillCommands.has(skill.name) && !oneShotSkillNames.has(skill.name))) registerSkillCommands(ctx.cwd);
 	});
 
-	// FALLBACK for pi < 0.86.0 (plan.md "Fallbacks for older pi"; delete it
-	// when the peer floor reaches 0.86.0). Before faa9863cb, pi's steer() and
-	// followUp() expanded `/skill:<name>` natively WITHOUT firing an `input`
-	// event (queued interactive messages after the first, RPC steer/followUp),
-	// so a turned-off skill's instructions could land in the session history.
-	// On 0.86+ the `input` handler above refuses them first, so this finds
-	// nothing to redact and returns undefined.
-	// Strip them from every outgoing request instead — the wire copy carries the
-	// refusal notice, the session file keeps the original bytes, and untouched
-	// requests return undefined so the message array stays byte-identical
-	// (prompt-cache stable). Override states are read lazily, only when a
-	// message actually contains a `<skill>` block.
-	pi.on("context", (event) => {
-		let states: Map<string, string> | undefined;
-		const isOff = (name: string) => {
-			states ??= new Map(index().map((skill) => [skill.name, skill.state]));
-			return states.get(name) === "off";
-		};
-		const redacted = redactOffSkillMessages(event.messages, isOff);
-		return redacted ? { messages: redacted } : undefined;
-	});
-
 	const buildSkillsRows = (cwd: string | undefined): SkillsRow[] =>
 		skillsOnly(cwd).map((skill) => ({
 			key: skillOverrideKey(skill.scope, skill.name),