@d3ara1n/pi-subagent 1.2.0 → 1.2.2

package/README.md

@@ -32,8 +32,8 @@ 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) |
+| `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 |
 
@@ -126,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"
@@ -177,7 +177,11 @@ Delegate tasks that would generate many tool calls or verbose output to keep you
 
 ## Background Delegation
 
-Foreground and background delegation share one async run engine — foreground is simply background-but-blocking. With `background: true`, `subagent_delegate` returns immediately with a run id, and two companion tools collect the outcome:
+Three execution properties, kept separate:
+
+- **Foreground** (default): the call blocks until the run finishes and returns the final output directly. (Under the hood foreground and background share one async run engine — foreground is simply background-but-blocking.)
+- **Parallel**: multiple `subagent_delegate` calls in one turn run concurrently — foreground and background alike, no special flag.
+- **Background** (`background: true`): non-blocking — `subagent_delegate` returns immediately with a run id. Use it when you have your own work to do (or a discussion with the user to continue) while the run executes; two companion tools collect the outcome:
 
 | Tool | Purpose | Returns to the model |
 |------|---------|---------------------|
@@ -204,6 +208,7 @@ Typical flow:
 
 Semantics worth knowing:
 
+- **Results are pull-only.** Nothing delivers them to the model — no completion event, no notification, nothing wakes the model up. The model owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists unclaimed runs on every request, but it never pushes results.
 - **Background runs survive turn cancellation** and are unaffected by a cancelled `subagent_wait` — cancelling the wait never cancels the runs; call `subagent_wait` or `subagent_check` again later.
 - **Read-once collection:** `subagent_check` on a terminal run returns the result and frees it — the output now lives in the conversation history, and only a lightweight tombstone stays in the registry (`/subagent:status` lists it under "Collected"). Re-checking a collected id explains that its result is already in the history.
 - **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the unclaimed runs (queued, running, and finished-but-unchecked alike), injected at a cache-stable head position. Runs missing from the list were already collected — so a finished run the model forgot to check keeps surfacing until it does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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

@@ -149,13 +149,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "",
       ...exampleLines,
       "",
-      "For multiple independent substantial tasks, emit multiple subagent_delegate calls in one turn — they run in parallel.",
+      "EXECUTION MODES:",
       "",
-      "BACKGROUND DELEGATION — start runs now, collect results later:",
+      "- Foreground (default): the call blocks until the run finishes and returns the final output directly.",
+      "- Parallel: multiple subagent_delegate calls at the same time run concurrently — foreground and background alike, no special flag.",
+      "- Background (background: true): non-blocking — returns an id immediately so you can do your own work while the run executes.",
       "",
-      "- Typical flow: subagent_delegate(background: true) ×N → keep working → subagent_wait(ids) to block until every listed run finishes (omit ids to wait for all) → subagent_check(id) for each finished run.",
-      "- A terminal check collects the run — the output is returned once and the run leaves the registry. Mid-run checks are free: peek at progress as often as you like; only terminal checks collect.",
-      "- Every LLM call carries a [background subagent runs] reminder listing your unclaimed runs (queued, running, and finished-but-unchecked alike). Runs missing from that list were already collected.",
+      "BACKGROUND DELEGATION:",
+      "",
+      "- Use it only when you have your own work this turn (including an ongoing discussion with the user) while the run executes; otherwise let the call block and return the result directly.",
+      "- Results are pull-only — no completion event, no notification, nothing wakes you. Dispatching means owning the collection point: finish your own work, then subagent_check(id) for each result. Use subagent_wait(ids) to block until the run finish.",
       "- Background delegation works only in the top-level session.",
     );
   }
@@ -267,7 +270,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       background: Type.Optional(
         Type.Boolean({
           description:
-            "Run asynchronously: returns an id (sub-N) immediately instead of blocking. The run survives turn cancellation.",
+            "Non-blocking: returns an id immediately so you can do your own work (or keep discussing with the user) while the run executes — not for parallelism (several foreground calls in one turn already run concurrently). Results are pull-only: nothing delivers them to you or wakes you; fetch with subagent_wait/subagent_check when your own work is done. If the next thing you'd do is wait for the result, omit this and let the call block.",
         }),
       ),
       cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),

package/src/reminder.test.ts

@@ -111,9 +111,9 @@ describe("buildInboxReminder", () => {
     assert.ok(text.includes(`"${"x".repeat(70)}..."`));
   });
 
-  test("header explains collection semantics", () => {
+  test("header explains pull-only collection semantics", () => {
     const text = buildInboxReminder([entry({ id: "sub-1", state: "running" })])!;
-    assert.match(text, /^\[background subagent runs — subagent_check claims/);
+    assert.match(text, /^\[background subagent runs — results are pull-only/);
     assert.match(text, /already collected\]/);
   });
 });

package/src/reminder.ts

@@ -28,7 +28,7 @@ export interface InboxEntry {
 }
 
 const INBOX_HEADER =
-  "[background subagent runs — subagent_check claims a terminal run's output and removes it from this list; runs missing here were already collected]";
+  "[background subagent runs — results are pull-only: nothing notifies you. subagent_wait, then subagent_check to collect each run; a terminal check removes it from this list; runs missing here were already collected]";
 
 /** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
 function formatDuration(totalSec: number): string {

package/src/roles.ts

@@ -15,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"),
   },
@@ -35,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",
@@ -44,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):",
@@ -67,8 +67,8 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
       "After each change, validate: run tests, check syntax, verify behavior.",
       "",
       "## Protecting your context",
-      "You have full tool access (web_search, fetch_content, MCP, ...) plus a `subagent_delegate` tool.",
-      "Use direct tools for quick lookups — e.g. check library docs/APIs with web_search or context7 before writing third-party code.",
+      "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 the research itself is a multi-step investigation",