@d3ara1n/pi-subagent 1.1.1 → 1.2.1

package/README.md

@@ -32,10 +32,12 @@ This means:
 
 | Role | Model Role | Timeout | Tools | Can Delegate To | Description |
 |------|-----------|---------|-------|-----------------|-------------|
-| `explorer` | fast | 900s | read, find, grep | — | Fast code search (read-only, no bash) |
-| `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review (read-only, bash for git/log) |
-| `worker` | default | 2400s | read, bash, edit, write, grep, find, delegate | explorer, researcher | Implementation — the only role that can modify files |
-| `researcher` | fast | 2400s | web_search, fetch_content, read, bash, delegate | explorer | Web research + GitHub repo analysis |
+| `explorer` | fast | 900s | read, find, grep | — | Fast code exploration (read-only) |
+| `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review, runs git/tests for evidence (read-only) |
+| `worker` | default | 2400s | all (no whitelist) | explorer, researcher | Implementation — the only role that can modify files; full tool access (web, MCP, everything) |
+| `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
+
+**Web tool naming**: `researcher`'s web tools use the community-standard names (`web_search`, `fetch_content`, `source_check`, `get_search_content`) shared by the most popular Pi web extensions — [pi-web-access](https://github.com/nicobailon/pi-web-access), `pi-web-tools`, `pi-browse`, and others. Install any of those and the researcher gets web access out of the box. If your web extension uses different tool names (e.g. `websearch`/`webfetch`) or you renamed the tools via a `toolNames` config, override `researcher.tools` in `agentOverrides` to match.
 
 **Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
 
@@ -124,7 +126,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
       },
       "tester": {
         "role": "default",
-        "description": "Test automation & QA — write and run tests, validate fixes. Tools: read, bash, edit, write, grep. Can delegate to explorer.",
+        "description": "Test automation & QA — write and run tests, validate fixes. Can delegate to explorer.",
         "examples": [
           "Write unit tests for the auth module",
           "Run the test suite and fix failing tests"
@@ -138,7 +140,7 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 }
 ```
 
