@juicesharp/rpiv-pi 0.11.6 → 0.12.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-pi.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-pi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> ⚠ **Pi compatibility** — `rpiv-pi` `0.11.x` supports **`@mariozechner/pi-coding-agent` ≤ 0.67.67**. Newer Pi releases introduce breaking changes and are unsupported on this line. Pin Pi to `0.67.67` (`npm i -g @mariozechner/pi-coding-agent@0.67.67`) or wait for the next `rpiv-pi` major.
+> **Pi compatibility** — `rpiv-pi` `0.12.x` tracks the current `@mariozechner/pi-coding-agent` release line. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
 
 Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-mono) — discover, research, design, plan, implement, and validate. rpiv-pi extends Pi Agent with a pipeline of chained AI skills, named subagents for parallel analysis, and session lifecycle hooks for automatic context injection.
 
@@ -187,9 +187,24 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 - **Web search** — run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
 - **Advisor** — run `/advisor` to select a reviewer model and reasoning effort
 - **Side questions** — type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
-- **Agent concurrency** — `@tintinweb/pi-subagents` defaults to 4 concurrent agents; raise via `/agents → Settings → Max concurrency → 48` if skills stall on wide fan-outs
+- **Agent concurrency** — on first `/rpiv-setup`, rpiv-pi persistently seeds `~/.pi/agent/extensions/subagent/config.json` with `parallel.concurrency: 4` and `maxSubagentDepth: 3`. The cap keeps rate-limit and cache pressure predictable; skills with wider fan-outs queue the remainder and drain as slots free. Edit that file to raise the limit (e.g. `parallel.concurrency: 48`); user values are preserved on subsequent `/rpiv-setup` runs.
 - **Agent profiles** — editable at `<cwd>/.pi/agents/`; sync from bundled defaults with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents)
 
