pi-fast-subagent 0.5.0 → 0.5.1

package/README.md

@@ -61,6 +61,51 @@ model: anthropic/claude-haiku-4-5
 You are code exploration specialist. Read relevant files, trace data flow, summarize findings clearly.
 ```
 
+## Background Agents
+
+Every foreground subagent can be moved to background at any time. Background jobs run concurrently while you continue chatting. When a job finishes, pi automatically posts the result as a follow-up message.
+
+### Status bar
+
+While a foreground subagent is running, the pi status bar shows:
+```
+{agent-name} running · Ctrl+Shift+B to move to background
+```
+
+While background jobs are running:
+```
+⧗ N bg agents
+```
+
+### Moving to background
+
+**Keyboard shortcut (while subagent is running):**
+```
+Ctrl+Shift+B
+```
+
+**Slash command:**
+```
+/fast-subagent:bg fg_ab12cd34
+```
+
+**Via tool call:**
+```js
+subagent({ action: "detach", jobId: "fg_ab12cd34" })
+```
+
+### Auto-completion announcement
+
+When a background job finishes, pi injects a follow-up message automatically:
+```
+Background subagent ✓: sa_ab12cd34 (scout, 4.2s)
+> Explore src and summarize architecture
+
+<result output>
+```
+
+Failed jobs are announced the same way with ✗ and the error message.
+
 ## Slash Commands
 
 ### `/fast-subagent:agent`
@@ -81,13 +126,13 @@ Tab-completion is supported for agent names.
 
 ### `/fast-subagent:bg`
 
-Detach running foreground subagent to background:
+Detach a running foreground subagent to background. Each foreground job has a `fg_` prefixed ID shown in the status bar.
 
 ```
 /fast-subagent:bg fg_ab12cd34
 ```
 
-Omit job id to list active foreground jobs:
+Omit ID to list all active foreground jobs:
 
 ```
 /fast-subagent:bg
@@ -95,13 +140,13 @@ Omit job id to list active foreground jobs:
 
 ### `/fast-subagent:bg-status`
 
-Show active background subagents in selector UI. Arrow keys move selection. Enter shows full details for selected job.
+Open selector UI showing all active background jobs. Arrow keys to navigate, Enter to view full details.
 
 ```
 /fast-subagent:bg-status
 ```
 
-Show details for specific background job:
+Skip the selector — show details for a specific job directly:
 
 ```
 /fast-subagent:bg-status sa_ab12cd34
@@ -109,52 +154,58 @@ Show details for specific background job:
 
 ### `/fast-subagent:bg-cancel`
 
-Cancel running background subagent. Omit job id to open selector UI, then choose job with arrow keys.
+Open selector UI to choose a running job to cancel:
 
 ```
 /fast-subagent:bg-cancel
 ```
 
-Cancel specific background job directly:
+Cancel a specific job directly:
 
 ```
 /fast-subagent:bg-cancel sa_ab12cd34
 ```
 
-## Usage
+## Keyboard Shortcuts
 
-### List agents
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Shift+B` | Move active foreground subagent to background |
 
-```js
-subagent({ action: "list" })
-```
+## Roadmap
 
-### Single
+Goal: keep this extension **small and focused** — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.
 
-```js
-subagent({
-  agent: "scout",
-  task: "Explore src and summarize architecture"
-})
-```
+- **UI/UX polish** — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
+- ~~**Background subagents**~~ ✔ shipped in v0.4.0 — fire-and-forget with `background: true`, poll/cancel/detach support
+
+## Notes
+
+- Async/background isolation not supported in-process
+- Git worktree isolation not supported
+- Nested subagent depth limited to 2 by default
+
+## Tool Reference
 
-### General-purpose built-in agent
+> These are `subagent` tool call examples used by the LLM internally. Not typically invoked directly by users.
+
+### List / discover agents
 
 ```js
-subagent({
-  agent: "general",
-  task: "Summarize open TODOs and propose next step"
-})
+// List all agents
+subagent({ action: "list" })
+
+// Get details for a specific agent
+subagent({ action: "get", agent: "scout" })
+
+// Scope filter: "user" | "project" | "both" (default)
+subagent({ action: "list", agentScope: "project" })
 ```
 
-### Override model
+### Single
 
 ```js
-subagent({
-  agent: "scout",
-  task: "Explore src and summarize architecture",
-  model: "anthropic/claude-haiku-4-5"
-})
+subagent({ agent: "scout", task: "Explore src and summarize architecture" })
 ```
 
 ### Parallel
@@ -165,42 +216,32 @@ subagent({
     { agent: "scout", task: "Map auth flow" },
     { agent: "scout", task: "Map navigation" }
   ],
-  concurrency: 2
+  concurrency: 2  // default: 4
 })
+
+// Repeat one task N times
+subagent({ tasks: [{ agent: "scout", task: "Explore src", count: 3 }] })
 ```
 
-### Background (fire-and-forget)
+### Background
 
 ```js
-// Dispatch — returns job ID immediately
+// Fire-and-forget — returns job ID immediately
 subagent({ agent: "scout", task: "Explore src", background: true })
 // → { jobId: "sa_ab12cd34", status: "running" }
 
-// Poll — check result / progress
-subagent({ action: "poll", jobId: "sa_ab12cd34" })
-
-// Cancel
-subagent({ action: "cancel", jobId: "sa_ab12cd34" })
-
-// List all background jobs
-subagent({ action: "status" })
-
-// Detach a running foreground job to background
-subagent({ action: "detach", jobId: "fg_ab12cd34" })
+subagent({ action: "poll",   jobId: "sa_ab12cd34" })  // check progress
+subagent({ action: "cancel", jobId: "sa_ab12cd34" })  // abort
+subagent({ action: "status" })                        // list all bg jobs
+subagent({ action: "detach", jobId: "fg_ab12cd34" })  // move fg → bg
 ```
 
-## Roadmap
-
-Goal: keep this extension **small and focused** — aligned with pi's philosophy of minimal, composable tooling. No feature creep. Every addition must earn its place.
+### Options
 
-- **UI/UX polish** — improve visibility of running subagents: clearer status lines, better progress feedback, agent name + task always visible during execution
-- **Background agents** — ala claude code
-
-## Notes
-
-- Async/background isolation not supported in-process
-- Git worktree isolation not supported
-- Nested subagent depth limited to 2 by default
+```js
+subagent({ agent: "scout", task: "...", model: "anthropic/claude-haiku-4-5" })
+subagent({ agent: "scout", task: "...", cwd: "/path/to/project" })
+```
 
 ## Publish
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fast-subagent",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "In-process subagent delegation for pi with single, parallel, and background modes",
   "type": "module",
   "keywords": [