@narumitw/pi-plan-mode 0.24.0 → 0.27.0

package/README.md

@@ -12,6 +12,7 @@ Pi core intentionally does not ship a built-in plan mode; this package provides
 - Adds `--plan` to start a session in Plan mode.
 - Enables built-in read-only tools by default while Plan mode is active.
 - Disables extension and custom tools by default, with a `/plan tools` selector for explicit user-risk opt-in.
+- Optionally limits `subagent` and `subagent_spawn` launches to named planning roles while Plan mode is active.
 - Blocks `update_plan`, mutating built-in tools, and unsafe `bash` forms such as writes, substitutions, background jobs, dependency installs, and mutating Git commands.
 - Injects Codex-like Plan mode instructions: explore first, ask decision questions for high-impact ambiguity, do not mutate files, and finalize only when decision-complete.
 - Adds required `plan_mode_question` and `plan_mode_complete` tools for structured questions and completion.
@@ -90,7 +91,8 @@ Create `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-m
 ```json
 {
   "thinkingLevel": "inherit",
-  "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
+  "defaultPlanTools": ["read", "bash", "grep", "find", "ls", "subagent"],
+  "allowedPlanSubagents": ["plan-scout", "plan-researcher", "plan-reviewer"],
   "safeSubcommands": {
     "git": ["status", "log", "rev-parse", "blame"],
     "gh": ["pr view", "pr list", "issue view", "issue list"]
@@ -106,6 +108,16 @@ Tool names must be non-empty strings; duplicates are removed in first-seen order
 
 A selection made with `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes. The global setting remains the baseline for fresh sessions and sessions without an explicit selection.
 
+### Allowed Plan subagents
+
+`allowedPlanSubagents` is an optional, exact, case-sensitive allowlist of role names for subagent launches while Plan mode is active. It does not activate delegation tools by itself: add `subagent` or `subagent_spawn` to `defaultPlanTools`, or select the tool through `/plan tools`. The same role policy applies whichever activation path is used.
+
+When configured, Plan mode checks every role in blocking `subagent` single, parallel, chain, and fan-in calls (`agent`, `tasks[].agent`, `chain[].agent`, and `aggregator.agent`) and the top-level `agent` in `subagent_spawn`. A call containing any disallowed role is rejected as a whole before the launch tool executes. Covered calls whose role fields cannot be verified are also rejected so a malformed launch cannot bypass the policy.
+
+Omit `allowedPlanSubagents` to preserve the unrestricted role behavior for explicitly enabled delegation tools. Set it to `[]` to reject every covered launch in Plan mode. Names must be non-empty strings; duplicates are removed in first-seen order. A wrong type or an empty, whitespace-only, or non-string entry invalidates the settings file and triggers the normal warning/default fallback. Settings reload on `session_start`; removing the property removes the role restriction. Non-Plan sessions are never restricted. If no extension has registered the covered tool names, the setting is inert, so `pi-plan-mode` and `pi-subagents` remain independently installable.
+
+This is a name check, not capability enforcement or a sandbox. `pi-plan-mode` does not inspect an allowed role's effective tools, permissions, or source. User or project definitions can change or override the meaning of an allowed name, so keep every allowed role independently read-only and retain normal project-agent trust and confirmation controls. The policy does not resolve retained agent IDs used by `subagent_send`; enabling follow-up lifecycle tools remains a separate user-risk decision.
+
 ### Safe shell subcommands
 
 `safeSubcommands` adds reviewed command validators to limited `bash`; it is not a raw shell allowlist. Only the following exact values are accepted:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.24.0",
+	"version": "0.27.0",
 	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
 	"type": "module",
 	"license": "MIT",

package/src/plan-mode.ts

@@ -32,6 +32,7 @@ import {
 	readPlanModeSettings,
 } from "./settings.js";
 import { type PlanCompletionSource, type PlanModeState, restorePlanModeState } from "./state.js";
+import { enforcePlanSubagentAllowlist } from "./subagent-policy.js";
 import {
 	canSelectToolInPlanMode,
 	classifyPlanModeTool,
@@ -264,6 +265,14 @@ export default function planMode(pi: ExtensionAPI) {
 					"Plan mode blocks update_plan because it tracks execution progress rather than conversational planning.",
 			};
 		}
+		if (settings.allowedPlanSubagents !== undefined) {
+			const blocked = enforcePlanSubagentAllowlist(
+				event.toolName,
+				event.input,
+				settings.allowedPlanSubagents,
+			);
+			if (blocked) return blocked;
+		}
 		const calledTool = toolByName(event.toolName);
 		if (calledTool && classifyPlanModeTool(calledTool) === "blocked") {
 			return {

package/src/settings.ts

@@ -28,6 +28,7 @@ export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit
 export interface PlanModeSettings {
 	thinkingLevel: PlanModeThinkingLevel;
 	defaultPlanTools?: string[];
+	allowedPlanSubagents?: string[];
 	safeSubcommands?: SafeSubcommands;
 }
 export type PlanModeSettingsLoadResult =
@@ -51,6 +52,11 @@ export function normalizePlanModeSettings(value: unknown): PlanModeSettings | un
 		if (!defaultPlanTools) return undefined;
 		settings.defaultPlanTools = defaultPlanTools;
 	}
+	if (Object.hasOwn(value, "allowedPlanSubagents")) {
+		const allowedPlanSubagents = normalizeToolNames(Reflect.get(value, "allowedPlanSubagents"));
+		if (!allowedPlanSubagents) return undefined;
+		settings.allowedPlanSubagents = allowedPlanSubagents;
+	}
 	if (Object.hasOwn(value, "safeSubcommands")) {
 		const safeSubcommands = normalizeSafeSubcommands(Reflect.get(value, "safeSubcommands"));
 		if (!safeSubcommands) return undefined;

package/src/subagent-policy.ts

@@ -0,0 +1,98 @@
+export interface PlanSubagentPolicyBlock {
+	block: true;
+	reason: string;
+}
+
+const COVERED_SUBAGENT_TOOLS = new Set(["subagent", "subagent_spawn"]);
+
+export function enforcePlanSubagentAllowlist(
+	toolName: string,
+	input: unknown,
+	allowedRoleNames: readonly string[],
+): PlanSubagentPolicyBlock | undefined {
+	if (!COVERED_SUBAGENT_TOOLS.has(toolName)) return undefined;
+
+	const requestedRoleNames =
+		toolName === "subagent_spawn" ? readSpawnRoleNames(input) : readBlockingRoleNames(input);
+	const allowedNames = unique(allowedRoleNames);
+	if (!requestedRoleNames) {
+		return {
+			block: true,
+			reason: `Plan mode could not verify subagent roles for tool '${toolName}'. ${formatAllowedRoles(allowedNames)}`,
+		};
+	}
+
+	const allowed = new Set(allowedNames);
+	const disallowedNames = unique(requestedRoleNames).filter((name) => !allowed.has(name));
+	if (disallowedNames.length === 0) return undefined;
+
+	return {
+		block: true,
+		reason: `Plan mode blocks subagent role(s): ${disallowedNames.join(", ")}. ${formatAllowedRoles(allowedNames)}`,
+	};
+}
+
+function readSpawnRoleNames(input: unknown) {
+	if (!isRecord(input)) return undefined;
+	const agent = readRoleName(input.agent);
+	return agent ? [agent] : undefined;
+}
+
+function readBlockingRoleNames(input: unknown) {
+	if (!isRecord(input)) return undefined;
+	const roleNames: string[] = [];
+	let hasRoleField = false;
+
+	if (Object.hasOwn(input, "agent")) {
+		hasRoleField = true;
+		const agent = readRoleName(input.agent);
+		if (!agent) return undefined;
+		roleNames.push(agent);
+	}
+	for (const field of ["tasks", "chain"] as const) {
+		if (!Object.hasOwn(input, field)) continue;
+		hasRoleField = true;
+		const agents = readRoleArray(input[field]);
+		if (!agents) return undefined;
+		roleNames.push(...agents);
+	}
+	if (Object.hasOwn(input, "aggregator")) {
+		hasRoleField = true;
+		if (!isRecord(input.aggregator)) return undefined;
+		const agent = readRoleName(input.aggregator.agent);
+		if (!agent) return undefined;
+		roleNames.push(agent);
+	}
+
+	return hasRoleField && roleNames.length > 0 ? roleNames : undefined;
+}
+
+function readRoleArray(value: unknown) {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	const roleNames: string[] = [];
+	for (const item of value) {
+		if (!isRecord(item)) return undefined;
+		const agent = readRoleName(item.agent);
+		if (!agent) return undefined;
+		roleNames.push(agent);
+	}
+	return roleNames;
+}
+
+function readRoleName(value: unknown) {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatAllowedRoles(allowedRoleNames: readonly string[]) {
+	return allowedRoleNames.length > 0
+		? `Allowed Plan subagents: ${allowedRoleNames.join(", ")}.`
+		: "No subagent roles are allowed in Plan mode.";
+}
+
+function unique(values: readonly string[]) {
+	return Array.from(new Set(values));
+}