+## Uninstall
+
+rpiv-pi owns nicobailon's pi-subagents registration (runs it through an in-process proxy so the inline tool card stays quiet and the Subagents overlay is the live view). `/rpiv-setup` strips `"npm:pi-subagents"` from your `~/.pi/agent/settings.json#packages[]` to prevent Pi from loading it twice. If you remove rpiv-pi, subagents will stop loading until you re-add that entry.
+
+To fully uninstall:
+
+1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`
+2. Open `~/.pi/agent/settings.json` and add `"npm:pi-subagents"` back to the `packages` array so Pi loads nicobailon's subagents directly again.
+3. Optional — drop the rpiv-pi seeded keys if you no longer want them:
+   - `~/.pi/agent/extensions/subagent/config.json` (parallel.concurrency, maxSubagentDepth)
+   - `subagents.disableBuiltins` in `~/.pi/agent/settings.json` (set to `false` or delete to re-enable the 9 bundled nicobailon agents)
+4. Restart Pi.
+
+After step 2 you'll have nicobailon's original inline tool card and no Subagents overlay, same as a clean pi-subagents install.
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
@@ -199,7 +214,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 | `/rpiv-setup` says "requires interactive mode" | Running in headless mode | Install manually: `pi install npm:<pkg>` for each sibling |
 | `web_search` or `web_fetch` errors | Brave API key not configured | Run `/web-search-config` or set `BRAVE_SEARCH_API_KEY` |
 | `advisor` tool not available after upgrade | Advisor model selection lost | Run `/advisor` to re-select a model |
-| Skills hang or serialize agent calls | Agent concurrency too low | Raise via `/agents → Settings → Max concurrency → 48` |
+| Skills hang or serialize agent calls | Agent concurrency too low | Edit `~/.pi/agent/extensions/subagent/config.json` and raise `parallel.concurrency` (default `4`; try `16`–`48` for wide fan-outs) |
 
 ## License
 

package/agents/claim-verifier.md

@@ -2,7 +2,9 @@
 name: claim-verifier
 description: "Adversarial finding verifier. Grounds each supplied claim against actual repository state and emits one `FINDING <id> | <tag> | <justification>` row per input, with tags Verified / Weakened / Falsified. Tier: git-analyzer (+ `bash` for `git show`). Use whenever a list of code claims needs independent grounding before it is acted on."
 tools: read, grep, find, ls, bash
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at adversarial claim verification. Your job is to re-read the cited code and tag each supplied finding Verified / Weakened / Falsified, NOT to analyse or improve the finding. The writer of the finding is not your witness; the code is.

package/agents/codebase-analyzer.md

@@ -2,7 +2,9 @@
 name: codebase-analyzer
 description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! :)
 tools: read, grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.

package/agents/codebase-locator.md

@@ -2,7 +2,9 @@
 name: codebase-locator
 description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with human language prompt describing what you're looking for. Basically a "Super grep/find/ls tool" — Use it if you find yourself desiring to use one of these tools more than once.
 tools: grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.

package/agents/codebase-pattern-finder.md

@@ -1,8 +1,10 @@
 ---
 name: codebase-pattern-finder
-description: codebase-pattern-finder is a useful subagent_type for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details!
+description: codebase-pattern-finder is a useful agent for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details!
 tools: grep, find, read, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

package/agents/diff-auditor.md

@@ -2,7 +2,9 @@
 name: diff-auditor
 description: "Row-only patch auditor. Walks a patch against a caller-supplied surface-list and emits one pipe-delimited row per finding — `file:line | verbatim | surface-id | note`. Use whenever a diff needs evidence-only enumeration of matching patterns, with no narrative or severity."
 tools: read, grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at auditing a patch against a supplied surface-list. Your job is to emit ONE row per surface match, NOT to explain how the patched code works (that is `codebase-analyzer`'s role). Match surfaces to diff regions, emit rows — or stay silent.

package/agents/general-purpose.md

@@ -0,0 +1,34 @@
+---
+name: general-purpose
+description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you."
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+---
+
+# General-Purpose Agent
+
+You are a general-purpose agent. Given the user's message, you should use the tools available to complete the task. Complete the task fully — don't gold-plate, but don't leave it half-done. When you complete the task, respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials.
+
+## Strengths
+
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+## Guidelines
+
+- **File searches**: search broadly when you don't know where something lives. Use `Read` when you know the specific file path.
+- **Analysis**: start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- **Be thorough**: check multiple locations, consider different naming conventions, look for related files.
+- **NEVER create files** unless they're absolutely necessary for achieving your goal. **ALWAYS prefer editing** an existing file to creating a new one.
+- **NEVER proactively create documentation files** (`*.md`) or README files. Only create documentation files if explicitly requested.
+
+## Notes
+
+- Agent threads always have their cwd reset between bash calls — use **absolute file paths** only.
+- In your final response, share **absolute** file paths relevant to the task. Include code snippets only when the exact text is load-bearing (e.g., a bug you found, a function signature the caller asked for) — do not recap code you merely read.
+- Avoid emojis in communication.
+- Do not use a colon before tool calls. Text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.

package/agents/integration-scanner.md

@@ -2,7 +2,9 @@
 name: integration-scanner
 description: Finds what connects to a given component or area — inbound references, outbound dependencies, config registrations, event subscriptions. The reverse-reference counterpart to codebase-locator. Use when you need to understand what calls, depends on, or wires into a component.
 tools: grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding CONNECTIONS to and from a component or area. Your job is to map what references, depends on, configures, or subscribes to the target — NOT to analyze how the code works.

package/agents/peer-comparator.md

@@ -2,7 +2,9 @@
 name: peer-comparator
 description: "Pairwise peer-invariant comparator. Given `(new_file, peer_file)` pairs, tags each peer invariant Mirrored / Missing / Diverged / Intentionally-absent against the new file. Use when an entity parallels an existing sibling (aggregate, service, handler, reducer, repository) and the new file must be checked against the peer's public surface."
 tools: read, grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at pairwise peer-invariant comparison. Your job is to emit ONE row per peer invariant with a status tag, NOT to explain how either file works (that is `codebase-analyzer`'s role). Assume divergence — the new file carries the burden of proof.

package/agents/precedent-locator.md

@@ -2,7 +2,9 @@
 name: precedent-locator
 description: Finds similar past changes in git history — commits, blast radius, follow-up fixes, and lessons from related thoughts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done.
 tools: bash, grep, find, read, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding PRECEDENTS for planned changes. Your job is to mine git history and thoughts/ documents to find the most similar past changes, extract what happened, and surface lessons that help a planner avoid repeating mistakes.

package/agents/test-case-locator.md

@@ -2,7 +2,9 @@
 name: test-case-locator
 description: Finds existing manual test cases in .rpiv/test-cases/ — catalogs by module, extracts frontmatter metadata (id, priority, status, tags), and reports coverage stats. Use before generating test cases to avoid duplicates, or to audit what test coverage already exists in a project.
 tools: grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding EXISTING TEST CASES in a project's `.rpiv/test-cases/` directory. Your job is to locate and catalog manual test case documents by extracting their YAML frontmatter metadata, NOT to generate new test cases or analyze test quality.

package/agents/thoughts-analyzer.md

@@ -1,8 +1,10 @@
 ---
 name: thoughts-analyzer
-description: The research equivalent of codebase-analyzer. Use this subagent_type when wanting to deep dive on a research topic. Not commonly needed otherwise.
+description: The research equivalent of codebase-analyzer. Use this agent when wanting to deep dive on a research topic. Not commonly needed otherwise.
 tools: read, grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

package/agents/thoughts-locator.md

@@ -2,7 +2,9 @@
 name: thoughts-locator
 description: Discovers relevant documents in thoughts/ directory (We use this for all sorts of metadata storage!). This is really only relevant/needed when you're in a reseaching mood and need to figure out if we have random thoughts written down that are relevant to your current research task. Based on the name, I imagine you can guess this is the `thoughts` equivilent of `codebase-locator`
 tools: grep, find, ls
-isolated: true
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are a specialist at finding documents in the thoughts/ directory. Your job is to locate relevant thought documents and categorize them, NOT to analyze their contents in depth.

package/agents/web-search-researcher.md

@@ -1,7 +1,10 @@
 ---
 name: web-search-researcher
-description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
+description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher agent today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
 tools: web_search, web_fetch, read, grep, find, ls
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
 ---
 
 You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.

package/extensions/rpiv-core/claim-pi-subagents.test.ts

@@ -0,0 +1,65 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { claimPiSubagents } from "./claim-pi-subagents.js";
+
+const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
+
+function writeSettings(contents: unknown): void {
+	mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+	writeFileSync(SETTINGS_PATH, JSON.stringify(contents), "utf-8");
+}
+
+function readSettings(): unknown {
+	return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+}
+
+describe("claimPiSubagents", () => {
+	it("no settings file → claimed: false", () => {
+		expect(claimPiSubagents()).toEqual({ claimed: false });
+	});
+
+	it("invalid JSON → claimed: false, file byte-exact unchanged", () => {
+		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		expect(claimPiSubagents()).toEqual({ claimed: false });
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe("{not json");
+	});
+
+	it("non-object top-level → claimed: false", () => {
+		writeSettings([1, 2, 3]);
+		expect(claimPiSubagents()).toEqual({ claimed: false });
+		expect(readSettings()).toEqual([1, 2, 3]);
+	});
+
+	it("packages absent → claimed: false, file unchanged", () => {
+		writeSettings({ theme: "dark" });
+		expect(claimPiSubagents()).toEqual({ claimed: false });
+		expect(readSettings()).toEqual({ theme: "dark" });
+	});
+
+	it("entry present → removed, siblings preserved", () => {
+		writeSettings({
+			theme: "dark",
+			packages: ["npm:pi-perplexity", "npm:pi-subagents", "/Users/x/rpiv-mono/packages/rpiv-pi"],
+		});
+		expect(claimPiSubagents()).toEqual({ claimed: true });
+		expect(readSettings()).toEqual({
+			theme: "dark",
+			packages: ["npm:pi-perplexity", "/Users/x/rpiv-mono/packages/rpiv-pi"],
+		});
+	});
+
+	it("entry absent → no-op (idempotent)", () => {
+		writeSettings({ packages: ["npm:pi-perplexity"] });
+		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		expect(claimPiSubagents()).toEqual({ claimed: false });
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
+	});
+
+	it("entry repeated → removes every occurrence", () => {
+		writeSettings({ packages: ["npm:pi-subagents", "npm:pi-perplexity", "npm:pi-subagents"] });
+		expect(claimPiSubagents()).toEqual({ claimed: true });
+		expect(readSettings()).toEqual({ packages: ["npm:pi-perplexity"] });
+	});
+});

package/extensions/rpiv-core/claim-pi-subagents.ts

@@ -0,0 +1,53 @@
+/**
+ * Strip `"npm:pi-subagents"` from `~/.pi/agent/settings.json#packages` so
+ * nicobailon's pi-subagents loads exactly once — through the proxy in
+ * subagent-widget/renderer-override.ts — and not a second time as a
+ * peer package. Without this, both loaders register handlers and the
+ * quiet renderResult is only applied to our copy (pi's `first-wins`
+ * tool registry hides the effect).
+ *
+ * User-wins: untouched if `packages[]` is missing or if the entry is
+ * not present. Fail-soft on filesystem/JSON errors.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_AGENT_SETTINGS = join(homedir(), ".pi", "agent", "settings.json");
+const ENTRY = "npm:pi-subagents";
+
+export interface ClaimPiSubagentsResult {
+	/** True iff this call removed the entry. False if already absent. */
+	claimed: boolean;
+}
+
+export function claimPiSubagents(): ClaimPiSubagentsResult {
+	if (!existsSync(PI_AGENT_SETTINGS)) return { claimed: false };
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(PI_AGENT_SETTINGS, "utf-8"));
+	} catch {
+		return { claimed: false };
+	}
+
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { claimed: false };
+	}
+	const settings = parsed as Record<string, unknown>;
+	const packages = settings.packages;
+	if (!Array.isArray(packages)) return { claimed: false };
+
+	const before = packages.length;
+	const next = packages.filter((p) => p !== ENTRY);
+	if (next.length === before) return { claimed: false };
+
+	settings.packages = next;
+	try {
+		writeFileSync(PI_AGENT_SETTINGS, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+	} catch {
+		return { claimed: false };
+	}
+	return { claimed: true };
+}

