pi-open-agents 0.1.15 → 0.1.17

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,

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.15",
+  "version": "0.1.17",
   "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",

package/src/primary/executor.ts

@@ -64,7 +64,8 @@ async function applyModel(agent: AgentDefinition, pi: ExtensionAPI, ctx: Extensi
  * Falls back to the session's current thinking level if agent doesn't specify one.
  */
 function applyThinking(agent: AgentDefinition, pi: ExtensionAPI): void {
-  pi.setThinkingLevel(agent.thinking);
+  // Cast: pi-open-agents accepts "max" (aligned with CLI); pi-agent-core type lags behind
+  pi.setThinkingLevel(agent.thinking as any);
 }
 
 // ─── Tool Filtering ──────────────────────────────────────────────────────────

package/src/primary/manager.ts

@@ -82,8 +82,8 @@ export class AgentManager {
       if (this.originalState.model) {
         await pi.setModel(this.originalState.model);
       }
-      // Restore thinking level
-      pi.setThinkingLevel(this.originalState.thinkingLevel);
+      // Restore thinking level (cast: pi-agent-core type lags behind on "max")
+      pi.setThinkingLevel(this.originalState.thinkingLevel as any);
       // Restore tools
       pi.setActiveTools(this.originalState.toolNames);
     } else {

package/src/types.ts

@@ -10,7 +10,7 @@
 
 export type AgentMode = "primary" | "subagent" | "all";
 
-export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 export type SystemPromptMode = "append" | "replace" | "replace-all";
 
@@ -19,7 +19,7 @@ export type PermissionAction = "allow" | "deny" | "ask";
 export type AgentSource = "global" | "project";
 
 export const THINKING_LEVELS: readonly ThinkingLevel[] = [
-  "off", "minimal", "low", "medium", "high", "xhigh",
+  "off", "minimal", "low", "medium", "high", "xhigh", "max",
 ] as const;
 
 export const SYSTEM_PROMPT_MODES: readonly SystemPromptMode[] = [