pi-agent-squad 0.7.0 → 0.8.0

package/README.md

@@ -25,7 +25,7 @@ Reload Pi after installation:
 
 **Identity (prompt layer)**:
 - `agents/*.md`: defines each subagent's identity, duties, model, tools (e.g. planner/reviewer/actor).
-- `orchestrator.md`: defines the main agent's outcome-oriented Discover → Decide → Execute → Verify workflow (optional injection).
+- `orchestrator.md`: gives main adaptive authority to choose direct work or any useful combination of planner/actor/reviewer, while weighing each role's value and risks.
 - The bottom layer never cares who is who — it only delivers messages.
 
 ## Messaging tools (shared by all agents)
@@ -43,7 +43,8 @@ Reload Pi after installation:
 - **Delegation**: `subagent` tool (sync / background `async:true`); background results are injected into the main session when done.
 - **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + resident RPC process pool.
 - **Non-blocking**: background tasks do not occupy the main session.
-- **Default safety gate**: unless the current user explicitly requests subagent involvement or `/orchestrate` is enabled, the main-agent system prompt forbids subagent delegation.
+- **Adaptive orchestration by default**: main decides whether delegation improves speed, quality, context management, independent judgment, or parallel progress, and also weighs latency, over-analysis, misunderstanding, duplication, and integration risk.
+- **Explicit opt-out**: `/orchestrate off` disables automatic delegation for the session; users can still explicitly request any subagent. `/orchestrate on` restores main-agent discretion.
 - **Bounded execution**: one-shot and resident tasks have configurable timeouts (default 6 hours, maximum 3 days); omit `timeoutSeconds` unless the user explicitly requested a time. Timed-out or crashed resident processes are discarded before the next task.
 - **Reliable messaging**: `send_message(wait=true)` waits for and returns the target's actual reply; `wait=false` remains fire-and-forget.
 - **Deadlock prevention**: synchronous wait cycles such as `main -> planner -> main`, self-messages, and `actor -> reviewer -> actor` are detected and rejected immediately with a recovery hint.
@@ -182,20 +183,20 @@ subagents/
 |-- message.ts      # generic messaging (file channel + send/reply/read + main-side router)
 |-- session.ts      # common interactive session-handle interface
 |-- session-ui.ts   # focused overlay for live transcript + interactive input
-|-- orchestrator.md # main-agent outcome/workflow prompt (optional injection)
+|-- orchestrator.md # main-agent adaptive delegation prompt (enabled by default)
 `-- README.md
 ```
 
 ## Usage
 
 ```bash
-# optional: inject the main-agent specialist-workflow identity
+# optional CLI equivalent of forcing adaptive orchestration on
 pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 
 # or in-session
-/orchestrate            # enable orchestrator mode (injects the triage identity every turn)
-/orchestrate off        # disable
-/orchestrate status     # check state
+/orchestrate            # enable adaptive orchestration (default)
+/orchestrate off        # require explicit user requests before using subagents
+/orchestrate status     # check adaptive orchestration state
 
 # in conversation
 "Resolve this architecture decision, then implement it" # planner is used when a Decision Brief is needed
@@ -203,3 +204,8 @@ pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 "Use subagent agent=reviewer timeoutSeconds=120 ..." # override the default 6h task timeout (only when the user asked)
 "Have reviewer review the recent changes"            # main agent delegates to reviewer
 ```
+
+Main is not required to follow a fixed planner → actor → reviewer chain. It may
+work directly, use only actor for high-throughput implementation, ask planner
+for a decision and implement it itself, or request reviewer only when an
+independent pass is worth its latency and false-positive risk.

package/index.ts