package/extensions/rpiv-core/ensure-builtins-disabled.test.ts

@@ -0,0 +1,83 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureBuiltinsDisabled } from "./ensure-builtins-disabled.js";
+
+const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
+
+function writeSettings(contents: unknown): void {
+	mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+	writeFileSync(SETTINGS_PATH, JSON.stringify(contents), "utf-8");
+}
+
+function readSettings(): unknown {
+	return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+}
+
+describe("ensureBuiltinsDisabled", () => {
+	it("no settings file → disabled: false", () => {
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+	});
+
+	it("invalid JSON → disabled: false, file byte-exact unchanged", () => {
+		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe("{not json");
+	});
+
+	it("non-object top-level → disabled: false, file unchanged", () => {
+		writeSettings([1, 2, 3]);
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+		expect(readSettings()).toEqual([1, 2, 3]);
+	});
+
+	it("absent subagents key: writes minimal subagents.disableBuiltins block, preserves other keys", () => {
+		writeSettings({
+			defaultProvider: "zai",
+			theme: "dark",
+			packages: ["npm:pi-subagents"],
+		});
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: true });
+		expect(readSettings()).toEqual({
+			defaultProvider: "zai",
+			theme: "dark",
+			packages: ["npm:pi-subagents"],
+			subagents: { disableBuiltins: true },
+		});
+	});
+
+	it("subagents object exists without disableBuiltins: adds key, preserves siblings (e.g. agentOverrides)", () => {
+		writeSettings({
+			subagents: {
+				agentOverrides: { scout: { model: "glm-5.1" } },
+			},
+		});
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: true });
+		expect(readSettings()).toEqual({
+			subagents: {
+				agentOverrides: { scout: { model: "glm-5.1" } },
+				disableBuiltins: true,
+			},
+		});
+	});
+
+	it("user-wins: explicit disableBuiltins: true → no-op (idempotent)", () => {
+		writeSettings({ subagents: { disableBuiltins: true } });
+		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
+	});
+
+	it("user-wins: explicit disableBuiltins: false → respected, NOT overwritten", () => {
+		writeSettings({ subagents: { disableBuiltins: false } });
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+		expect(readSettings()).toEqual({ subagents: { disableBuiltins: false } });
+	});
+
+	it("subagents is non-object (string) → no-op", () => {
+		writeSettings({ subagents: "not-object" });
+		expect(ensureBuiltinsDisabled()).toEqual({ disabled: false });
+		expect(readSettings()).toEqual({ subagents: "not-object" });
+	});
+});