-**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `tools`, `systemPrompt`.
+**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`. `tools` is optional — absent means all tools, a list restricts to those exact tool names.
 
 **Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/index.ts

@@ -188,12 +188,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
     applyAgentOverrides(availableRoles, config.agentOverrides);
 
     // Validate custom roles (skip built-in roles — they already have all fields)
+    // `tools` is optional — absent means the role gets all tools.
     const REQUIRED_FIELDS = [
       "role",
       "description",
       "examples",
       "decisionTrigger",
-      "tools",
       "systemPrompt",
     ] as const;
     for (const [name, role] of Object.entries(availableRoles)) {

package/src/roles.ts

@@ -2,7 +2,8 @@
  * Built-in subagent role definitions.
  *
  * Each maps to a pi-model-roles role and has a tailored system prompt
- * and tool set. Prompts are in English — concise, efficient, task-focused.
+ * and tool policy (an explicit allowlist, or all tools when unset).
+ * Prompts are in English — concise, efficient, task-focused.
  * Final output should be accurate and concise, stating conclusions directly.
  */
 
@@ -14,18 +15,18 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 900,
     description:
-      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures. Tools: read, find, grep. NO bash, NO edits, NO web access.",
+      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures.",
     examples: ["Find where auth middleware is implemented", "Map the routing structure"],
     decisionTrigger: "Task finds or maps code without touch?",
     tools: ["read", "find", "grep"],
     systemPrompt: [
-      "Fast code explorer. You have READ-ONLY tools only — no commands, no edits.",
-      "Grep/find to locate → read key sections only → identify types, interfaces, functions.",
-      "Never read entire files. Target specific line ranges.",
+      "Code explorer. READ-ONLY — locate code, understand it, and report findings; never modify anything.",
+      "Search to locate → read the files relevant to the task → trace imports, identify types, interfaces, functions.",
+      "Skip noise: lockfiles, vendored, minified, and generated files.",
       "",
-      "Output format (keep each section brief):",
+      "Output format:",
       "## Files: file paths with line ranges and one-line descriptions",
-      "## Findings: key types/functions with minimal code snippets",
+      "## Findings: key types/functions with short code snippets",
       "## Summary: direct answer to the task question",
     ].join("\n"),
   },
@@ -34,7 +35,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 3600,
     description:
-      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs. Tools: read, bash, grep, find. Has bash (git diff/log, test runs). NO edits, NO web access.",
+      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs, run tests for evidence.",
     examples: [
       "Review the error handling in src/api/ for security issues",
       "Audit this PR diff for performance regressions",
@@ -43,7 +44,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     tools: ["read", "bash", "grep", "find"],
     systemPrompt: [
       "Senior code reviewer. READ-ONLY — you must NOT modify any file.",
-      "bash is for read-only commands only (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
+      "Run only read-only commands (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
       "Provide evidence-backed findings with file:line references.",
       "",
       "Output format (prioritize critical issues first):",
@@ -56,10 +57,9 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     role: "default",
     timeout: 2400,
     description:
-      "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, find, subagent_delegate. Can delegate to explorer/researcher.",
+      "Full tool access — the ONLY role that can MODIFY files (edit, write, refactor, fix, implement). Can delegate to explorer/researcher.",
     examples: ["Rename all snake_case fields to camelCase", "Add input validation to POST /login"],
     decisionTrigger: "Task modifies files?",
-    tools: ["read", "bash", "edit", "write", "grep", "find", "subagent_delegate"],
     subagentRoles: ["explorer", "researcher"],
     systemPrompt: [
       "Implementation worker. Work autonomously — all context is in the task description.",
@@ -67,10 +67,12 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
       "After each change, validate: run tests, check syntax, verify behavior.",
       "",
       "## Protecting your context",
-      "You have a `subagent_delegate` tool. Use it to offload exploration and research:",
+      "You have full tool access plus a `subagent_delegate` tool.",
+      "Use direct tools for quick lookups — e.g. search the web for library docs/APIs before writing third-party code.",
+      "Delegate only when the work is substantial:",
       "- subagent_delegate(role=explorer) when you need to map unfamiliar code before editing",
-      "- subagent_delegate(role=researcher) when you need external docs or library references",
-      "Don't delegate tasks you can do with a single read or grep.",
+      "- subagent_delegate(role=researcher) when the research itself is a multi-step investigation",
+      "Don't delegate tasks you can do with a single read, grep, or web search.",
       "",
       "Output format (be brief — summarize, don't paste full diffs):",
       "## Changes: list each file touched and what changed",
@@ -82,23 +84,35 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 2400,
     description:
-      "the ONLY role with WEB ACCESS — search docs, fetch pages, analyze GitHub repos. Tools: web_search, fetch_content, read, bash, subagent_delegate. Can clone repos & delegate to explorer.",
+      "the ONLY role with WEB ACCESS — search docs, fetch pages, verify claims, analyze GitHub repos. Can clone repos & delegate to explorer.",
     examples: ["Find the React 19 migration guide", "Check GitHub issue #1234 for context"],
     decisionTrigger: "Task searches web or GitHub?",
-    tools: ["web_search", "fetch_content", "read", "bash", "subagent_delegate"],
+    tools: [
+      "web_search",
+      "fetch_content",
+      "source_check",
+      "get_search_content",
+      "read",
+      "bash",
+      "edit",
+      "write",
+      "subagent_delegate",
+    ],
     subagentRoles: ["explorer"],
     systemPrompt: [
       "Web researcher. Search with varied angles, prefer official docs over blogs.",
       "If first results are insufficient, refine queries and search again.",
       "",
+      "## Research artifacts",
+      "You may write files (downloaded docs, notes, intermediate results) — but ONLY under $PI_SUBAGENT_TMPDIR.",
+      "Never write anywhere else: project files and other directories are strictly off-limits.",
+      "",
       "## GitHub repo analysis",
       "When the task requires analyzing a GitHub repo:",
-      "1. git clone the repo into PI_SUBAGENT_TMPDIR (must exist)",
+      "1. Clone the repo into $PI_SUBAGENT_TMPDIR",
       "2. Use `subagent_delegate` with role=explorer to investigate the cloned codebase — pass the repo path and the research question",
       "3. Combine explorer findings with any web search results",
       "",
-      "bash is for git clone and read-only commands only. Never modify files.",
-      "",
       "Output format:",
       "## Answer: direct answer to the question (2-3 sentences)",
       "## Sources: list of URLs used",

package/src/types.ts

@@ -54,8 +54,11 @@ export interface SubagentRole {
   decisionTrigger: string;
   /** System prompt for the subagent */
   systemPrompt: string;
-  /** Tools available to this subagent */
-  tools: string[];
+  /**
+   * Tools available to this subagent. Empty or absent = all tools (no restriction).
+   * When set, only the listed tool names are exposed to the child (exact-name allowlist).
+   */
+  tools?: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
   /** Per-role active-time timeout in seconds. `0` or unset means unlimited; negative values are normalized to `0`. */