@@ -185,21 +185,19 @@ function sessionRoot(sessionId: string): string {
 
 const ORCHESTRATOR_MODE_ENTRY = "orchestrator-mode";
 const ORCHESTRATOR_PROMPT_MARKER = "# You are the Orchestrator";
-const SUBAGENT_USAGE_GUARD = [
-	"# Subagent Usage Gate",
+const SUBAGENT_USAGE_DISABLED_GUARD = [
+	"# Subagent Usage Policy: Automatic Delegation Disabled",
 	"",
-	"Do not use subagents unless at least one of these conditions is true:",
-	"1. The user's current request explicitly asks you to use, call, spawn, delegate to, or communicate with a subagent.",
-	"2. Orchestrator mode is enabled.",
+	"Automatic subagent delegation has been explicitly disabled for this session.",
+	"Do not use subagents unless the user's current request explicitly asks you to use, call, spawn, delegate to, or communicate with one.",
 	"",
-	"When neither condition is true:",
+	"When the user has not explicitly requested subagent involvement:",
 	"- Do not call the `subagent` tool.",
 	"- Do not call `send_message` to contact or assign work to a subagent.",
 	"- Do not initiate or continue a planner/actor/reviewer workflow.",
 	"- Perform the task yourself using the normal tools available to the main agent.",
 	"",
-	"Task complexity, convenience, a desire for planning/review, the availability of subagent tools, or prior subagent use are not authorization.",
-	"A generic request to plan, review, test, or implement something is not authorization unless the user explicitly requests subagent involvement.",
+	"The user can still explicitly request any combination of planner, actor, or reviewer while automatic delegation is disabled.",
 ].join("\n");
 
 function orchestratorPromptPath(): string {
@@ -222,7 +220,11 @@ function readOrchestratorPrompt(): string {
 	return orchestratorPromptCache;
 }
 
-/** Read the current session's orchestrator-mode flag (the last entry wins) */
+/**
+ * Read the current session's adaptive-orchestration flag (the last entry wins).
+ * Adaptive orchestration is enabled by default; `/orchestrate off` is an
+ * explicit per-session opt-out.
+ */
 function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown[] } }): boolean {
 	try {
 		const entries = (ctx.sessionManager?.getEntries?.() ?? []) as Array<{
@@ -230,7 +232,7 @@ function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown
 			customType?: string;
 			data?: { enabled?: boolean };
 		}>;
-		let enabled = false;
+		let enabled = true;
 		for (const e of entries) {
 			if (e.type === "custom" && e.customType === ORCHESTRATOR_MODE_ENTRY && typeof e.data?.enabled === "boolean") {
 				enabled = e.data.enabled;
@@ -238,7 +240,7 @@ function isOrchestratorMode(ctx: { sessionManager?: { getEntries?: () => unknown
 		}
 		return enabled;
 	} catch {
-		return false;
+		return true;
 	}
 }
 
@@ -971,7 +973,7 @@ export default function (pi: ExtensionAPI) {
 		return runId;
 	}
 
-	// ---- system prompt gate: subagents require explicit user authorization or orchestrator mode ----
+	// ---- adaptive orchestration prompt; `/orchestrate off` installs the explicit opt-out guard ----
 	pi.on("before_agent_start", (event, ctx) => {
 		// Treat an explicitly appended orchestrator prompt (CLI
 		// --append-system-prompt) as orchestrator mode too.
@@ -982,7 +984,7 @@ export default function (pi: ExtensionAPI) {
 			if (!prompt) return;
 			return { systemPrompt: event.systemPrompt + "\n\n" + prompt };
 		}
-		return { systemPrompt: event.systemPrompt + "\n\n" + SUBAGENT_USAGE_GUARD };
+		return { systemPrompt: event.systemPrompt + "\n\n" + SUBAGENT_USAGE_DISABLED_GUARD };
 	});
 
 	// ---- subagent tool ----
@@ -1093,7 +1095,7 @@ export default function (pi: ExtensionAPI) {
 
 	// ---- commands ----
 	pi.registerCommand("orchestrate", {
-		description: "Turn multi-agent orchestration mode on/off (on|off|status, default on)",
+		description: "Enable/disable adaptive subagent delegation (on|off|status, default on)",
 		handler: async (args, ctx) => {
 			const first = Array.isArray(args) ? (args[0] ?? "on") : String(args ?? "on").trim().split(/\s+/)[0] ?? "on";
 			const arg = String(first).toLowerCase();
@@ -1102,8 +1104,8 @@ export default function (pi: ExtensionAPI) {
 				const on = isOrchestratorMode(ctx);
 				ctx.ui.notify(
 					on
-						? "Orchestrator mode: ON (runs as orchestrator each turn; use /orchestrate off to disable)"
-						: "Orchestrator mode: OFF (use /orchestrate on to enable)",
+						? "Adaptive orchestration: ON (main decides whether and how to delegate; use /orchestrate off to disable automatic delegation)"
+						: "Adaptive orchestration: OFF (subagents require an explicit user request; use /orchestrate on to restore main-agent discretion)",
 					"info",
 				);
 				return;
@@ -1117,8 +1119,8 @@ export default function (pi: ExtensionAPI) {
 			}
 			ctx.ui.notify(
 				enabled
-					? "Orchestrator mode enabled — every turn will run as the orchestrator (triage + orchestrate subagents)"
-					: "Orchestrator mode disabled",
+					? "Adaptive orchestration enabled — main will decide whether to work directly or delegate to any useful combination of specialists"
+					: "Adaptive orchestration disabled — subagents now require an explicit user request",
 				"info",
 			);
 		},

package/orchestrator.md

@@ -5,72 +5,81 @@ description: Main agent system prompt — outcome ownership with optional specia
 
 # You are the Orchestrator
 
-You are the primary owner of the user's outcome. Use specialists when their
-distinct capability materially improves the result. Choose the smallest
-workflow that delivers the outcome reliably, and remain responsible for
-reconnaissance, integration, user communication, and final delivery.
+You are the primary owner of the user's outcome. You have authority to decide
+whether to complete work directly or delegate any useful part of it to
+`planner`, `actor`, or `reviewer`. The user does not need to explicitly request
+subagent involvement.
 
-## Working model
+Base each decision on the actual task, available context, uncertainty,
+execution volume, model strengths, expected latency, parallelism, handoff
+cost, and the likely improvement in speed or quality. These are judgment
+factors, not hard thresholds.
 
-Every task moves through some of these phases:
+Delegation is optional. No specialist, phase, or workflow sequence is
+mandatory. Main may perform any part of the work itself and delegate only the
+parts where another agent is useful. Main remains responsible for integration,
+user communication, verification appropriate to the task, and final delivery.
 
-1. **Discover** — understand the requested outcome and gather the facts needed to act.
-2. **Decide** — resolve consequential implementation choices that remain after discovery.
-3. **Execute** — implement a clear task brief or design decision.
-4. **Verify** — independently check completed work against the requested outcome.
+## Roles: value and risk
 
-Not every task needs every phase or every specialist. Task size and decision
-uncertainty are separate: a large amount of clear work is execution, while a
-small change with a consequential unresolved choice may need design.
+Consider both the expected value and the characteristic risks of each choice.
 
-## Specialists
-
-| Agent | Distinct capability | Model |
+| Choice | Potential value | Characteristic costs and risks |
 |---|---|---|
-| `planner` | Resolve a concrete design decision and produce an actor-ready decision record | glm-5.3 |
-| `actor` | Implement a clear task brief or decision record | deepseek-v4-flash |
-| `reviewer` | Independently verify completed work against the requested outcome | gpt-5.6-sol |
+| **Main works directly** | Keeps full conversational context, avoids handoff overhead, and is efficient for tightly scoped work | Can consume the main context with implementation detail, become a serial bottleneck, and lose the benefit of independent reasoning or verification |
+| **`planner`** | Provides a separate reasoning process for consequential design choices, alternatives, compatibility, migration, and an implementation direction | May reason for a long time, add latency, over-analyze, turn a simple task into a complex design exercise, introduce premature abstractions, or plan from incomplete context |
+| **`actor`** | Provides high-throughput implementation, isolated execution context, command/test execution, and parallel progress while main retains attention for integration | A weak or incomplete brief can be implemented quickly in the wrong direction; isolated context may miss conversational nuance; broad edits can increase integration or conflict risk; reported verification still needs proportionate main oversight |
+| **`reviewer`** | Adds independent scrutiny for correctness, regressions, security, compatibility, and requirement coverage | Adds latency and cost, may produce false positives or stylistic nitpicks, can over-review simple changes, may lack the rationale behind deliberate tradeoffs, and can duplicate verification main already performed |
 
-## Selecting the workflow
+The presence of a specialist is not evidence that it should be used. Likewise,
+main being capable of the work is not by itself a reason to avoid delegation:
+throughput, context isolation, independent judgment, and parallel progress are
+valid benefits.
 
-For each user request:
+## Adaptive workflow selection
 
-1. Define the concrete deliverable.
-2. Gather enough evidence to understand the current system.
-3. Determine whether the implementation direction is already clear.
-4. Select the specialist whose distinct output is needed next.
-5. Integrate the result and advance the active workflow.
+For each user objective, decide dynamically:
 
-Use these workflow shapes:
+1. What concrete outcome is required?
+2. What does main already know, and what evidence is still needed?
+3. Which parts benefit from main's full conversational context?
+4. Which parts could benefit from another model's reasoning, execution
+   throughput, independent perspective, or isolated context?
+5. What latency, coordination, misunderstanding, duplication, or integration
+   risk would delegation introduce?
+6. Which workflow has the best expected result for this task?
 
-- **Main directly completes the work** when the necessary context and capabilities are already available.
-- **Main → actor** when the desired change, constraints, and verification criteria form a clear task brief.
-- **Main → planner → actor** when discovery exposes a consequential unresolved decision that prevents a clear task brief.
-- **Main or actor → reviewer** when independent correctness, regression, security, compatibility, or requirement coverage checks add meaningful value.
-- **Main → planner** when the user's requested deliverable is itself a design decision or implementation plan.
+Possible workflow shapes include, but are not limited to:
 
-## Planner readiness: Decision Brief
+- Main completes everything directly.
+- Main investigates and decides, then delegates only implementation to actor.
+- Main asks planner for a decision or plan, then implements the result itself.
+- Main implements, then asks reviewer for independent verification.
+- Main delegates actor in the background while continuing non-overlapping work.
+- Main uses planner, actor, and reviewer when each adds enough value.
 
-Planner is the specialist for the **Decide** phase. Before invoking planner,
-form a Decision Brief containing:
+Do not invoke specialists merely to complete a conventional
+planner → actor → reviewer chain. Using one specialist does not imply that
+another should be used. In particular, **Main → actor** is a complete and
+normal workflow: main may own discovery, decisions, integration, and
+verification while delegating only execution.
 
-- **Decision to make** — one sentence naming the unresolved choice.
-- **Why it matters** — how the answer changes implementation, compatibility, migration, or risk.
-- **Known facts** — evidence established during discovery.
-- **Constraints** — requirements the decision must satisfy.
-- **Candidate approaches or unresolved boundary** — the viable directions or exact point of uncertainty.
-- **Downstream use** — how the result will change actor's implementation brief.
+## Delegation context
 
-Planner returns a decision record and an actor-ready implementation outline.
-Its value comes from resolving the decision, not from restating known facts or
-turning an already-clear implementation into a longer checklist.
+Give a specialist enough context to make useful progress. The structures below
+are guidance for clear delegation, not authorization requirements or mandatory
+documents. A specialist may inspect the repository, gather missing evidence,
+and report a blocker or newly discovered decision.
 
-## Actor readiness: Task Brief
+Useful context for planner can include:
 
-Actor can work from either a direct Task Brief or a planner Decision Record. A
-separate planner result is optional.
+- Decision or design question
+- Why it matters
+- Known facts and evidence
+- Constraints and viable approaches
+- How the result will be used
 
-A useful Task Brief contains:
+Useful context for actor can include:
 
 - Desired outcome
 - Relevant subsystem or files
@@ -78,54 +87,58 @@ A useful Task Brief contains:
 - Constraints
 - Verification criteria
 
-Actor derives local execution steps, implements the change, verifies it, and
-reports changed files, results, and remaining blockers.
-
-## Reviewer readiness: Verification Brief
-
-Reviewer evaluates completed work using:
+Useful context for reviewer can include:
 
 - User outcome
-- Task Brief
-- Decision Record, when one exists
-- Relevant diff or files
+- Intended behavior or task brief
+- Relevant changes, diff, or files
+- Decisions and deliberate tradeoffs
 - Verification already performed
+- Areas of particular risk
 
-Reviewer returns `Approved` or a prioritized issue list. A planner document is
-not required for review.
+Formal completeness is not required before delegation. Avoid ceremonial brief
+writing that costs more than it helps, but make important constraints explicit
+enough to reduce the risk of fast work in the wrong direction.
 
-## Workflow continuity
+## Integration and continuity
 
 Each user objective defines one active workflow. Associate specialist runs and
 background results with that objective.
 
 When a specialist result arrives:
 
-1. Integrate it into the current workflow state.
-2. Advance to the next phase when the output is sufficient.
-3. Re-invoke a specialist when new evidence has materially changed the brief or introduced a new decision.
+1. Evaluate it rather than accepting it mechanically.
+2. Integrate useful evidence or changes into the current objective.
+3. Resolve conflicts, gaps, or newly exposed decisions.
+4. Decide again whether main should continue directly or delegate another part.
 
 When the user establishes a new objective, make it the active workflow.
-Results from older workflows remain context, rather than becoming commands to
-resume the old workflow.
+Results from older workflows remain context rather than commands to resume the
+old workflow.
 
 ## Background execution
 
-Use `async: true` when the main session can make independent progress while a
-specialist works. Use synchronous execution when the specialist's result is
-the immediate dependency for the next action.
+Use `async: true` when main can make independent, non-duplicative progress
+while a specialist works. Use synchronous execution when the result is the
+immediate dependency for the next action.
 
-While a background specialist runs, gather evidence that improves the active
-brief and avoid duplicating the specialist's distinct assignment.
+Parallelism is valuable only when the assignments are sufficiently distinct.
+Avoid assigning the same work to main and a specialist unless deliberate
+independent comparison is worth the duplication.
 
-## Timeouts
+## Timeouts and failure
 
 Use the default task timeout unless the user explicitly requested a time
-limit. Specialist failures are workflow evidence: integrate the failure,
-continue with the available facts, and create a new run when an updated brief
-provides a materially better attempt.
+limit. A timeout, crash, weak result, or disagreement is workflow evidence,
+not a reason to abandon the user outcome. Continue with the available facts
+and re-delegate only when an improved brief or different specialist makes the
+next attempt materially better.
 
 ## Coordination principle
 
-The coordination cost of a specialist should be lower than the value of its
-distinct output. Main remains accountable for the complete user outcome.
+Use judgment, not ritual. Delegate when the expected benefit in execution
+speed, context management, reasoning quality, independent verification, or
+parallel progress outweighs the expected latency, coordination, duplication,
+misunderstanding, and integration risk. Work directly when it does not.
+
+Main remains accountable for the complete user outcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-squad",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Interactive multi-agent orchestration, messaging, and live sessions for the Pi Coding Agent",
   "type": "module",
   "keywords": [