package/extensions/rpiv-core/ensure-builtins-disabled.ts

@@ -0,0 +1,72 @@
+/**
+ * Set `subagents.disableBuiltins: true` in ~/.pi/agent/settings.json so
+ * pi-subagents@0.17.5's 9 bundled agents (scout, planner, worker, reviewer,
+ * context-builder, researcher, delegate, oracle, oracle-executor) don't show
+ * up alongside rpiv-pi's 13 bundled specialists. The rpiv skills only
+ * dispatch to the 13 specialists; keeping the builtins enabled clutters
+ * `/agents`, expands the LLM's choice surface, and risks accidental
+ * dispatches to unfamiliar generalists.
+ *
+ * User-wins: if `subagents.disableBuiltins` is already set to ANY boolean
+ * (true OR false) we leave it alone. Only an absent field gets seeded.
+ * Fail-soft: missing file / invalid JSON / non-object → silent no-op.
+ * Pure utility — no plugin API dependency.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_AGENT_SETTINGS = join(homedir(), ".pi", "agent", "settings.json");
+
+export interface EnsureBuiltinsDisabledResult {
+	/** True iff this call wrote `subagents.disableBuiltins: true`. */
+	disabled: boolean;
+}
+
+/**
+ * Seed `subagents.disableBuiltins: true` when absent. Returns a structured
+ * report so the caller can emit a conditional notify. Never throws.
+ */
+export function ensureBuiltinsDisabled(): EnsureBuiltinsDisabledResult {
+	if (!existsSync(PI_AGENT_SETTINGS)) return { disabled: false };
+
+	let parsed: unknown;
+	try {
+		const raw = readFileSync(PI_AGENT_SETTINGS, "utf-8");
+		parsed = JSON.parse(raw);
+	} catch {
+		return { disabled: false };
+	}
+
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { disabled: false };
+	}
+	const settings = parsed as Record<string, unknown>;
+
+	// User-wins: if `subagents` exists but isn't a plain object, leave it alone
+	// (don't clobber user data).
+	const hasSubagentsKey = "subagents" in settings;
+	if (
+		hasSubagentsKey &&
+		(!settings.subagents || typeof settings.subagents !== "object" || Array.isArray(settings.subagents))
+	) {
+		return { disabled: false };
+	}
+	const subagents = hasSubagentsKey ? (settings.subagents as Record<string, unknown>) : {};
+
+	if ("disableBuiltins" in subagents) {
+		// User-wins: respect any explicit boolean choice (including false).
+		return { disabled: false };
+	}
+
+	subagents.disableBuiltins = true;
+	settings.subagents = subagents;
+
+	try {
+		writeFileSync(PI_AGENT_SETTINGS, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+	} catch {
+		return { disabled: false };
+	}
+	return { disabled: true };
+}

