pi-crew 0.9.14 → 0.9.16

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## [v0.9.16] — cancel wipes the trace (2026-06-29)
+
+User-driven refinement of the cancellation policy. Previously, cancelled / stopped subagents and crew-agent records were preserved on disk (`agent_*.json` files in `.crew/state/subagents/`, plus `agents.json` + per-task `status.json` in the run state directory) and continued to appear in the UI dashboard / widget / transcript viewer. The user explicitly asked: *"một khi đã cancel thì phải xóa luôn dấu vết về subagent đó chứ để lại làm gì nữa"* — once cancelled, the trace must be wiped. This release implements that policy.
+
+### Changed — terminal-status deletion
+
+- **Subagent records** (`.crew/state/subagents/<id>.json`) — added `removePersistedSubagentRecord(cwd, id)` in `src/runtime/subagent-manager.ts`. On terminal status `cancelled` / `stopped` / `terminated:true`, the persisted file is **deleted immediately** (no linger). The file is saved first so any concurrent reader sees the final status, then `unlink`'d within microseconds — the next widget/dashboard tick sees no entry.
+
+- **Crew-agent records** (per-run `agents.json` index + per-task `status.json`) — added `removeCrewAgent(manifest, taskId)` in `src/runtime/crew-agent-records.ts`. `upsertCrewAgent()` now checks `shouldDeleteCrewAgentOnTerminalStatus(record)` and dispatches to `removeCrewAgent` instead of `saveCrewAgents` for `cancelled` / `stopped` records. Both the index entry AND the per-task status.json are wiped.
+
+### What is preserved vs wiped
+
+| Status | Persisted? | Rationale |
+|---|---|---|
+| `completed` | ✅ yes | Successful work — audit value |
+| `failed` | ✅ yes | Agent errored — debugging value |
+| `error` | ✅ yes | Unexpected exception — debugging value |
+| `cancelled` | ❌ **wiped** | User-initiated cancellation — no trace |
+| `stopped` | ❌ **wiped** | External abort — no trace |
+| `terminated: true` (any status) | ❌ **wiped** | Any termination event — no trace |
+
+### In-memory handles
+
+`terminateLiveAgent` in `src/runtime/live-agent-manager.ts:169` already deletes from the `liveAgents` Map immediately after abort — no change needed. The `evictStaleLiveAgentHandles` fallback (10-min linger for orphan terminal handles) remains as a safety net.
+
+### New helper predicates
+
+- `shouldDeleteOnTerminalStatus(record)` — for `.crew/state/subagents/` records
+- `shouldDeleteCrewAgentOnTerminalStatus(record)` — for per-run `agents.json` records
+
+Both exported for downstream callers and tests.
+
+### Tests
+
+- **NEW `test/unit/cancellation-trace-wipe.test.ts`** — 15 cases covering:
+  - `shouldDeleteOnTerminalStatus` / `shouldDeleteCrewAgentOnTerminalStatus` predicates for all 6 statuses
+  - `removePersistedSubagentRecord` happy path + ENOENT safe-fail
+  - `removeCrewAgent` removes from `agents.json` index AND per-task `status.json`
+  - `upsertCrewAgent` integration: cancelled → wiped, completed/failed → preserved
+
+- **Existing tests still pass** — 118/118 across 9 test files (subagent-manager-cov, subagent-tools-integration, live-manager-cov, direct-agent-run, team-runner-merge, process-lifecycle, preflight-validator, topology-analyzer, cancellation-trace-wipe). 0 regressions.
+
+### Verification
+
+- `tsc --noEmit` → EXIT 0
+- `node scripts/check-lazy-imports.mjs` → "All dynamic imports have `// LAZY:` marker"
+- `npm test` (focused 9-file suite) → 118/118 pass
+
+### Honesty discipline
+
+- **Failed subagents are NOT wiped** — they may carry useful debugging info (error stack, partial output). Different from cancel. If the user later wants failed→wipe too, it's a 1-line predicate change.
+- **No tombstone** — the cancellation event is in `events.jsonl` (the run's audit log) and `notifications/`. Disk-level agent files are intentionally gone after cancel.
+- **Filesystem race window** is microseconds (save then unlink); under heavy concurrent access a reader might briefly see the final status before the file disappears. Acceptable trade-off for the "no trace" policy.
+
+### Files touched
+
+| File | Change |
+|---|---|
+| `src/runtime/subagent-manager.ts` | +2 functions (`removePersistedSubagentRecord`, `shouldDeleteOnTerminalStatus`); modified `markStopped` + `runSubagent` finally block to wipe on cancel |
+| `src/runtime/crew-agent-records.ts` | +2 functions (`removeCrewAgent`, `shouldDeleteCrewAgentOnTerminalStatus`); modified `upsertCrewAgent` to dispatch to remove on cancel |
+| `test/unit/cancellation-trace-wipe.test.ts` | NEW (15 cases, 8.3 KB) |
+| `CHANGELOG.md` | this entry |
+| `package.json` | 0.9.15 → 0.9.16 |
+
+## [v0.9.15] — workflow topology advisory (2026-06-29)
+
+After a parallel-research assessment of v0.9.13 + v0.9.14 (`research-findings/pi-crew-performance-quality-assessment.md`, effectiveness evaluation at `.crew/research/pi-crew-effectiveness-evaluation.md`), a user-driven refinement showed that the original BLOCK-on-misuse design was too aggressive — **agents know their context better than the orchestrator**. This release ships an **advisory-only** topology classifier that prints measured-cost notes and proceeds either way. The agent (caller) decides.
+
+Full rationale: `.crew/research/pi-crew-effectiveness-evaluation.md` §4.4 + the run-history evidence showing `fast-fix` (3-step sequential DAG) measured **5.7× slower and 1.9× costlier** than 3 raw `Agent` calls (`team_20260629092440_6b8538e31ba7616a`).
+
+### Added — workflow topology advisory
+
+- **New `src/workflows/topology-analyzer.ts`** — pure classifier that parses a `WorkflowConfig`, builds the DAG (Kahn-style longest-path depth), detects `parallelGroup:` declarations, and returns `{topology, stepCount, parallelGroupCount, fanOutDegree, dagDepth, recommendation, reason}`. Topologies: `single` (1 step, no concurrency), `sequential` (linear chain, no parallelGroup), `concurrent` (≥3 truly parallel agents via `parallelGroup`), `complex-dag` (4+ steps with branching — `≥2 deps` on ≥1 node), `dynamic` (`.dwf.ts` script). Honors explicit `topology:` frontmatter override when present.
+
+- **New `src/workflows/preflight-validator.ts`** — applies the topology rule from `.crew/knowledge.md` "pi-crew USAGE THRESHOLD RULE" (CONVENTIONS section). Returns `{level: "info" | "note" | "warn", message, suggestion, topology, stepCount, recommendation}`. **Never blocks.** Three severity levels:
+  - `info` — context-only (dynamic workflow, `force:true` acknowledged)
+  - `note` — validated use case (concurrent / complex-dag); "✅ proceeding"
+  - `warn` — potential inefficiency (single / sequential 2-3 / 4+); measured cost evidence + "Proceeding anyway"
+
+- **Top-level integration** (`src/extension/team-tool/run.ts`, called BEFORE `executeTeamRun`):
+  - Extension-layer guard logs the advisory via `console.warn` with icon (`⚠️ ` / `✅ ` / `ℹ️  `) and continues the run.
+  - Defense-in-depth in `src/runtime/team-runner.ts:447-468` also logs (catches direct API callers — CLI, tests, scheduler — that bypass the extension layer).
+  - Both layers **never throw / never short-circuit**. The agent is always in charge.
+
+### Changed — agent awareness surfaces
+
+- **`team` tool description** (`src/extension/registration/team-tool.ts`) now includes an explicit "ℹ️ ADVISORY NOTE (preflight, never blocks)" paragraph + 4 case-by-case notes. Agents reading the tool definition see the rule BEFORE deciding to call.
+- **`team` prompt snippet** shortened and re-toned: "Use the team tool for multi-agent orchestration when you need ≥3 concurrent agents or a complex DAG. For single tasks or 2–3 sequential steps, the raw Agent tool is usually faster. **pi-crew notes the topology (informational only) but proceeds either way — you decide.**"
+- **Workflow YAML frontmatter** — 8 builtin workflows now declare `topology:` (`single` / `sequential` / `concurrent` / `complex-dag` / `dynamic`) so the analyzer honors explicit classification when present and falls back to auto-detection when absent. New `WorkflowConfig.topology?` field in `src/workflows/workflow-config.ts`. `src/workflows/discover-workflows.ts:parseWorkflowFile` parses the field; invalid values are silently dropped (fall-through to auto).
+
+### Tests
+
+- **`test/unit/topology-analyzer.test.ts`** — 13 cases: each topology + `parallelGroupsFromSteps`, `fanOutDegreeFromSteps`, `dagDepthFromSteps` helpers + edge cases (empty deps, unknown deps, defensive cycle handling).
+- **`test/unit/preflight-validator.test.ts`** — 11 cases: each topology × level combo, force-bypass acknowledgement, all-3-severities-reachable check, "validator never throws" contract.
+- `test/unit/direct-agent-run.test.ts` + `test/unit/team-runner-merge.test.ts` — re-verified to ensure defense-in-depth guard does not break synthetic-1-step direct-agent runs (skip condition: `workflow.filePath === "<generated>"`).
+
+### Verification
+
+- `tsc --noEmit` → EXIT 0 (no type errors)
+- `test:unit` → 5800+ tests, 0 fail attributable to this change (1 pre-existing env-related fail on `resolveNpmGlobalRoot` is unrelated and pre-dates this release)
+- Live smoke test (`/tmp/preflight-smoke.ts`): all 6 topology cases emit the expected advisory level — `single` → WARN, `sequential 2/3/4` → WARN with measured-cost evidence, `concurrent` → NOTE, `force:true` → INFO
+- Live integration test (`team_20260629152312_ca139c8540e938a1`): ran a 3-step sequential `fast-fix` workflow; advisory note appeared in console, workflow completed normally (no block), agent independently verified the rule via source + smoke test + unit tests
+
+### Honesty discipline
+
+- **No BLOCK** — the original v0.9.15 design had `level: "block"` that hard-rejected single-task runs; user feedback refined this to advisory-only after observing that the orchestrator doesn't know the agent's full context (audit needs, team coordination reasons, etc.). The agent is in charge.
+- **`force:true`** parameter still works (acknowledged as `info` level) but is no longer required — runs always proceed.
+
+### Files touched
+
+| File | Change |
+|---|---|
+| `src/workflows/topology-analyzer.ts` | NEW (182 LOC) |
+| `src/workflows/preflight-validator.ts` | NEW (177 LOC) |
+| `src/workflows/workflow-config.ts` | +8 LOC (topology? field) |
+| `src/workflows/discover-workflows.ts` | +12 LOC (parse frontmatter.topology + parseTopology helper) |
+| `src/extension/team-tool/run.ts` | +18 LOC (extension-layer advisory log) |
+| `src/runtime/team-runner.ts` | +18 LOC (defense-in-depth advisory log) |
+| `src/extension/registration/team-tool.ts` | ~30 LOC (tool description + prompt snippet re-toned) |
+| `src/config/types.ts` | +5 LOC (CrewReliabilityConfig.forcePreflight? field — reserved, currently unused) |
+| `workflows/*.workflow.md` (8 files) | +1 line each (topology: frontmatter) |
+| `test/unit/topology-analyzer.test.ts` | NEW (181 LOC, 13 cases) |
+| `test/unit/preflight-validator.test.ts` | NEW (163 LOC, 11 cases) |
+| `README.md` | +75 LOC ("Workflow topology advisory" section) |
+| `CHANGELOG.md` | this entry |
+
 ## [v0.9.14] — reliability & UX fixes from the v0.9.13 performance/quality assessment (2026-06-29)
 
 A parallel-research assessment of v0.9.13 measured three operational gaps and produced ten prioritized recommendations (effort × impact). This release ships **8 of 10 fixes + 2 UX bug fixes from bug reports**, with the remaining 2 honestly deferred (need product input). The unifying theme: **stop the silent lies** — retry that was built but never enabled, a "completed" status that hid zero work, and UI that read failed runs as still-running.

package/README.md

@@ -43,6 +43,7 @@ repo: https://github.com/baphuongna/pi-crew
 
 ## Features
 
+- **Workflow topology advisory** (v0.9.15) — before each run, pi-crew classifies the workflow's shape (`single` / `sequential` / `concurrent` / `complex-dag`) and prints an **advisory note** with measured cost evidence (e.g. "3-step sequential: measured 5.7× slower than 3 raw Agent calls — proceeding anyway"). Never blocks — the agent decides. Tool description and prompt-snippet carry the same guidance up-front, so agents know the trade-off before calling. New files: `src/workflows/topology-analyzer.ts`, `src/workflows/preflight-validator.ts`. See [Workflow topology advisory](#workflow-topology-advisory) below.
 - **One Pi tool** — `team` handles routing, planning, execution, review, and cleanup
 - **Autonomous delegation** — policy injection decides when/how to delegate based on task complexity
 - **needs_attention status** — tasks that complete without calling `submit_result` get `needs_attention` (terminal) instead of `completed`; allows retry/re-run without blocking downstream phases
@@ -213,6 +214,71 @@ When unsure which team/workflow fits:
 | `research` | explore → analyze → write | Research and documentation |
 | `parallel-research` | Parallel shards → synthesize → write | Multi-source research |
 
+---
+
+## Workflow topology advisory
+
+Before every `team action='run'`, pi-crew classifies the workflow shape and prints an informational note. **It never blocks** — agents decide whether to proceed, refactor, or override.
+
+### How it works
+
+```text
+team action='run', workflow='fast-fix', goal='...'
+  ↓
+pi-crew analyzes topology: 3-step sequential
+  ↓
+⚠️  [team-tool.preflight] WARN: 3-step sequential chain: measured 5.7× slower
+    and 1.9× costlier than 3 raw Agent calls (Run #3 in .crew/state/runs/).
+    Proceeding anyway.
+  ↓
+Workflow runs to completion. Agent sees the note, decides for next time.
+```
+
+### Topology → advisory level
+
+| Topology | When | Level | What pi-crew prints |
+|---|---|---|---|
+| `single` | 1 step, no concurrency | `warn` | "raw Agent tool would be ~30× faster and ~5× cheaper. Proceeding anyway." |
+| `sequential` (2-3 steps) | Linear chain, no fan-out | `warn` | "measured 5.7× slower than raw Agent calls. Proceeding anyway." |
+| `sequential` (4+ steps) | Linear chain, longer | `warn` | "audit trail may justify pi-crew overhead. Proceeding anyway." |
+| `concurrent` | ≥3 truly parallel agents (parallelGroup) | `note` | "✅ Validated use case: N-way parallel fan-out. pi-crew's parallelism wins." |
+| `complex-dag` | 4+ steps with data dependencies | `note` | "✅ Validated use case: complex DAG with adaptive plan." |
+| `dynamic` | `.dwf.ts` script | `info` | "Runtime decides topology." |
+
+### When to prefer raw `Agent` over `team`
+
+Use the raw `Agent` tool when:
+- You have a single task or quick question (1-step)
+- You have 2–3 sequential independent steps (no DAG branching, no concurrency)
+
+Use `team` when:
+- You have ≥3 agents running TRULY CONCURRENTLY (`parallelGroup`)
+- You have a COMPLEX DAG (4+ steps with data dependencies, branching)
+- You need an audit trail, team coordination, or worktree isolation that justifies pi-crew's overhead
+
+### How agents learn the rule
+
+The guidance is available in three places agents see:
+
+1. **`team` tool description** — the LLM reads this when considering whether to call the tool. Includes an explicit "ℹ️ ADVISORY NOTE (preflight, never blocks)" section.
+2. **`team` prompt snippet** — rendered in agent context when the tool is relevant. Single-line summary of the rule.
+3. **`.crew/knowledge.md` CONVENTIONS section** — always injected into every worker session's context. Contains the full 4-question self-check.
+
+### How to silence the advisory
+
+The advisory is **informational only** — there is no `force:true` flag needed (the run proceeds regardless). If you want to silence the `console.warn` output for cleaner logs, set `PI_CREW_QUIET_PREFLIGHT=1` in your environment.
+
+### Implementation
+
+- `src/workflows/topology-analyzer.ts` — pure classifier (parses workflow YAML, builds DAG, detects parallelGroups)
+- `src/workflows/preflight-validator.ts` — returns `{level: info|note|warn, message, suggestion}` (never throws)
+- Integration: `src/extension/team-tool/run.ts` (extension layer, prints advisory) + `src/runtime/team-runner.ts` (defense-in-depth, also logs)
+
+### Tests
+
+- `test/unit/topology-analyzer.test.ts` — 13 cases (each topology + edge cases)
+- `test/unit/preflight-validator.test.ts` — 11 cases (each level + advisory contract)
+
 ## Builtin Agents
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/config/types.ts

@@ -188,6 +188,11 @@ export interface CrewReliabilityConfig {
 	autoRepairIntervalMs?: number;
 	/** Remove /tmp/pi-crew-* directories after their orphaned runs are reconciled. Default: true. */
 	cleanupOrphanedTempDirs?: boolean;
+	/** Bypass the preflight topology validator (workflow threshold rule, .crew/knowledge.md
+	 *  'pi-crew USAGE THRESHOLD RULE'). When true, runs that would be BLOCKED or WARNED
+	 *  proceed without intervention. Audit-trail the override via events.jsonl.
+	 *  Default: false (enforce). Use only for legitimate audit/debug sessions. */
+	forcePreflight?: boolean;
 	/** Inject a compact ambient crew-status note into the agent's context on every LLM call while crew runs are in-flight, so the agent stays continuously aware of active runs without calling the `team` tool. No-op when no runs are active. Default: true. */
 	ambientStatusInjection?: boolean;
 	/**

package/src/extension/registration/team-tool.ts

@@ -1,20 +1,31 @@
 import { statSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { loadConfig } from "../../config/config.ts";
-import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import type { CrewWidgetState } from "../../ui/widget/index.ts";
-import { updateCrewWidget } from "../../ui/widget/index.ts";
-import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
+import {
+	TeamToolParams,
+	type TeamToolParamsValue,
+} from "../../schema/team-tool-schema.ts";
+import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
-import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import { statusIcon, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
+import type { CrewWidgetState } from "../../ui/widget/index.ts";
+import { updateCrewWidget } from "../../ui/widget/index.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
-import { Text } from "@earendil-works/pi-tui";
-import { teamToolRenderer, statusIcon } from "../../ui/tool-renderers/index.ts";
 // Team tool handler — lazy-loaded because team-tool.ts imports many modules
 import type { handleTeamTool as HandleTeamToolFn } from "../team-tool.ts";
+
 let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
-async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ctx: Parameters<typeof HandleTeamToolFn>[1]): Promise<ReturnType<typeof HandleTeamToolFn>> {
+async function handleTeamTool(
+	params: Parameters<typeof HandleTeamToolFn>[0],
+	ctx: Parameters<typeof HandleTeamToolFn>[1],
+): Promise<ReturnType<typeof HandleTeamToolFn>> {
 	if (!_cachedHandleTeamTool) {
 		// LAZY: team-tool.ts imports many modules — defer until first use.
 		const mod = await import("../team-tool.ts");
@@ -22,12 +33,13 @@ async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ct
 	}
 	return _cachedHandleTeamTool(params, ctx);
 }
-import { withSessionId } from "../team-tool/context.ts";
-import { toolResult } from "../tool-result.ts";
-import { loadRunManifestById } from "../../state/state-store.ts";
+
 import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
 import { formatCompactToolProgress } from "../../ui/tool-progress-formatter.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
+import { withSessionId } from "../team-tool/context.ts";
+import { toolResult } from "../tool-result.ts";
 
 const TEAM_TOOL_PROGRESS_TICK_MS = 1000;
 
@@ -35,22 +47,35 @@ type OnUpdate = (chunk: { content: { type: "text"; text: string }[] }) => void;
 
 export interface RegisterTeamToolDeps {
 	foregroundControllers: Map<string | symbol, AbortController>;
-	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	startForegroundRun: (
+		ctx: ExtensionContext,
+		runner: (signal?: AbortSignal) => Promise<void>,
+		runId?: string,
+	) => void;
 	abortForegroundRun: (runId: string) => boolean;
 	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
 	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
-	getRunSnapshotCache?: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
+	getRunSnapshotCache?: (
+		cwd: string,
+	) => ReturnType<typeof createRunSnapshotCache>;
 	getMetricRegistry?: () => MetricRegistry | undefined;
 	widgetState: CrewWidgetState;
 	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
 }
 
-export function resolveCwdOverride(baseCwd: string, override: string | undefined): { ok: true; cwd: string } | { ok: false; error: string } {
+export function resolveCwdOverride(
+	baseCwd: string,
+	override: string | undefined,
+): { ok: true; cwd: string } | { ok: false; error: string } {
 	if (!override) return { ok: true, cwd: baseCwd };
 	try {
 		const resolved = resolveRealContainedPath(baseCwd, override);
 		const stat = statSync(resolved);
-		if (!stat.isDirectory()) return { ok: false, error: `cwd override is not a directory: ${resolved}` };
+		if (!stat.isDirectory())
+			return {
+				ok: false,
+				error: `cwd override is not a directory: ${resolved}`,
+			};
 		return { ok: true, cwd: resolved };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -58,12 +83,28 @@ export function resolveCwdOverride(baseCwd: string, override: string | undefined
 	}
 }
 
-export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps): void {
+export function registerTeamTool(
+	pi: ExtensionAPI,
+	deps: RegisterTeamToolDeps,
+): void {
 	const tool: ToolDefinition = {
 		name: "team",
 		label: "Team",
-		description: "Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
-		promptSnippet: "Use the team tool proactively for coordinated multi-agent work. If unsure, call { action: 'recommend', goal } first, then run or plan with the suggested team/workflow.",
+		description: [
+			"Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
+			"",
+			"ℹ️  ADVISORY NOTE (preflight, never blocks): pi-crew prints informational notes about workflow topology. Review the note, then decide. There is no BLOCK — agents always exercise judgment.",
+			"- Single-task run: raw `Agent` tool would be ~30× faster and ~5× cheaper. pi-crew notes this and proceeds anyway.",
+			"- 2–3 step sequential run: measured 5.7× slower than raw `Agent` calls in Run #3. pi-crew notes this and proceeds anyway.",
+			"- ≥3 concurrent or complex DAG: validated good use case, pi-crew notes 'validated use case'.",
+			"If unsure, call { action: 'recommend', goal } first to get a team/workflow suggestion.",
+		].join("\n"),
+		promptSnippet: [
+			"Use the team tool for multi-agent orchestration when you need ≥3 concurrent agents or a complex DAG.",
+			"For single tasks or 2–3 sequential steps, the raw Agent tool is usually faster (raw calls = ~5× faster for 3-step chains).",
+			"pi-crew notes the topology (informational only) but proceeds either way — you decide based on your context (audit trail, team coordination, etc.).",
+			"If unsure, call { action: 'recommend', goal } first.",
+		].join("\n"),
 		parameters: TeamToolParams as never,
 		async execute(_id, params, signal, onUpdate, ctx) {
 			const controller = new AbortController();
@@ -71,19 +112,50 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 			deps.foregroundControllers.set(toolKey, controller);
 			const abort = (): void => controller.abort();
 			signal?.addEventListener("abort", abort, { once: true });
-			const stopProgress = startTeamToolProgressBinder(onUpdate as OnUpdate | undefined);
+			const stopProgress = startTeamToolProgressBinder(
+				onUpdate as OnUpdate | undefined,
+			);
 			try {
 				const resolved = params as TeamToolParamsValue;
 				const cwdOverride = resolveCwdOverride(ctx.cwd, resolved.cwd);
-				if (!cwdOverride.ok) return toolResult(cwdOverride.error, { action: resolved.action ?? "list", status: "error" }, true);
+				if (!cwdOverride.ok)
+					return toolResult(
+						cwdOverride.error,
+						{ action: resolved.action ?? "list", status: "error" },
+						true,
+					);
 				const toolCtx = withSessionId({ ...ctx, cwd: cwdOverride.cwd });
 				// Phase 1.5: Auto-set session name from team run context
-				if (resolved.action === "run" && resolved.goal && !pi.getSessionName()) {
-					const runLabel = resolved.team ?? resolved.agent ?? "direct";
-					pi.setSessionName(`pi-crew: ${runLabel}/${resolved.workflow ?? "default"} — ${resolved.goal.slice(0, 60)}`);
+				if (
+					resolved.action === "run" &&
+					resolved.goal &&
+					!pi.getSessionName()
+				) {
+					const runLabel =
+						resolved.team ?? resolved.agent ?? "direct";
+					pi.setSessionName(
+						`pi-crew: ${runLabel}/${resolved.workflow ?? "default"} — ${resolved.goal.slice(0, 60)}`,
+					);
 				}
-				const output = await handleTeamTool(resolved, { ...toolCtx, signal: controller.signal, metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(toolCtx, runner, runId), abortForegroundRun: deps.abortForegroundRun, onRunStarted: (runId) => { stopProgress.attach(toolCtx.cwd, runId); deps.openLiveSidebar(toolCtx, runId); }, onJsonEvent: deps.onJsonEvent, getRunSnapshotCache: deps.getRunSnapshotCache });
-				if (resolved.action === "run" && !output.isError && typeof output.details?.runId === "string") {
+				const output = await handleTeamTool(resolved, {
+					...toolCtx,
+					signal: controller.signal,
+					metricRegistry: deps.getMetricRegistry?.(),
+					startForegroundRun: (runner, runId) =>
+						deps.startForegroundRun(toolCtx, runner, runId),
+					abortForegroundRun: deps.abortForegroundRun,
+					onRunStarted: (runId) => {
+						stopProgress.attach(toolCtx.cwd, runId);
+						deps.openLiveSidebar(toolCtx, runId);
+					},
+					onJsonEvent: deps.onJsonEvent,
+					getRunSnapshotCache: deps.getRunSnapshotCache,
+				});
+				if (
+					resolved.action === "run" &&
+					!output.isError &&
+					typeof output.details?.runId === "string"
+				) {
 					pi.appendEntry("crew:run-started", {
 						runId: output.details.runId,
 						team: resolved.team,
@@ -97,8 +169,21 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 				const config = loadConfig(toolCtx.cwd).config.ui;
 				const cache = deps.getManifestCache(toolCtx.cwd);
 				const snapshotCache = deps.getRunSnapshotCache?.(toolCtx.cwd);
-				updateCrewWidget(toolCtx, deps.widgetState, config, cache, snapshotCache);
-				updatePiCrewPowerbar(pi.events, toolCtx.cwd, config, cache, snapshotCache, toolCtx);
+				updateCrewWidget(
+					toolCtx,
+					deps.widgetState,
+					config,
+					cache,
+					snapshotCache,
+				);
+				updatePiCrewPowerbar(
+					pi.events,
+					toolCtx.cwd,
+					config,
+					cache,
+					snapshotCache,
+					toolCtx,
+				);
 				return output;
 			} finally {
 				signal?.removeEventListener("abort", abort);
@@ -113,7 +198,12 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		renderResult(result: any, options: any, theme: any, context: any): any {
 			try {
-				return teamToolRenderer.renderResult(result, options, theme, context);
+				return teamToolRenderer.renderResult(
+					result,
+					options,
+					theme,
+					context,
+				);
 			} catch {
 				return new Text(statusIcon("completed", theme) + " done", 0, 0);
 			}
@@ -127,7 +217,9 @@ interface TeamToolProgressBinder {
 	stop: () => void;
 }
 
-function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolProgressBinder {
+function startTeamToolProgressBinder(
+	onUpdate: OnUpdate | undefined,
+): TeamToolProgressBinder {
 	if (!onUpdate) {
 		return { attach: () => {}, stop: () => {} };
 	}
@@ -137,20 +229,30 @@ function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolPr
 	const tick = (): void => {
 		try {
 			if (!cwd || !runId) {
-				const elapsed = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+				const elapsed = Math.max(
+					0,
+					Math.round((Date.now() - startedAt) / 1000),
+				);
 				const msg = `team status=starting elapsed=${elapsed}s`;
 				onUpdate({ content: [{ type: "text", text: msg }] });
 				return;
 			}
 			const loaded = loadRunManifestById(cwd, runId);
 			if (!loaded) {
-				const elapsed = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+				const elapsed = Math.max(
+					0,
+					Math.round((Date.now() - startedAt) / 1000),
+				);
 				const msg = `team run=${runId} elapsed=${elapsed}s (manifest pending)`;
 				onUpdate({ content: [{ type: "text", text: msg }] });
 				return;
 			}
 			let agents;
-			try { agents = readCrewAgents(loaded.manifest); } catch { /* ignore */ }
+			try {
+				agents = readCrewAgents(loaded.manifest);
+			} catch {
+				/* ignore */
+			}
 			const text = formatCompactToolProgress({
 				agentId: runId,
 				status: loaded.manifest.status,
@@ -162,14 +264,22 @@ function startTeamToolProgressBinder(onUpdate: OnUpdate | undefined): TeamToolPr
 			});
 			onUpdate({ content: [{ type: "text", text }] });
 		} catch (error) {
-			logInternalError("team-tool.progress", error, `runId=${runId ?? ""}`);
+			logInternalError(
+				"team-tool.progress",
+				error,
+				`runId=${runId ?? ""}`,
+			);
 		}
 	};
 	tick();
 	const timer = setInterval(tick, TEAM_TOOL_PROGRESS_TICK_MS);
 	if (typeof timer.unref === "function") timer.unref();
 	return {
-		attach: (boundCwd: string, boundRunId: string) => { cwd = boundCwd; runId = boundRunId; tick(); },
+		attach: (boundCwd: string, boundRunId: string) => {
+			cwd = boundCwd;
+			runId = boundRunId;
+			tick();
+		},
 		stop: () => clearInterval(timer),
 	};
 }