@oh-my-pi/pi-coding-agent 16.4.2 → 16.4.3

package/scripts/bundle-dist.ts

@@ -3,17 +3,24 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent } from "@oh-my-pi/pi-utils";
-import { assertDocsIndexFresh, buildDocsIndexPayload } from "./generate-docs-index";
+import { buildDocsIndexPayload } from "./generate-docs-index";
 
 const packageDir = path.join(import.meta.dir, "..");
 const outDir = path.join(packageDir, "dist");
 const cliPath = path.join(outDir, "cli.js");
 const shebang = "#!/usr/bin/env bun\n";
 
-// Native / optional / platform-specific deps that are never bundled — installed on
-// demand (transformers/fastembed/onnxruntime) or shipped as their own artifact
-// (native addon, mupdf).
-const ALWAYS_EXTERNAL = ["mupdf", "@oh-my-pi/pi-natives", "@huggingface/transformers", "fastembed", "onnxruntime-node"];
+// Native / optional / platform-specific deps are loaded from installed files.
+// `omp-legacy-pi-modules` exists only in compiled binaries via the build plugin;
+// the npm bundle never executes that `isCompiledBinary()` branch.
+const ALWAYS_EXTERNAL = [
+	"mupdf",
+	"@oh-my-pi/pi-natives",
+	"@huggingface/transformers",
+	"fastembed",
+	"onnxruntime-node",
+	"omp-legacy-pi-modules",
+];
 
 // Heavy, lazily-used third-party leaf deps. Each is a declared `dependency`, so the
 // published package resolves it from node_modules at runtime; bundling only embeds a
@@ -73,48 +80,37 @@ async function cleanBundleOutputs(): Promise<void> {
 	);
 }
 