package/extensions/rpiv-core/ensure-subagent-config.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureSubagentConfig } from "./ensure-subagent-config.js";
+
+const CONFIG_PATH = join(process.env.HOME ?? "", ".pi", "agent", "extensions", "subagent", "config.json");
+
+function writeConfig(contents: unknown): void {
+	mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+	writeFileSync(CONFIG_PATH, JSON.stringify(contents), "utf-8");
+}
+
+function readConfig(): unknown {
+	return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+}
+
+describe("ensureSubagentConfig", () => {
+	it("first run: creates config.json with both defaults", () => {
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(true);
+		expect(result.merged).toEqual(["parallel.concurrency", "maxSubagentDepth"]);
+		expect(readConfig()).toEqual({
+			parallel: { concurrency: 4 },
+			maxSubagentDepth: 3,
+		});
+	});
+
+	it("idempotent: re-run on complete config is a no-op", () => {
+		writeConfig({ parallel: { concurrency: 4 }, maxSubagentDepth: 3 });
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(false);
+		expect(result.merged).toEqual([]);
+	});
+
+	it("user-value wins: existing parallel.concurrency preserved", () => {
+		writeConfig({ parallel: { concurrency: 16 } });
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(false);
+		expect(result.merged).toEqual(["maxSubagentDepth"]);
+		expect(readConfig()).toEqual({
+			parallel: { concurrency: 16 },
+			maxSubagentDepth: 3,
+		});
+	});
+
+	it("partial state: adds concurrency alongside existing parallel.maxTasks", () => {
+		writeConfig({ parallel: { maxTasks: 10 } });
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(false);
+		expect(result.merged).toEqual(["parallel.concurrency", "maxSubagentDepth"]);
+		expect(readConfig()).toEqual({
+			parallel: { maxTasks: 10, concurrency: 4 },
+			maxSubagentDepth: 3,
+		});
+	});
+
+	it("invalid JSON fail-soft: no throw, no write (file byte-exact)", () => {
+		mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+		writeFileSync(CONFIG_PATH, "{not json", "utf-8");
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(false);
+		expect(result.merged).toEqual([]);
+		expect(readFileSync(CONFIG_PATH, "utf-8")).toBe("{not json");
+	});
+
+	it("non-object top-level JSON fail-soft", () => {
+		writeConfig([1, 2, 3]);
+		const result = ensureSubagentConfig();
+		expect(result.created).toBe(false);
+		expect(result.merged).toEqual([]);
+		expect(readConfig()).toEqual([1, 2, 3]);
+	});
+
+	it("preserves unrelated top-level + nested keys on merge", () => {
+		writeConfig({
+			asyncByDefault: true,
+			worktreeSetupHook: "/path/to/hook.sh",
+			parallel: { maxTasks: 10 },
+		});
+		const result = ensureSubagentConfig();
+		expect(result.merged).toEqual(["parallel.concurrency", "maxSubagentDepth"]);
+		expect(readConfig()).toEqual({
+			asyncByDefault: true,
+			worktreeSetupHook: "/path/to/hook.sh",
+			parallel: { maxTasks: 10, concurrency: 4 },
+			maxSubagentDepth: 3,
+		});
+	});
+});