pi-open-agents 0.1.14 → 0.1.16

package/README.md

@@ -34,6 +34,38 @@ Existing `.agent.md` files work without changes (default `mode: all`).
 
 ---
 
+## Agents vs subagents (and why you need both)
+
+People tend to lump "agents" and "subagents" together. They're not the same
+thing, and the difference is the whole game.
+
+An **agent** changes *your* session. Switch to one and the conversation you're
+already having starts thinking with a different brain — different prompt,
+different model, different tools, different rules. The thread keeps going;
+what's running it changes. Planning wants a slow, deliberate mind. Coding wants
+a fast one. Reviewing wants a skeptic. An agent is how you become the right one
+for the moment.
+
+A **subagent** never touches your session. It's a separate process you spin up
+for one job — usually on a cheaper, faster model, with locked-down permissions
+— that works in isolation and hands you back an answer. Your context stays
+clean; your main model keeps its focus.
+
+The payoff is using both. You sit in an **orchestrator** agent — the strong
+model holding the plan — and delegate the grunt work to subagents: search these
+five hundred files, run that test matrix, draft the boilerplate. One mind to
+think, many hands to do. You get the big model's reasoning *and* the small
+models' speed and economy, without one poisoning the other's context.
+
+And the moment you delegate, control stops being optional. A subagent is a real
+process with real tools — it can read your secrets, rewrite your files, run
+shell. So you choose its model, set its thinking level, clip its permissions to
+*read-only* or *git-only*, cap how deep it can recurse, decide who's even
+allowed to spawn whom. That's not red tape. It's what turns *delegate and pray*
+into *delegate and trust* — and it's exactly what this plugin gives you.
+
+---
+
 ## Why this exists
 
 Pi splits agent management across two separate plugins — one for primary agents,
@@ -91,8 +123,10 @@ permission:
   "subagent": deny        # no delegation
 ```
 
-Tool names are normalized automatically: `write` → `edit`, `task` → `subagent`,
-`vscode` → `read`.
+Tool names are normalized automatically: `task` → `subagent`, `vscode` → `read`,
+`apply_patch` → `edit` (OpenCode-only tool). In pi, `write` and `edit` are
+**separate** tools — `write` creates/overwrites files, `edit` does search-and-
+replace — so they have separate permission categories.
 
 ### Auto-injected delegation guidance
 
@@ -118,6 +152,11 @@ This means:
 - Each subagent runs with exactly the model and tools it declares
 - Skills load per-agent, with wildcard support (`security-*`, `git-*`)
 
+The `--tools` whitelist is derived from both explicit `tools:` arrays and
+permission allow-lists. An agent with `permission: { read: allow, edit: allow }`
+will only get `read` and `edit` in the child process. Wildcard permissions
+(`*: allow`) cannot produce a finite whitelist — the child gets all tools.
+
 ### OpenCode compatibility
 
 Your `.opencode/agent/` files work as-is. The `tools` map format is auto-converted
@@ -133,6 +172,10 @@ tools:
   bash: false
 ```
 
+The `tools` map is converted to permission rules and **also restricts the
+subagent child process** — a subagent with `tools: { read: true, bash: false }`
+will only have access to the `read` tool when spawned.
+
 ### Mode-based visibility
 
 | `mode` | TUI selector | `subagent` tool | `set_agent` tool |
@@ -249,9 +292,12 @@ Optional cleanup:
 
 ## Development
 
+**Contributing?** Please read the [Contributing Guide](./CONTRIBUTING.md) before
+opening an issue or pull request.
+
 ```bash
 npm install
-npm test          # 84 tests
+npm test          # 117 tests
 npm run typecheck # tsc --noEmit
 ```
 

package/agents/explorer.agent.md

@@ -0,0 +1,43 @@
+---
+name: explorer
+mode: subagent
+description: Dedicated investigation and reconnaissance agent for codebases, remote systems, REST APIs, and log sources. Returns structured, dense findings ready for direct use by the calling agent.
+# tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo']
+---
+
+You are an investigation agent. You explore codebases, remote systems, REST APIs, and log sources, then return precise, structured findings.
+
+## Scope
+
+| Domain | Examples |
+|--------|----------|
+| **Codebases** | Directory trees, file contents, dependency graphs, architecture, call chains |
+| **Remote systems** | SSH commands, cluster inspections, process lists, service status |
+| **REST APIs** | Endpoint discovery, request/response probing, auth flows, error patterns |
+| **Log sources** | Log files, journalctl, container logs, structured JSON logs, error correlation |
+
+## Principles
+
+1. **Answer the question, nothing else.** The calling agent gave you a specific task — deliver exactly what was asked.
+2. **Be precise.** File paths, line numbers, exact values, command output. No vagueness.
+3. **Be dense.** Strip filler. Every line in your response should carry information the caller needs.
+4. **Show evidence.** Quote relevant code, paste relevant output. The caller should not need to re-verify.
+5. **Structure the answer.** Use headings, tables, bullet lists — make it scannable. Start with a one-line TL;DR when the answer is complex.
+
+## Investigation Method
+
+Adapt to the target. Do not follow a rigid checklist.
+
+For **codebases**: identify entry points, trace the relevant path, report what you found and where.
+For **remote systems**: run targeted commands, report exact output, flag anything unexpected.
+For **APIs**: probe endpoints, capture status codes and response shapes, document the contract.
+For **logs**: filter to the relevant window/level, correlate events, report patterns and anomalies.
+
+If the task is broad ("explore this repo"), give a high-level architecture overview. If the task is specific ("how does auth work in module X"), trace the exact flow end-to-end.
+
+## Output Contract
+
+Your response is the only thing the calling agent sees. It must be:
+- **Self-contained** — no "you should also check…"; if something is relevant, include it now
+- **Actionable** — the caller can make decisions from your answer without further exploration
+- **Compact** — no preamble, no summary-of-what-you-did; just the findings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",
@@ -30,7 +30,8 @@
     "src/",
     "README.md",
     "LICENSE",
-    "ATTRIBUTION.md"
+    "ATTRIBUTION.md",
+    "agents/"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -64,6 +65,7 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsx": "^4.19.0",
+    "typebox": "^1.3.10",
     "typescript": "^5.6.0"
   }
 }

package/src/tui/tools.ts

@@ -14,6 +14,7 @@ import { Type } from "typebox";
 import type { AgentDefinition } from "../types.ts";
 import { selectableAgents } from "../discovery/loader.ts";
 import type { AgentManager } from "../primary/manager.ts";
+import { isSubagentProcess } from "../subagent/env.ts";
 import { updateBanner } from "./banner.ts";
 
 /**
@@ -32,6 +33,10 @@ export function registerAgentTools(manager: AgentManager, pi: ExtensionAPI): voi
       reason: Type.Optional(Type.String({ description: "Reason for switching agents" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+      if (isSubagentProcess(process.env)) {
+        throw new Error("set_agent is only available to the primary agent, not subagents.");
+      }
+
       const { agent: name, reason } = params;
 
       const agent = manager.getAgent(name);
@@ -40,6 +45,10 @@ export function registerAgentTools(manager: AgentManager, pi: ExtensionAPI): voi
         throw new Error(`Unknown agent "${name}". Available: ${available}`);
       }
 
+      if (agent.mode === "subagent") {
+        throw new Error(`Agent "${name}" is a subagent and cannot be set as the primary agent.`);
+      }
+
       const success = await manager.apply(name, pi, ctx);
       if (!success) {
         throw new Error(`Failed to apply agent "${name}"`);