@narumitw/pi-subagents 0.17.0 → 0.17.2

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.0",
+	"version": "0.17.2",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

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.",