@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/grouping.ts

@@ -96,7 +96,7 @@ function visibleLines(lines: string[]): string[] {
 
 function stripLeadingStatusIcon(line: string): string {
 	return line.replace(
-		/^((?:\x1b\[[0-9;]*m|[ \t]|[├└│─])*)(?:\x1b\[[0-9;]*m)*(?:[✓✗●○■⬤•·])(?:\x1b\[[0-9;]*m)*\s+/,
+		/^((?:\x1b\[[0-9;]*m|[ \t]|[├└│─])*)(?:\x1b\[[0-9;]*m)*(?:[✓✗●○■⬤•·⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏])(?:\x1b\[[0-9;]*m)*\s+/,
 		"$1",
 	);
 }
@@ -127,6 +127,10 @@ function stripLeadingSpaces(line: string, count: number): string {
 }
 
 /** 生成一行铺满 width 的 slot 背景行；bgAnsiOverride 可替换背景 ANSI（用于提亮等）。 */
+function panelInnerWidth(width: number): number {
+	return Math.max(0, Math.floor(width) - 2);
+}
+
 export function paddedBackgroundRow(
 	theme: any,
 	slot: string,
@@ -134,9 +138,12 @@ export function paddedBackgroundRow(
 	width: number,
 	bgAnsiOverride?: string,
 ): string {
-	const innerWidth = Math.max(0, width - 2);
+	const safeWidth = Math.max(0, Math.floor(width));
+	const leftPadding = safeWidth > 0 ? " " : "";
+	const rightPadding = safeWidth > 1 ? " " : "";
+	const innerWidth = panelInnerWidth(width);
 	const clipped = truncateToWidth(stripBackgroundAnsi(content), innerWidth, "");
-	const row = ` ${clipped}${" ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} `;
+	const row = `${leftPadding}${clipped}${" ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)))}${rightPadding}`;
 	const bgAnsi =
 		bgAnsiOverride ||
 		(typeof theme?.bg === "function"
@@ -147,11 +154,10 @@ export function paddedBackgroundRow(
 	return `${bgAnsi}${stable}\x1b[49m`;
 }
 
-function oneLine(value: unknown, max = 96): string {
-	const text = sanitizeToolResultText(String(value ?? ""), 4096)
+function oneLine(value: unknown): string {
+	return sanitizeToolResultText(String(value ?? ""), 4096)
 		.replace(/\s+/g, " ")
 		.trim();
-	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 
 function humanizeToolName(name: string): string {
@@ -264,6 +270,10 @@ function toolNameList(tools: any[]): string {
 
 let nextGroupId = 1;
 
+function groupChildWidth(width: number): number {
+	return Math.max(1, panelInnerWidth(width));
+}
+
 export class ToolGroupComponent extends Container {
 	readonly toolCallId = `ccstyle-tool-group-${nextGroupId++}`;
 	readonly toolName = "Tool group";
@@ -311,7 +321,7 @@ export class ToolGroupComponent extends Container {
 
 	/**
 	 * 展开时按局部行定位内部组件（null = 行属于 group 自身：空行/头行/尾行）。
-	 * 行数计算与 render 保持一致：宽度 width-2 + 空行过滤。
+	 * 行数计算与 render 保持一致：预留背景 padding、分支和状态前缀后再过滤空行。
 	 */
 	childAtRow(localRow: number, width: number): { component: any; row: number } | null {
 		if (!this._expanded || localRow < 2) return null;
@@ -319,7 +329,7 @@ export class ToolGroupComponent extends Container {
 		for (const tool of this.children) {
 			let lines: string[] = [];
 			try {
-				const rendered = tool.render?.(Math.max(1, width - 2));
+				const rendered = tool.render?.(groupChildWidth(width));
 				if (Array.isArray(rendered)) lines = visibleLines(rendered.map((line) => String(line)));
 			} catch {
 				lines = [];
@@ -386,7 +396,7 @@ export class ToolGroupComponent extends Container {
 				);
 				continue;
 			}
-			const rendered = visibleLines(tool.render(Math.max(1, width - 2)));
+			const rendered = visibleLines(tool.render(groupChildWidth(width)));
 			if (rendered.length) {
 				rendered[0] = stripLeadingStatusIcon(rendered[0])
 					.replace(/^ +/, "")
@@ -434,7 +444,7 @@ function ungroup(patch: Patch): void {
 	}
 }
 
-function normalizeGroup(patch: Patch, group: ToolGroupComponent): void {
+function normalizeGroup(group: ToolGroupComponent): void {
 	if (group.children.length > 1) return;
 	const parent = (group as any)[PARENT_KEY];
 	const index = parent?.children?.indexOf(group) ?? -1;
@@ -565,12 +575,12 @@ export function installToolGrouping(getEnabled: () => boolean): ToolGroupingHook
 			const group = component?.[PARENT_KEY];
 			if (group instanceof ToolGroupComponent && (group as any)[PARENT_KEY] === this) {
 				group.removeTool(component);
-				normalizeGroup(patch, group);
+				normalizeGroup(group);
 				return;
 			}
 			const result = patch.original.removeChild.call(this, component);
 			if (component?.[PARENT_KEY] === this) delete component[PARENT_KEY];
-			if (this instanceof ToolGroupComponent) normalizeGroup(patch, this);
+			if (this instanceof ToolGroupComponent) normalizeGroup(this);
 			if (component instanceof ToolGroupComponent) {
 				for (const tool of component.releaseTools()) delete tool[PARENT_KEY];
 			}

package/node_modules/@herbertgao/pi-cc-extensions/extensions/renderer/tool/result.ts

@@ -5,10 +5,8 @@ import { showMoreHintText } from "../show-more-hint.ts";
 import { TOOL_LOADING_INTERVAL_MS, toolLoadingIcon } from "../../utils/tool-loading-icon.ts";
 import { sanitizeToolResultText } from "../../utils/tool-result-sanitize.ts";
 
-const TOOL_VIEWPORT_WIDTH_RATIO = 0.8;
-
 export function toolViewportWidth(width: number): number {
-	return Math.max(1, Math.floor(width * TOOL_VIEWPORT_WIDTH_RATIO));
+	return Math.max(1, Math.floor(width));
 }
 
 /** 与默认工具结果相同的一级缩进包装。 */
@@ -23,7 +21,7 @@ export function insetComponent(component: any): any {
 	};
 }
 
-export function oneLine(value: unknown, max = 72): string {
+export function oneLine(value: unknown, max = 4096): string {
 	const text = sanitizeToolResultText(String(value ?? ""))
 		.replace(/\s+/g, " ")
 		.trim();

package/node_modules/@herbertgao/pi-cc-extensions/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@herbertgao/pi-cc-extensions",
-	"version": "0.8.53",
+	"version": "0.8.55",
 	"license": "MIT",
 	"description": "A Pi productivity suite with Claude Code-style UI, context inspection, and agent/session references",
 	"type": "module",
@@ -69,8 +69,8 @@
 	},
 	"x-upstream": {
 		"package": "pi-cc-extensions",
-		"version": "0.8.54",
+		"version": "0.8.60",
 		"repository": "https://github.com/minuque/pi-cc-extensions",
-		"commit": "8372ecaff7f079ab4452db47328c3238620a4885"
+		"commit": "268e017acde0b2adb65cefef3c740e37b1aef202"
 	}
 }

package/node_modules/@herbertgao/pi-subagents/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.5
+
+### Patch Changes
+
+- [#72](https://github.com/HerbertGao/pi-extensions/pull/72) [`5a133d4`](https://github.com/HerbertGao/pi-extensions/commit/5a133d4753532beef884b093638bceacf0545629) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Bypass Git signing for internal worktree preservation commits so interactive signers cannot time out and discard agent changes.
+
+- [#73](https://github.com/HerbertGao/pi-extensions/pull/73) [`553f466`](https://github.com/HerbertGao/pi-extensions/commit/553f4662b968cacaf969c1f4e588d29403c54bfc) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Use the primary text color across selected FleetView rows while preserving configured agent badges, and record the reviewed post-0.16.1 upstream range.
+
+- [#66](https://github.com/HerbertGao/pi-extensions/pull/66) [`af56b15`](https://github.com/HerbertGao/pi-extensions/commit/af56b159ce7081daf191d12da6afe3155e2b52b0) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Sync the applicable pi-subagents 0.16.1 compatibility fix and advance the reviewed upstream baseline to bb47763 while preserving the local fork behavior.
+
+## 0.15.4
+
+### Patch Changes
+
+- [#45](https://github.com/HerbertGao/pi-extensions/pull/45) [`97bad4e`](https://github.com/HerbertGao/pi-extensions/commit/97bad4e05f7398d9910786e8d614ffd4943cac8c) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Link persisted subagent sessions to their parent Pi session and advance the reviewed upstream baseline to 0.15.1.
+
+- [#52](https://github.com/HerbertGao/pi-extensions/pull/52) [`b12ab55`](https://github.com/HerbertGao/pi-extensions/commit/b12ab5597059ff2020e2108f8e8de85ce64e49c7) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Sync the applicable pi-subagents 0.16.0 fixes and advance the reviewed upstream baseline to bcbd602.
+
 ## 0.15.3
 
 ### Patch Changes

package/node_modules/@herbertgao/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.15.3",
+  "version": "0.15.5",
   "description": "Claude Code-style autonomous subagents for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -40,13 +40,17 @@
   "scripts": {
     "lint": "biome check src/ test/",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "croner": "^10.0.1",
     "nanoid": "^5.0.0"
   },
+  "devDependencies": {
+    "@vitest/coverage-istanbul": "^4.1.10"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.80.0",
     "@earendil-works/pi-coding-agent": ">=0.80.0",
@@ -64,8 +68,8 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.15.0",
+    "version": "0.16.1",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "c83dd82"
+    "commit": "bb47763"
   }
 }

package/node_modules/@herbertgao/pi-subagents/src/agent-color.ts

@@ -1,22 +1,25 @@
 /**
- * agent-color.ts — Claude Code-compatible agent name color rendering.
+ * agent-color.ts — Claude Code-compatible agent name badges.
  *
- * Claude Code defines eight named subagent colors. Agency Agents also uses
- * six-digit hex values and a small set of additional palette names, which are
- * accepted here so those definitions render without conversion.
+ * Claude Code renders a subagent's name as a badge: the configured color is the
+ * background, the text an inverse foreground. Its eight named colors are
+ * reproduced here, along with six-digit hex and the extra palette names Agency
+ * Agents uses, so those definitions render as written.
  */
 
 import { getConfig } from "./agent-types.js"
 
 const NAMED_AGENT_COLORS: Readonly<Record<string, string>> = {
-  red: "#E74C3C",
-  blue: "#3498DB",
-  green: "#2ECC71",
-  yellow: "#EAB308",
-  purple: "#9B59B6",
-  orange: "#F39C12",
-  pink: "#E84393",
-  cyan: "#00FFFF",
+  // Claude Code's eight subagent colors, as its default theme renders them.
+  red: "#DC2626",
+  blue: "#6A9BCC",
+  green: "#16A34A",
+  yellow: "#CA8A04",
+  purple: "#827DBD",
+  orange: "#D97757",
+  pink: "#C46686",
+  cyan: "#0891B2",
+  // Agency Agents palette aliases.
   amber: "#F59E0B",
   teal: "#008080",
   indigo: "#6366F1",
@@ -34,8 +37,10 @@ const NAMED_AGENT_COLORS: Readonly<Record<string, string>> = {
   navy: "#1E3A8A",
 }
 
-const CUBE_VALUES = [0, 95, 135, 175, 215, 255] as const
+const CUBE_VALUES = [0, 95, 135, 175, 215, 255]
 const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10)
+const BLACK = { r: 0, g: 0, b: 0 }
+const WHITE = { r: 255, g: 255, b: 255 }
 
 type Rgb = { r: number; g: number; b: number }
 type ColorMode = "truecolor" | "256color"
@@ -72,51 +77,48 @@ function parseHex(hex: string): Rgb {
   }
 }
 
-function nearestCubeIndex(value: number): number {
-  let best = 0
-  for (let i = 1; i < CUBE_VALUES.length; i++) {
-    if (Math.abs(value - CUBE_VALUES[i]) < Math.abs(value - CUBE_VALUES[best]))
-      best = i
-  }
-  return best
+/** Index of the entry in `values` closest to `value`. */
+function nearest(values: readonly number[], value: number): number {
+  return values.reduce(
+    (best, v, i) =>
+      Math.abs(value - v) < Math.abs(value - values[best]) ? i : best,
+    0,
+  )
 }
 
+/**
+ * Quantize to the xterm-256 palette the way pi's own theme does, returning both
+ * the index to emit and the color the terminal will actually show — badge
+ * contrast is judged against the latter.
+ */
 function rgbTo256({ r, g, b }: Rgb): { index: number; rgb: Rgb } {
-  const rIndex = nearestCubeIndex(r)
-  const gIndex = nearestCubeIndex(g)
-  const bIndex = nearestCubeIndex(b)
-  const cubeRgb = {
-    r: CUBE_VALUES[rIndex],
-    g: CUBE_VALUES[gIndex],
-    b: CUBE_VALUES[bIndex],
-  }
-  const distance = (candidate: Rgb) => {
-    const dr = r - candidate.r
-    const dg = g - candidate.g
-    const db = b - candidate.b
-    return dr * dr * 0.299 + dg * dg * 0.587 + db * db * 0.114
-  }
-
-  const gray = Math.round(0.299 * r + 0.587 * g + 0.114 * b)
-  let grayIndex = 0
-  for (let i = 1; i < GRAY_VALUES.length; i++) {
-    if (
-      Math.abs(gray - GRAY_VALUES[i]) < Math.abs(gray - GRAY_VALUES[grayIndex])
-    )
-      grayIndex = i
-  }
-  const grayRgb = {
+  const [rIndex, gIndex, bIndex] = [r, g, b].map((channel) =>
+    nearest(CUBE_VALUES, channel),
+  )
+  const distance = ({ r: cr, g: cg, b: cb }: Rgb) =>
+    0.299 * (r - cr) ** 2 + 0.587 * (g - cg) ** 2 + 0.114 * (b - cb) ** 2
+  const grayIndex = nearest(
+    GRAY_VALUES,
+    Math.round(0.299 * r + 0.587 * g + 0.114 * b),
+  )
+  const gray = {
     r: GRAY_VALUES[grayIndex],
     g: GRAY_VALUES[grayIndex],
     b: GRAY_VALUES[grayIndex],
   }
+  const cube = {
+    r: CUBE_VALUES[rIndex],
+    g: CUBE_VALUES[gIndex],
+    b: CUBE_VALUES[bIndex],
+  }
+  // Only near-neutral colors may take the gray ramp; anything else keeps its tint.
   if (
     Math.max(r, g, b) - Math.min(r, g, b) < 10 &&
-    distance(grayRgb) < distance(cubeRgb)
+    distance(gray) < distance(cube)
   ) {
-    return { index: 232 + grayIndex, rgb: grayRgb }
+    return { index: 232 + grayIndex, rgb: gray }
   }
-  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cubeRgb }
+  return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cube }
 }
 
 function ansiColor(
@@ -140,9 +142,10 @@ function relativeLuminance({ r, g, b }: Rgb): number {
 }
 
 /**
- * Render one name as a padded background badge when `color` is valid.
- * Black/white foreground is selected by WCAG contrast; invalid or omitted
- * colors preserve the caller's existing theme styling.
+ * Render one name as a padded background badge when `color` is valid. Claude
+ * Code uses one inverse color for every badge's text; black or white is picked
+ * by WCAG contrast here instead, so each palette entry stays readable. Invalid
+ * or omitted colors preserve the caller's existing theme styling.
  */
 export function renderAgentNameLabel(
   name: string,
@@ -156,32 +159,34 @@ export function renderAgentNameLabel(
     return style.fallbackColor ? theme.fg(style.fallbackColor, text) : text
   }
 
-  const backgroundRgb = parseHex(resolved)
-  const mode = theme.getColorMode?.() ?? "truecolor"
-  let background: Rgb | number = backgroundRgb
-  let effectiveBackground = backgroundRgb
-  if (mode === "256color") {
-    const quantized = rgbTo256(backgroundRgb)
-    background = quantized.index
-    effectiveBackground = quantized.rgb
-  }
-  const foregroundRgb =
-    relativeLuminance(effectiveBackground) > 0.179
-      ? { r: 0, g: 0, b: 0 }
-      : { r: 255, g: 255, b: 255 }
-  const foreground =
-    mode === "256color" ? rgbTo256(foregroundRgb).index : foregroundRgb
+  const rgb = parseHex(resolved)
+  const quantized =
+    (theme.getColorMode?.() ?? "truecolor") === "256color"
+      ? rgbTo256(rgb)
+      : undefined
+  const shown = quantized?.rgb ?? rgb
+  const contrasting = relativeLuminance(shown) > 0.179 ? BLACK : WHITE
   const label = style.bold ? theme.bold(` ${name} `) : ` ${name} `
 
   return (
-    ansiColor("background", background) +
-    ansiColor("foreground", foreground) +
+    ansiColor("background", quantized?.index ?? rgb) +
+    ansiColor(
+      "foreground",
+      quantized ? rgbTo256(contrasting).index : contrasting,
+    ) +
     label +
     "\u001b[39m" +
     (style.restoreBackground ?? "\u001b[49m")
   )
 }
 
+/** Whether an agent renders as a badge — i.e. it has a valid configured color. */
+export function hasAgentBadge(type: string | undefined): boolean {
+  return (
+    type !== undefined && resolveAgentColor(getConfig(type).color) !== undefined
+  )
+}
+
 /** Render a registered agent's display name with its configured color. */
 export function renderAgentName(
   type: string | undefined,

package/node_modules/@herbertgao/pi-subagents/src/agent-file-toggle.ts

@@ -0,0 +1,255 @@
+/**
+ * agent-file-toggle.ts — Pure helpers for the `/agents` file-editing operations:
+ * locating an agent's .md file, toggling its `enabled:` frontmatter flag, and
+ * serializing an AgentConfig back to frontmatter for eject.
+ *
+ * These live outside src/index.ts so they can be tested directly: the `/agents`
+ * command handler is an ~890-line closure reached only through `registerCommand`,
+ * which every test mocks.
+ *
+ * The read side of this data (src/custom-agents.ts) parses frontmatter with a
+ * real YAML parser, so it honors `enabled: false` at any position in the block.
+ * This module must agree with it, and splits the work accordingly:
+ *
+ * - Deciding whether a file is disabled is a *read*, so it calls that same parser
+ *   (`isDisabledContent`) instead of mirroring it. A mirror has to be right about
+ *   YAML's boolean spellings and about pi's fence scan, and a regex was wrong
+ *   about both.
+ * - *Editing* cannot go through the parser, because re-serializing a parsed
+ *   document would reformat a file the README tells users to hand-author —
+ *   discarding their comments, key order, and quoting. So the edits are line-wise
+ *   and preserve everything they don't touch.
+ *
+ * That leaves removal best-effort: it recognizes the parser's case-insensitive
+ * bare `false` spellings and trailing comments, and reports `changed: false`
+ * for values it cannot rewrite, so the caller refuses honestly rather than
+ * announcing a change it did not make.
+ */
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent"
+import type { AgentConfig } from "./types.js"
+
+export type AgentFileLocation = "project" | "workspace" | "personal"
+
+export const projectAgentsDir = (cwd: string = process.cwd()) =>
+  join(cwd, ".pi", "agents")
+export const workspaceAgentsDir = (cwd: string = process.cwd()) =>
+  join(cwd, ".agents", "agents")
+export const personalAgentsDir = () => join(getAgentDir(), "agents")
+
+/**
+ * Find the file path of a custom agent by name, in discovery-precedence order
+ * (project, workspace, then global). Mirrors the load-side precedence in
+ * src/custom-agents.ts — if the two drift, `/agents` edits a file the loader
+ * isn't reading.
+ */
+export function findAgentFile(
+  name: string,
+  cwd: string = process.cwd(),
+): { path: string; location: AgentFileLocation } | undefined {
+  const projectPath = join(projectAgentsDir(cwd), `${name}.md`)
+  if (existsSync(projectPath)) return { path: projectPath, location: "project" }
+  const workspacePath = join(workspaceAgentsDir(cwd), `${name}.md`)
+  if (existsSync(workspacePath))
+    return { path: workspacePath, location: "workspace" }
+  const personalPath = join(personalAgentsDir(), `${name}.md`)
+  if (existsSync(personalPath))
+    return { path: personalPath, location: "personal" }
+  return undefined
+}
+
+export type DisableOutcome = "disabled" | "already-disabled" | "no-frontmatter"
+
+/** A line that sets `enabled: false`, accepting YAML case and comments. */
+const ENABLED_FALSE = /^[ \t]*enabled:[ \t]*false[ \t]*(?:#[^\r\n]*)?$/i
+/** An opening or closing `---` fence line. */
+const FENCE = /^---[ \t]*$/
+
+/**
+ * Split a file into its frontmatter lines and everything else, agreeing with
+ * what `parseFrontmatter` (the load side) considers a frontmatter block.
+ *
+ * Lines keep their terminators, so an edit preserves the file's existing line
+ * endings instead of rewriting CRLF to LF. Returns undefined when there is no
+ * usable block — notably for a BOM-prefixed file, which the parser also reads
+ * as having none, so writing a key into it would change nothing on load.
+ */
+function splitFrontmatter(
+  content: string,
+):
+  | { lines: string[]; openIdx: number; closeIdx: number; eol: string }
+  | undefined {
+  const lines = content.split(/(?<=\n)/)
+  if (lines.length === 0 || !FENCE.test(lines[0].replace(/\r?\n$/, "")))
+    return undefined
+  const closeIdx = lines.findIndex(
+    (l, i) => i > 0 && FENCE.test(l.replace(/\r?\n$/, "")),
+  )
+  if (closeIdx === -1) return undefined
+  return {
+    lines,
+    openIdx: 0,
+    closeIdx,
+    eol: lines[0].endsWith("\r\n") ? "\r\n" : "\n",
+  }
+}
+
+/**
+ * Does the loader consider this file disabled?
+ *
+ * Detection is a READ operation, so it asks the same parser the loader uses
+ * rather than mirroring it with a regex — that mirror has to be right about
+ * YAML's boolean spellings (`False`, `FALSE`, a trailing `# comment`, a quoted
+ * key) *and* about pi's fence scan, which closes the block on any line starting
+ * `---` and so ends it early on `----`. A throw means the file is already
+ * unparseable, which is what the loader sees too: it skips the agent, so there
+ * is no "disabled" state to report.
+ */
+export function isDisabledContent(content: string): boolean {
+  try {
+    return (
+      parseFrontmatter<Record<string, unknown>>(content).frontmatter.enabled ===
+      false
+    )
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Add `enabled: false` to a file's frontmatter.
+ *
+ * `outcome` distinguishes a real edit from a no-op so the caller can report
+ * honestly instead of unconditionally claiming success.
+ */
+export function disableInContent(content: string): {
+  content: string
+  outcome: DisableOutcome
+} {
+  const block = splitFrontmatter(content)
+  if (!block) return { content, outcome: "no-frontmatter" }
+  if (isDisabledContent(content))
+    return { content, outcome: "already-disabled" }
+  const lines = [...block.lines]
+  lines.splice(1, 0, `enabled: false${block.eol}`)
+  return { content: lines.join(""), outcome: "disabled" }
+}
+
+/**
+ * Remove `enabled: false` from a file's frontmatter, wherever it appears in the
+ * block — the loader honors the key at any position, so the two must agree or a
+ * hand-authored agent can be disabled and never re-enabled.
+ *
+ * `changed` is false when the key wasn't found, so the caller can avoid
+ * reporting "Enabled <name>" for a write that did nothing.
+ */
+export function enableInContent(content: string): {
+  content: string
+  changed: boolean
+} {
+  const block = splitFrontmatter(content)
+  if (!block) return { content, changed: false }
+  const kept = block.lines.filter(
+    (l, i) =>
+      !(
+        i > 0 &&
+        i < block.closeIdx &&
+        ENABLED_FALSE.test(l.replace(/\r?\n$/, ""))
+      ),
+  )
+  if (kept.length === block.lines.length) return { content, changed: false }
+  return { content: kept.join(""), changed: true }
+}
+
+/** Is this the empty stub `/agents` writes when disabling a built-in default? */
+export function isEmptyStub(content: string): boolean {
+  return content.replace(/\r\n/g, "\n").trim() === "---\n---"
+}
+
+/** The answers `/agents → Create agent → Manual` collects, before serialization. */
+export interface NewAgentInput {
+  description: string
+  /** Already-resolved `tools:` value ("none", "all", or a CSV of tool names). */
+  tools: string
+  /** `provider/modelId`, or undefined to inherit the parent's model. */
+  model?: string
+  /** A pi thinking level, or undefined to inherit. */
+  thinking?: string
+  systemPrompt: string
+}
+
+/**
+ * Build the .md file the create wizard writes.
+ *
+ * `description` and `model` come straight from a free-text prompt, so they are
+ * quoted rather than interpolated — `serializeAgentFile` above quotes the
+ * description for the same reason. An unquoted YAML scalar mishandles ordinary
+ * input in two ways, and both are silent: a colon ("Scout: find things") makes
+ * the file unparseable, and since #212 an unparseable agent file is *skipped*,
+ * so the wizard reports success for an agent that does not exist; a `#`
+ * ("audit #security") opens a comment and truncates the value. `model` can
+ * carry a colon too — pi accepts a `provider/model:thinking` suffix.
+ *
+ * `tools` and `thinking` are not quoted: both are chosen from fixed menus, and
+ * `tools` is a CSV that must stay a bare scalar for the loader's parser.
+ */
+export function buildNewAgentFile(input: NewAgentInput): string {
+  const modelLine = input.model ? `\nmodel: ${JSON.stringify(input.model)}` : ""
+  const thinkingLine = input.thinking ? `\nthinking: ${input.thinking}` : ""
+  return `---
+description: ${JSON.stringify(input.description)}
+tools: ${input.tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${input.systemPrompt}
+`
+}
+
+/** Render a built-in tool list as a `tools:` frontmatter value. */
+function formatToolsField(tools: string[] | undefined): string {
+  if (tools === undefined) return "all"
+  if (tools.length === 0) return "none"
+  return tools.join(", ")
+}
+
+/** Serialize an AgentConfig to a full .md file (frontmatter + system prompt) for eject. */
+export function serializeAgentFile(cfg: AgentConfig): string {
+  const fmFields: string[] = []
+  fmFields.push(`description: ${JSON.stringify(cfg.description)}`)
+  if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`)
+  if (cfg.color) fmFields.push(`color: ${JSON.stringify(cfg.color)}`)
+  // Absent means "all built-ins"; an EMPTY list means explicitly zero. Writing
+  // `all` for both would hand a deliberately tool-less agent the whole toolbox
+  // the first time it is ejected.
+  fmFields.push(`tools: ${formatToolsField(cfg.builtinToolNames)}`)
+  if (cfg.model) fmFields.push(`model: ${cfg.model}`)
+  if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`)
+  if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`)
+  if (cfg.allowedSubagents !== undefined) {
+    fmFields.push(
+      `allowed_subagents: ${cfg.allowedSubagents === "all" ? "all" : cfg.allowedSubagents.join(", ")}`,
+    )
+  }
+  fmFields.push(`prompt_mode: ${cfg.promptMode}`)
+  if (cfg.extensions === false) fmFields.push("extensions: false")
+  else if (Array.isArray(cfg.extensions))
+    fmFields.push(`extensions: ${cfg.extensions.join(", ")}`)
+  if (cfg.excludeExtensions?.length)
+    fmFields.push(`exclude_extensions: ${cfg.excludeExtensions.join(", ")}`)
+  if (cfg.skills === false) fmFields.push("skills: false")
+  else if (Array.isArray(cfg.skills))
+    fmFields.push(`skills: ${cfg.skills.join(", ")}`)
+  if (cfg.disallowedTools?.length)
+    fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`)
+  if (cfg.inheritContext) fmFields.push("inherit_context: true")
+  if (cfg.runInBackground) fmFields.push("run_in_background: true")
+  if (cfg.outputTranscript === false) fmFields.push("output_transcript: false")
+  if (cfg.isolated) fmFields.push("isolated: true")
+  if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`)
+  if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`)
+
+  return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`
+}