@narumitw/pi-subagents 0.17.1 → 0.18.0

package/README.md

@@ -335,7 +335,43 @@ You are an API review subagent. Do not edit files. Check compatibility,
 test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
 ```
 
-By default, `subagent` loads user agents only. Set `agentScope` to `"project"` or `"both"` to load project-local agents. Interactive sessions ask for confirmation before using project agents unless `confirmProjectAgents` is disabled.
+`agentScope` is a top-level tool argument supplied per invocation. It is not a setting in
+`~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter. The scope selects which
+custom agent directories are loaded; built-in agents remain available in every scope:
+
+| `agentScope` | Custom agents loaded |
+| --- | --- |
+| `"user"` (default) | User agents only. |
+| `"project"` | Project-local agents only. |
+| `"both"` | User and project-local agents. Project definitions override same-named user definitions. |
+
+For example, invoke a project-local agent with the blocking `subagent` tool:
+
+```json
+{
+  "agent": "api-reviewer",
+  "task": "Review this project's API changes",
+  "agentScope": "project"
+}
+```
+
+Or select the scope when creating a stateful agent with `subagent_spawn`:
+
+```json
+{
+  "agent": "api-reviewer",
+  "task": "Review this project's API changes",
+  "agentScope": "project"
+}
+```
+
+A stateful agent retains the scope selected by `subagent_spawn` for its follow-ups. Every new
+blocking `subagent` invocation or `subagent_spawn` call that needs project agents must supply
+`agentScope: "project"` or `"both"` again.
+
+Project-local agents require a trusted Pi project. Interactive sessions also ask for confirmation
+before using them by default. Passing `confirmProjectAgents: false` as another top-level tool
+argument skips that confirmation dialog, but it does not bypass the project trust requirement.
 
 ## ⏱️ Runtime limits and thinking levels
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.17.1",
+	"version": "0.18.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/config-ui.ts

@@ -4,8 +4,8 @@ import {
 	Container,
 	Key,
 	matchesKey,
-	SelectList,
 	type SelectItem,
+	SelectList,
 	Spacer,
 	Text,
 	truncateToWidth,
@@ -20,7 +20,7 @@ import {
 	uniqueToolNames,
 } from "./settings.js";
 
-class ToolToggleList {
+export class ToolToggleList {
 	private items: { name: string; selected: boolean }[];
 	private cursor = 0;
 	private cachedWidth?: number;
@@ -98,6 +98,7 @@ export function registerSubagentConfigCommand(pi: ExtensionAPI) {
 			}
 
 			// Loop: agent selection → tool toggle (Esc in tools returns here)
+			let selectedAgentIndex = 0;
 			while (true) {
 				// Step 1: pick an agent to configure
 				const agentItems: SelectItem[] = agents.map((a) => {
@@ -133,7 +134,20 @@ export function registerSubagentConfigCommand(pi: ExtensionAPI) {
 						scrollInfo: (t: string) => theme.fg("dim", t),
 						noMatch: (t: string) => theme.fg("warning", t),
 					});
-					selectList.onSelect = (item) => done(item.value);
+					selectList.setSelectedIndex(selectedAgentIndex);
+					selectList.onSelectionChange = (item) => {
+						selectedAgentIndex = Math.max(
+							0,
+							agentItems.findIndex((candidate) => candidate.value === item.value),
+						);
+					};
+					selectList.onSelect = (item) => {
+						selectedAgentIndex = Math.max(
+							0,
+							agentItems.findIndex((candidate) => candidate.value === item.value),
+						);
+						done(item.value);
+					};
 					selectList.onCancel = () => done(null);
 					container.addChild(selectList);
 					container.addChild(
@@ -193,7 +207,11 @@ export function registerSubagentConfigCommand(pi: ExtensionAPI) {
 					);
 					container.addChild(new Spacer(1));
 					container.addChild(
-						new Text(theme.fg("muted", "Toggle tools with Enter/Space. S to save, Esc to cancel."), 1, 0),
+						new Text(
+							theme.fg("muted", "Toggle tools with Enter/Space. S to save, Esc to cancel."),
+							1,
+							0,
+						),
 					);
 					container.addChild(new Spacer(1));
 
@@ -206,7 +224,11 @@ export function registerSubagentConfigCommand(pi: ExtensionAPI) {
 
 					container.addChild(new Spacer(1));
 					container.addChild(
-						new Text(theme.fg("dim", "↑↓ navigate · enter/space toggle · S save · esc cancel"), 1, 0),
+						new Text(
+							theme.fg("dim", "↑↓ navigate · enter/space toggle · S save · esc cancel"),
+							1,
+							0,
+						),
 					);
 					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 

package/src/params.ts

@@ -37,7 +37,8 @@ const AggregatorItem = Type.Object({
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
-	description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
+	description:
+		'Per-invocation custom agent scope. Default: "user". Use "project" for project-local agents or "both" for user and project agents; this is a tool argument, not a pi-subagents.json setting.',
 	default: "user",
 });
 

package/src/stateful.ts

@@ -31,7 +31,11 @@ const ContextModeSchema = Type.Union([
 	StringEnum(["none", "all", "summary"] as const),
 	Type.Number({ minimum: 1, description: "Include the most recent N user turns." }),
 ]);
-const ScopeSchema = StringEnum(["user", "project", "both"] as const);
+const ScopeSchema = StringEnum(["user", "project", "both"] as const, {
+	description:
+		'Per-invocation custom agent scope for this spawn. Default: "user". Use "project" for project-local agents or "both" for user and project agents; the selected scope is retained for follow-ups.',
+	default: "user",
+});
 const MAX_TOOL_MESSAGE_BYTES = 2 * 1024;
 const MAX_COMPLETION_ERROR_BYTES = 512;
 

package/src/subagents.ts

@@ -30,7 +30,7 @@ export default function (pi: ExtensionAPI) {
 			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
 			"Parallel mode may include an aggregator fan-in step that receives all task outputs.",
 			'Default agent scope is "user" (from ~/.pi/agent/agents).',
-			'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
+			'To enable project-local agents in .pi/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.',
 		].join(" "),
 		promptSnippet:
 			"Decide whether to spawn 0, 1, or multiple subagents for independent research, review, verification, or multi-step work in isolated Pi processes.",