-async function assertDocsEmbedPopulated(): Promise<void> {
-	// bundle-dist runs from prepack (which calls `gen:docs` first) or directly.
-	// Direct invocations must fail — the tarball ships src/, and an empty embed
-	// would make src/internal-urls/docs-index.ts fall through to the missing
-	// repo `docs/` tree at runtime in published packages (codex review, PR #3941).
-	const embedPath = path.join(packageDir, "src/internal-urls/docs-index.generated.txt");
-	const embed = await Bun.file(embedPath).text();
-	if (embed.length === 0) {
-		throw new Error(
-			"docs-index embed is empty. Run `bun run gen:docs` before `bun run gen:bundle`, or use `bun pm pack` which runs the prepack chain.",
-		);
-	}
-	const expected = await buildDocsIndexPayload();
-	assertDocsIndexFresh(embed, expected);
-}
-
 async function main(): Promise<void> {
 	const start = Bun.nanoseconds();
 	await cleanBundleOutputs();
-	await assertDocsEmbedPopulated();
 	// The npm bundle ships no stats dashboard sources, so embed the dashboard
 	// archive the same way compiled binaries do (scripts/build-binary.ts). Reset
-	// afterwards to keep the checked-in placeholder empty. The docs embed stays
-	// populated on disk — postpack owns its reset so `bun pm pack` can pack a
-	// tarball whose src copy is still valid for subpath imports.
+	// afterwards to keep the checked-in placeholder empty.
 	await runCommand(["bun", "--cwd=../stats", "run", "gen:stats"]);
 	try {
-		await runCommand([
-			"bun",
-			"build",
-			"--target=bun",
-			"--outdir",
-			"dist",
-			// Full minify (whitespace + syntax + identifiers); --keep-names retains
-			// fn/class .name where code depends on it.
-			"--minify",
-			"--keep-names",
-			...[...ALWAYS_EXTERNAL, ...RUNTIME_EXTERNAL].flatMap(dep => ["--external", dep]),
-			"--define",
-			'process.env.PI_BUNDLED="true"',
-			"./src/cli.ts",
-		]);
+		// Build in-process: the docs embed payload is far larger than Linux's
+		// 128KiB per-argv-string cap, so it can never be passed as a CLI
+		// `--define` (posix_spawn fails with E2BIG).
+		const output = await Bun.build({
+			entrypoints: [path.join(packageDir, "src/cli.ts")],
+			outdir: outDir,
+			target: "bun",
+			external: [...ALWAYS_EXTERNAL, ...RUNTIME_EXTERNAL],
+			define: {
+				"process.env.PI_BUNDLED": JSON.stringify("true"),
+				"process.env.PI_DOCS_EMBED": JSON.stringify((await buildDocsIndexPayload()).payload),
+			},
+			minify: {
+				whitespace: true,
+				syntax: true,
+				identifiers: true,
+				keepNames: true,
+			},
+			throw: false,
+		});
+		if (!output.success) {
+			throw new Error(`CLI bundle failed:\n${output.logs.map(log => log.message).join("\n")}`);
+		}
 	} finally {
 		await runCommand(["bun", "--cwd=../stats", "run", "gen:stats:reset"]);
 	}

package/scripts/compile-binary.ts

@@ -0,0 +1,68 @@
+import { buildDocsIndexPayload } from "./generate-docs-index";
+import { createLegacyPiVirtualModulePlugin } from "./legacy-pi-virtual-module";
+
+/** Inputs shared by local and release coding-agent binary builds. */
+export interface CodingAgentCompileOptions {
+	/** Absolute repository root used for package resolution. */
+	readonly repoRoot: string;
+	/** Absolute CLI entrypoint. */
+	readonly entrypoint: string;
+	/** Absolute standalone executable output path. */
+	readonly outfile: string;
+	/** Concrete Transformers.js version baked into the tiny-model worker. */
+	readonly transformersVersion: string;
+	/** Optional cross-compilation runtime target. */
+	readonly target?: Bun.Build.CompileTarget;
+	/** Dependencies intentionally resolved from the runtime filesystem. */
+	readonly external?: readonly string[];
+	/** Match release builds that minify identifiers while retaining names. */
+	readonly minifyIdentifiers?: boolean;
+	/** Disable Bun's built-in Darwin signing before the caller re-signs. */
+	readonly skipBuiltinCodesign?: boolean;
+}
+
+/**
+ * Compile the coding-agent executable with its legacy Pi compatibility module
+ * graph supplied by an in-memory build plugin rather than generated files.
+ */
+export async function compileCodingAgent(options: CodingAgentCompileOptions): Promise<void> {
+	const previousCodesignSetting = Bun.env.BUN_NO_CODESIGN_MACHO_BINARY;
+	if (options.skipBuiltinCodesign) {
+		Bun.env.BUN_NO_CODESIGN_MACHO_BINARY = "1";
+	}
+	try {
+		const output = await Bun.build({
+			entrypoints: [options.entrypoint],
+			root: options.repoRoot,
+			external: options.external ? [...options.external] : undefined,
+			define: {
+				"process.env.PI_COMPILED": JSON.stringify("true"),
+				"process.env.PI_TINY_TRANSFORMERS_VERSION": JSON.stringify(options.transformersVersion),
+				"process.env.PI_DOCS_EMBED": JSON.stringify((await buildDocsIndexPayload()).payload),
+			},
+			minify: {
+				identifiers: options.minifyIdentifiers ?? false,
+				keepNames: true,
+			},
+			plugins: [await createLegacyPiVirtualModulePlugin()],
+			compile: {
+				...(options.target ? { target: options.target } : {}),
+				outfile: options.outfile,
+				autoloadBunfig: false,
+				autoloadDotenv: false,
+				autoloadTsconfig: false,
+				autoloadPackageJson: false,
+			},
+			throw: false,
+		});
+		if (!output.success) {
+			throw new Error(`Coding-agent binary bundle failed:\n${output.logs.map(log => log.message).join("\n")}`);
+		}
+	} finally {
+		if (previousCodesignSetting === undefined) {
+			delete Bun.env.BUN_NO_CODESIGN_MACHO_BINARY;
+		} else {
+			Bun.env.BUN_NO_CODESIGN_MACHO_BINARY = previousCodesignSetting;
+		}
+	}
+}

package/scripts/generate-docs-index.ts

@@ -1,38 +1,18 @@
-#!/usr/bin/env bun
-
-/**
- * Populate, check, or reset the embedded harness documentation index for `omp://`.
- *
- * `--generate` writes `src/internal-urls/docs-index.generated.txt` as two lines:
- * a plain JSON array of the sorted `docs/**\/*.md` file names, then a base64
- * gzip blob of the index-aligned doc bodies (`string[]`). `--check` rebuilds
- * that payload from the real docs corpus and compares it to the embed when
- * present; the checked-in empty placeholder is accepted after verifying that a
- * fresh generated payload round-trips. `--reset` restores the placeholder so the
- * dev tree reads `docs/` from disk. Mirrors the stats / model-catalog embeds.
- */
-
 import * as path from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { Glob } from "bun";
 
-const docsDir = path.resolve(import.meta.dir, "../../../docs");
-const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/docs-index.generated.txt");
-const GENERATE_FLAG = "--generate";
-const RESET_FLAG = "--reset";
-const CHECK_FLAG = "--check";
+const packageDir = path.resolve(import.meta.dir, "..");
+const docsDir = path.resolve(packageDir, "../../docs");
 
 export interface DocsIndexPayload {
-	/** Sorted `docs/**\/*.md` file names plus index-aligned bodies and embed text. */
 	readonly files: readonly string[];
 	readonly bodies: readonly string[];
 	readonly payload: string;
 }
 
 export interface DecodedDocsIndexPayload {
-	/** Sorted `docs/**\/*.md` file names decoded from an embed payload. */
 	readonly files: readonly string[];
-	/** Index-aligned Markdown bodies decoded from an embed payload. */
 	readonly bodies: readonly string[];
 }
 
@@ -40,7 +20,7 @@ function isStringArray(value: unknown): value is string[] {
 	return Array.isArray(value) && value.every(item => typeof item === "string");
 }
 
-/** Build the exact two-line `omp://` docs embed from the source `docs/**\/*.md` corpus. */
+/** Build the exact two-line `omp://` docs embed from the source `docs` Markdown corpus. */
 export async function buildDocsIndexPayload(): Promise<DocsIndexPayload> {
 	const glob = new Glob("**/*.md");
 	const files: string[] = [];
@@ -76,73 +56,3 @@ export function decodeDocsIndexPayload(embed: string): DecodedDocsIndexPayload |
 
 	return { files: filenames, bodies };
 }
-
-/**
- * Assert that an embed payload is fresh against the current source docs payload.
- * An empty placeholder is accepted by round-tripping the expected payload (the
- * dev tree and post-build reset state both checked-in placeholders).
- */
-export function assertDocsIndexFresh(embed: string, expected: DecodedDocsIndexPayload): void {
-	const source =
-		embed.length > 0
-			? embed
-			: `${JSON.stringify(expected.files)}\n${Buffer.from(gzipSync(Buffer.from(JSON.stringify(expected.bodies)), { level: 9 })).toString("base64")}`;
-	const decoded = decodeDocsIndexPayload(source);
-	if (decoded === null) {
-		throw new Error("Embedded docs index is malformed: missing newline separator.");
-	}
-	if (decoded.files.length !== expected.files.length) {
-		throw new Error(
-			`Embedded docs index has ${decoded.files.length} docs; source corpus has ${expected.files.length}.`,
-		);
-	}
-	if (decoded.bodies.length !== expected.bodies.length) {
-		throw new Error(
-			`Embedded docs index has ${decoded.bodies.length} bodies; source corpus has ${expected.bodies.length}.`,
-		);
-	}
-	for (let i = 0; i < expected.files.length; i++) {
-		if (decoded.files[i] !== expected.files[i]) {
-			throw new Error(
-				`Embedded docs index filename mismatch at ${i}: ${decoded.files[i] ?? "<missing>"} !== ${expected.files[i]}.`,
-			);
-		}
-		if (decoded.bodies[i] !== expected.bodies[i]) {
-			throw new Error(`Embedded docs index body mismatch for ${expected.files[i]}. Run \`bun run gen:docs\`.`);
-		}
-	}
-}
-
-async function main(): Promise<void> {
-	const rel = path.relative(process.cwd(), outputPath);
-
-	if (process.argv.includes(RESET_FLAG)) {
-		await Bun.write(outputPath, "");
-		process.stdout.write(`Reset ${rel}\n`);
-		return;
-	}
-
-	if (process.argv.includes(CHECK_FLAG)) {
-		const current = await buildDocsIndexPayload();
-		const embed = await Bun.file(outputPath).text();
-		assertDocsIndexFresh(embed, current);
-		process.stdout.write(`Docs index fresh for ${current.files.length} docs (${rel})\n`);
-		return;
-	}
-
-	if (!process.argv.includes(GENERATE_FLAG)) {
-		process.stdout.write(
-			`Skipping ${rel}; pass ${GENERATE_FLAG} to embed docs (the dev tree reads docs/ from disk)\n`,
-		);
-		return;
-	}
-
-	const current = await buildDocsIndexPayload();
-	assertDocsIndexFresh(current.payload, current);
-	await Bun.write(outputPath, current.payload);
-	process.stdout.write(`Generated ${rel} (${current.files.length} docs, ${current.payload.length} bytes)\n`);
-}
-
-if (import.meta.main) {
-	await main();
-}

package/scripts/legacy-pi-virtual-module.ts

@@ -0,0 +1,192 @@
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils/fs-error";
+
+/** Build-time specifier resolved to bundled legacy Pi module namespaces. */
+export const LEGACY_PI_MODULES_SPECIFIER = "omp-legacy-pi-modules";
+
+const VIRTUAL_NAMESPACE = "omp-legacy-pi-modules-build";
+const packageDir = path.resolve(import.meta.dir, "..");
+const repoRoot = path.resolve(packageDir, "..", "..");
+
+interface BundledPackage {
+	readonly dir: string;
+	readonly identifier: string;
+	readonly rootShim: string | null;
+}
+
+const BUNDLED_PACKAGES: readonly BundledPackage[] = [
+	{ dir: "agent", identifier: "PiAgentCore", rootShim: null },
+	{ dir: "ai", identifier: "PiAi", rootShim: "legacy-pi-ai-shim.ts" },
+	{ dir: "coding-agent", identifier: "PiCodingAgent", rootShim: "legacy-pi-coding-agent-shim.ts" },
+	{ dir: "natives", identifier: "PiNatives", rootShim: null },
+	{ dir: "tui", identifier: "PiTui", rootShim: null },
+	{ dir: "utils", identifier: "PiUtils", rootShim: null },
+];
+
+const TYPEBOX_MODULE_KEY = "typebox";
+const TYPEBOX_SHIM = "typebox.ts";
+const SKIPPED_WILDCARD_BASENAMES = new Set(["index"]);
+const MAIN_THREAD_UNSAFE_WILDCARD_BASENAMES = new Set(["worker-entry"]);
+
+/** One namespace module the binary must retain for legacy extension imports. */
+export interface BundledPiEntry {
+	/** Canonical import key exposed to extensions. */
+	readonly key: string;
+	/** Unique identifier used by the virtual module's generated import. */
+	readonly binding: string;
+	/** Package or absolute source specifier compiled into the binary. */
+	readonly importSpecifier: string;
+}
+
+interface WildcardPattern {
+	readonly exportPrefix: string;
+	readonly exportSuffix: string;
+	readonly sourcePrefix: string;
+	readonly sourceSuffix: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function bindingForSubpath(identifier: string, subpath: string): string {
+	const segments = subpath
+		.split("/")
+		.filter(Boolean)
+		.map(segment =>
+			segment
+				.split(/[-_]/)
+				.filter(Boolean)
+				.map(part => part.charAt(0).toUpperCase() + part.slice(1))
+				.join(""),
+		);
+	return `bundled${identifier}${segments.join("")}`;
+}
+
+function isSafeWildcardBasename(basename: string): boolean {
+	if (!basename || basename.startsWith(".") || basename.startsWith("_")) return false;
+	if (SKIPPED_WILDCARD_BASENAMES.has(basename)) return false;
+	if (MAIN_THREAD_UNSAFE_WILDCARD_BASENAMES.has(basename)) return false;
+	return !/\.(test|spec|d|generated|bench)$/.test(basename);
+}
+
+function parseWildcardPattern(exportKey: string, sourcePattern: string): WildcardPattern | null {
+	const exportStar = exportKey.indexOf("*");
+	const sourceStar = sourcePattern.indexOf("*");
+	if (exportStar === -1 || sourceStar === -1) return null;
+	if (exportKey.indexOf("*", exportStar + 1) !== -1) return null;
+	if (sourcePattern.indexOf("*", sourceStar + 1) !== -1) return null;
+	if (!sourcePattern.startsWith("./")) return null;
+	return {
+		exportPrefix: exportKey.slice(2, exportStar),
+		exportSuffix: exportKey.slice(exportStar + 1),
+		sourcePrefix: sourcePattern.slice(2, sourceStar),
+		sourceSuffix: sourcePattern.slice(sourceStar + 1),
+	};
+}
+
+function exportImportTarget(value: unknown): string | null {
+	if (typeof value === "string") return value;
+	if (isRecord(value) && typeof value.import === "string") return value.import;
+	return null;
+}
+
+function shimSpecifier(file: string): string {
+	return path.join(packageDir, "src", "extensibility", file);
+}
+
+/**
+ * Derive the bundled legacy Pi module surface from current package exports.
+ * Named wildcard exports are expanded from source; root catch-alls stay out to
+ * avoid importing CLI entrypoints and other non-extension surfaces.
+ */
+export async function collectBundledPiEntries(): Promise<BundledPiEntry[]> {
+	const entries: BundledPiEntry[] = [];
+	const seenKeys = new Set<string>();
+	const seenBindings = new Set<string>();
+	function addEntry(key: string, binding: string, importSpecifier: string): void {
+		if (seenKeys.has(key)) return;
+		if (seenBindings.has(binding)) {
+			throw new Error(`Duplicate bundled Pi binding ${binding} for ${key}`);
+		}
+		seenKeys.add(key);
+		seenBindings.add(binding);
+		entries.push({ key, binding, importSpecifier });
+	}
+
+	for (const pkg of BUNDLED_PACKAGES) {
+		const packageRoot = path.join(repoRoot, "packages", pkg.dir);
+		const manifestPath = path.join(packageRoot, "package.json");
+		const manifest: unknown = await Bun.file(manifestPath).json();
+		if (!isRecord(manifest) || typeof manifest.name !== "string") {
+			throw new Error(`Bundled Pi package manifest has no name: ${manifestPath}`);
+		}
+		const exportsField = isRecord(manifest.exports) ? manifest.exports : {};
+		const rootSpecifier = pkg.rootShim ? shimSpecifier(pkg.rootShim) : manifest.name;
+		addEntry(manifest.name, `bundled${pkg.identifier}`, rootSpecifier);
+
+		for (const exportKey in exportsField) {
+			if (!exportKey.startsWith("./") || exportKey === "." || exportKey.includes("*")) continue;
+			const subpath = exportKey.slice(2);
+			const key = `${manifest.name}/${subpath}`;
+			addEntry(key, bindingForSubpath(pkg.identifier, subpath), key);
+		}
+
+		for (const exportKey in exportsField) {
+			if (!exportKey.startsWith("./") || exportKey === "." || !exportKey.includes("*")) continue;
+			const sourcePattern = exportImportTarget(exportsField[exportKey]);
+			if (!sourcePattern) continue;
+			const pattern = parseWildcardPattern(exportKey, sourcePattern);
+			if (!pattern || !/\.(ts|tsx|mts|cts|js|mjs|cjs|jsx)$/.test(pattern.sourceSuffix)) continue;
+			if (pattern.exportPrefix === "" || pattern.exportPrefix === "/") continue;
+
+			const sourceDir = path.join(packageRoot, pattern.sourcePrefix);
+			try {
+				const glob = new Bun.Glob(`*${pattern.sourceSuffix}`);
+				const matches: string[] = [];
+				for await (const match of glob.scan({ cwd: sourceDir, onlyFiles: true })) {
+					matches.push(match);
+				}
+				matches.sort();
+				for (const match of matches) {
+					if (!match.endsWith(pattern.sourceSuffix)) continue;
+					const basename = match.slice(0, match.length - pattern.sourceSuffix.length);
+					if (!isSafeWildcardBasename(basename) || basename.includes("/")) continue;
+					const subpath = `${pattern.exportPrefix}${basename}${pattern.exportSuffix}`;
+					const key = `${manifest.name}/${subpath}`;
+					addEntry(key, bindingForSubpath(pkg.identifier, subpath), key);
+				}
+			} catch (error) {
+				if (!isEnoent(error)) throw error;
+			}
+		}
+	}
+
+	addEntry(TYPEBOX_MODULE_KEY, "bundledTypeBoxShim", shimSpecifier(TYPEBOX_SHIM));
+	return entries;
+}
+
+function renderVirtualModule(entries: readonly BundledPiEntry[]): string {
+	const imports = entries.map(entry => `import * as ${entry.binding} from ${JSON.stringify(entry.importSpecifier)};`);
+	const modules = entries.map(entry => `\t${JSON.stringify(entry.key)}: ${entry.binding},`);
+	return [...imports, "", "export const BUNDLED_PI_MODULES = {", ...modules, "};", ""].join("\n");
+}
+
+/**
+ * Build plugin that materializes the legacy Pi module graph entirely in
+ * memory. Bun still needs static import edges at compile time, but no generated
+ * source or key-list file is written to the repository.
+ */
+export async function createLegacyPiVirtualModulePlugin(): Promise<Bun.BunPlugin> {
+	const source = renderVirtualModule(await collectBundledPiEntries());
+	return {
+		name: "omp:legacy-pi-modules",
+		setup(build) {
+			build.onResolve({ filter: /^omp-legacy-pi-modules$/ }, () => ({
+				path: LEGACY_PI_MODULES_SPECIFIER,
+				namespace: VIRTUAL_NAMESPACE,
+			}));
+			build.onLoad({ filter: /.*/, namespace: VIRTUAL_NAMESPACE }, () => ({ contents: source, loader: "ts" }));
+		},
+	};
+}

package/src/advisor/__tests__/advisor.test.ts

@@ -1827,6 +1827,19 @@ describe("advisor", () => {
 			expect(text).toContain("read, grep, glob (default)");
 		});
 
+		it("renders an explicit no-tools advisor distinctly from the omitted default", async () => {
+			const uiTheme = await getThemeByName("dark");
+			if (!uiTheme) throw new Error("theme unavailable");
+			setThemeInstance(uiTheme);
+			const overlay = make({
+				advisors: [{ name: "Blank", tools: [] }],
+			});
+
+			const text = strip(overlay.render(200));
+			expect(text.toLowerCase()).toContain("no tools");
+			expect(text).not.toContain("read, grep, glob (default)");
+		});
+
 		it("moves the preview with keyboard selection and preserves an explicit tool set", async () => {
 			const uiTheme = await getThemeByName("dark");
 			if (!uiTheme) throw new Error("theme unavailable");

package/src/advisor/__tests__/config.test.ts

@@ -56,6 +56,27 @@ describe("discoverAdvisorConfigs", () => {
 		expect(sharedInstructions).toBe("Shared baseline for all advisors.");
 	});
 
+	it("distinguishes omitted tools, explicit no-tools, and invalid-only lists", async () => {
+		const yaml = [
+			"advisors:",
+			"  - name: No Tools",
+			"    tools: []",
+			"  - name: Default Tools",
+			"  - name: Invalid Only",
+			"    tools: [reed]",
+		].join("\n");
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), yaml);
+
+		const { advisors } = await discoverAdvisorConfigs(tmp, agentDir);
+		const noTools = advisors.find(a => a.name === "No Tools");
+		const defaultTools = advisors.find(a => a.name === "Default Tools");
+		const invalidOnly = advisors.find(a => a.name === "Invalid Only");
+
+		expect(noTools?.tools).toEqual([]);
+		expect(defaultTools?.tools).toBeUndefined();
+		expect(invalidOnly?.tools).toBeUndefined();
+	});
+
 	it("ignores a malformed YAML file without throwing", async () => {
 		await Bun.write(path.join(tmp, "WATCHDOG.yml"), "advisors: [unclosed bracket");
 		const result = await discoverAdvisorConfigs(tmp, agentDir);
@@ -206,6 +227,21 @@ describe("WATCHDOG.yml file round-trip", () => {
 		expect(sharedInstructions).toContain("Shared baseline.");
 	});
 
+	it("round-trips an explicit empty tools list without collapsing it into the default", async () => {
+		const file = path.join(tmp, "WATCHDOG.yml");
+		const explicitNoToolsDoc: WatchdogConfigDoc = {
+			advisors: [{ name: "No Tools", tools: [] }, { name: "Default Tools" }],
+		};
+
+		await saveWatchdogConfigFile(file, explicitNoToolsDoc);
+		const serializedDoc = await loadWatchdogConfigFile(file);
+		expect(serializedDoc).toEqual(explicitNoToolsDoc);
+
+		const { advisors } = await discoverAdvisorConfigs(tmp, tmp);
+		expect(advisors.find(a => a.name === "No Tools")?.tools).toEqual([]);
+		expect(advisors.find(a => a.name === "Default Tools")?.tools).toBeUndefined();
+	});
+
 	it("removes the file when the doc is empty so legacy discovery resumes", async () => {
 		const file = path.join(tmp, "WATCHDOG.yml");
 		await saveWatchdogConfigFile(file, doc);

package/src/advisor/config.ts

@@ -12,9 +12,10 @@ import { collectConfigCandidates } from "./watchdog";
  * with an optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`),
  * resolved exactly like any other model override; `tools` is a subset of
  * `BUILTIN_TOOL_NAMES` — any built-in name, including mutating tools such as
- * `edit`/`write`/`bash` (the advisor is a full agent). Omitted or empty falls
- * back to the default `read`/`grep`/`glob` subset. `instructions` is the
- * advisor's specialization, appended to the shared baseline.
+ * `edit`/`write`/`bash` (the advisor is a full agent). Omitted falls back to
+ * the default `read`/`grep`/`glob` subset; an explicit empty list grants no
+ * tools. `instructions` is the advisor's specialization, appended to the shared
+ * baseline.
  */
 export interface AdvisorConfig {
 	name: string;
@@ -93,11 +94,13 @@ const KNOWN_TOOL_NAMES = new Set<string>(BUILTIN_TOOL_NAMES);
 /**
  * Keep only valid tool names from an advisor's `tools` list, dropping unknowns
  * with a warning. The advisor is a full agent, so any built tool may be granted;
- * the runtime further filters to what's actually available this session. An empty
- * result (or no list) means "use the default subset" (read/grep/glob).
+ * the runtime further filters to what's actually available this session.
+ * `undefined` means "use the default subset" (read/grep/glob); only an explicit
+ * raw empty list means "no tools".
  */
 function filterAdvisorTools(tools: string[] | undefined, sourcePath: string): string[] | undefined {
-	if (!tools || tools.length === 0) return undefined;
+	if (tools === undefined) return undefined;
+	if (tools.length === 0) return [];
 	// Normalize legacy aliases (search→grep, find→glob) and dedupe before validating.
 	const filtered = normalizeToolNames(tools).filter(name => {
 		if (KNOWN_TOOL_NAMES.has(name)) return true;
@@ -238,7 +241,7 @@ export async function loadWatchdogConfigFile(filePath: string): Promise<Watchdog
 		advisors: (result.advisors ?? []).map(a => ({
 			name: a.name,
 			model: a.model?.trim() || undefined,
-			tools: a.tools?.length ? [...a.tools] : undefined,
+			tools: a.tools === undefined ? undefined : [...a.tools],
 			instructions: a.instructions?.trim() ? a.instructions : undefined,
 		})),
 	};
@@ -257,7 +260,7 @@ export function serializeWatchdogConfig(doc: WatchdogConfigDoc): string {
 		out.advisors = doc.advisors.map(a => {
 			const entry: AdvisorConfig = { name: a.name };
 			if (a.model?.trim()) entry.model = a.model;
-			if (a.tools?.length) entry.tools = [...a.tools];
+			if (a.tools !== undefined) entry.tools = [...a.tools];
 			if (a.instructions?.trim()) entry.instructions = a.instructions;
 			return entry;
 		});

package/src/commit/agentic/agent.ts

@@ -29,6 +29,7 @@ export interface CommitAgentInput {
 	requireChangelog: boolean;
 	diffText?: string;
 	existingChangelogEntries?: ExistingChangelogEntries[];
+	onComplete?: (state: CommitAgentState) => Promise<void> | void;
 }
 
 export interface ExistingChangelogEntries {
@@ -175,6 +176,9 @@ export async function runCommitAgentSession(input: CommitAgentInput): Promise<Co
 			});
 		}
 
+		if (input.onComplete) {
+			await input.onComplete(state);
+		}
 		return state;
 	} finally {
 		unsubscribe();