pi-crew 0.1.46 → 0.1.49

package/skills/ui-render-performance/SKILL.md

@@ -1,39 +1,39 @@
----
-name: ui-render-performance
-description: Non-blocking Pi TUI render workflow. Use when changing widgets, powerbar/statusbar segments, dashboard panes, overlays, snapshot caches, or live UI refresh behavior.
----
-
-# ui-render-performance
-
-Use this skill for Pi/pi-crew TUI work.
-
-## Source patterns distilled
-
-- Pi TUI is synchronous immediate-mode/string rendering: `source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
-- Pi extension examples use event-driven state updates, not render-time loading.
-- pi-crew UI: `src/extension/register.ts`, `src/ui/run-dashboard.ts`, `src/ui/run-snapshot-cache.ts`, `src/ui/crew-widget.ts`, `src/ui/powerbar-publisher.ts`, `src/ui/render-scheduler.ts`
-
-## Rules
-
-- Treat every `render(width)` and widget/powerbar update as a hot synchronous path.
-- Render from in-memory snapshots only. Preload config, manifests, snapshots, agents, and mailbox counts asynchronously.
-- Use `RenderScheduler.schedule()` to coalesce renders; avoid direct repeated rendering.
-- Prefer `snapshotCache.get(runId)` in render paths. If a sync fallback is unavoidable, classify it as first-load/rare and document why.
-- Keep dashboard panes pure: accept a snapshot/model and format strings; do not call `fs.readFileSync`, `fs.readdirSync`, `fs.statSync`, or network APIs from pane render methods.
-- On session switch, cancel timers and ensure in-flight async preloads cannot update stale session UI.
-- Watch TTL interactions: a preload interval shorter than cache TTL prevents render-time refresh gaps.
-
-## Anti-patterns
-
-- Do not call `loadConfig()`, `manifestCache.list()`, or `refreshIfStale()` repeatedly inside `renderTick()` unless backed by preloaded frame data.
-- Do not do large JSON parsing or directory scans inside widget render/update functions.
-- Do not show stale health warnings for completed/cancelled/failed runs.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/unit/run-snapshot-cache.test.ts test/unit/crew-widget.test.ts test/unit/powerbar-publisher.test.ts test/unit/run-dashboard.test.ts
-npm test
-```
+---
+name: ui-render-performance
+description: Non-blocking Pi TUI render workflow. Use when changing widgets, powerbar/statusbar segments, dashboard panes, overlays, snapshot caches, or live UI refresh behavior.
+---
+
+# ui-render-performance
+
+Use this skill for Pi/pi-crew TUI work.
+
+## Source patterns distilled
+
+- Pi TUI is synchronous immediate-mode/string rendering: `source/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts`
+- Pi extension examples use event-driven state updates, not render-time loading.
+- pi-crew UI: `src/extension/register.ts`, `src/ui/run-dashboard.ts`, `src/ui/run-snapshot-cache.ts`, `src/ui/crew-widget.ts`, `src/ui/powerbar-publisher.ts`, `src/ui/render-scheduler.ts`
+
+## Rules
+
+- Treat every `render(width)` and widget/powerbar update as a hot synchronous path.
+- Render from in-memory snapshots only. Preload config, manifests, snapshots, agents, and mailbox counts asynchronously.
+- Use `RenderScheduler.schedule()` to coalesce renders; avoid direct repeated rendering.
+- Prefer `snapshotCache.get(runId)` in render paths. If a sync fallback is unavoidable, classify it as first-load/rare and document why.
+- Keep dashboard panes pure: accept a snapshot/model and format strings; do not call `fs.readFileSync`, `fs.readdirSync`, `fs.statSync`, or network APIs from pane render methods.
+- On session switch, cancel timers and ensure in-flight async preloads cannot update stale session UI.
+- Watch TTL interactions: a preload interval shorter than cache TTL prevents render-time refresh gaps.
+
+## Anti-patterns
+
+- Do not call `loadConfig()`, `manifestCache.list()`, or `refreshIfStale()` repeatedly inside `renderTick()` unless backed by preloaded frame data.
+- Do not do large JSON parsing or directory scans inside widget render/update functions.
+- Do not show stale health warnings for completed/cancelled/failed runs.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/run-snapshot-cache.test.ts test/unit/crew-widget.test.ts test/unit/powerbar-publisher.test.ts test/unit/run-dashboard.test.ts
+npm test
+```

package/skills/verification-before-done/SKILL.md

@@ -1,57 +1,57 @@
----
-name: verification-before-done
-description: Use when about to claim work is complete, fixed, passing, reviewed, committed, or ready to hand off.
----
-
-# verification-before-done
-
-Core principle: evidence before claims. A worker report, green-looking log, or previous run is not fresh verification.
-
-Distilled from detailed reads of agent-skill patterns for verification-before-completion, TDD, review reception, and QA workflows.
-
-## Gate Function
-
-Before any completion claim:
-
-1. Identify the command or inspection that proves the claim.
-2. Run the full command fresh, or explicitly state why a command cannot be run.
-3. Read the output, including exit code and failure counts.
-4. Compare the output to the claim.
-5. Report the claim only with the evidence.
-
-## Claim-to-Evidence Table
-
-| Claim | Requires | Not sufficient |
-|---|---|---|
-| Tests pass | Fresh test output with zero failures | Prior run, “should pass” |
-| Typecheck passes | Typecheck command exit 0 | Lint or targeted tests only |
-| Bug fixed | Original symptom/regression test passes | Code changed |
-| Requirements met | Checklist against request/plan | Generic test success |
-| Agent completed | Worker output plus artifact/diff/state inspection | Worker says DONE |
-| Safe to commit | Relevant checks pass and status reviewed | Partial local confidence |
-
-## Verification Ladder
-
-Choose the smallest reliable gate, then escalate when risk requires it:
-
-1. Read-only inspection for plans/reviews.
-2. Targeted unit test for touched behavior.
-3. Typecheck for TypeScript/schema/API changes.
-4. Integration test for runtime, subprocess, state, filesystem, UI, config, or session behavior.
-5. Full suite before commit/release or broad changes.
-6. Real Pi smoke only when safe and needed.
-
-## Done Report
-
-Include:
-
-- changed files or read-only status;
-- commands run and pass/fail result;
-- artifacts, run IDs, logs, or state paths inspected;
-- behavior actually verified;
-- skipped checks and why;
-- risks and rollback notes.
-
-## Red Flags
-
-Stop before saying done if you are using words like “should”, “probably”, “looks”, “seems”, “I think”, or if you are trusting an agent report without checking evidence.
+---
+name: verification-before-done
+description: Use when about to claim work is complete, fixed, passing, reviewed, committed, or ready to hand off.
+---
+
+# verification-before-done
+
+Core principle: evidence before claims. A worker report, green-looking log, or previous run is not fresh verification.
+
+Distilled from detailed reads of agent-skill patterns for verification-before-completion, TDD, review reception, and QA workflows.
+
+## Gate Function
+
+Before any completion claim:
+
+1. Identify the command or inspection that proves the claim.
+2. Run the full command fresh, or explicitly state why a command cannot be run.
+3. Read the output, including exit code and failure counts.
+4. Compare the output to the claim.
+5. Report the claim only with the evidence.
+
+## Claim-to-Evidence Table
+
+| Claim | Requires | Not sufficient |
+|---|---|---|
+| Tests pass | Fresh test output with zero failures | Prior run, “should pass” |
+| Typecheck passes | Typecheck command exit 0 | Lint or targeted tests only |
+| Bug fixed | Original symptom/regression test passes | Code changed |
+| Requirements met | Checklist against request/plan | Generic test success |
+| Agent completed | Worker output plus artifact/diff/state inspection | Worker says DONE |
+| Safe to commit | Relevant checks pass and status reviewed | Partial local confidence |
+
+## Verification Ladder
+
+Choose the smallest reliable gate, then escalate when risk requires it:
+
+1. Read-only inspection for plans/reviews.
+2. Targeted unit test for touched behavior.
+3. Typecheck for TypeScript/schema/API changes.
+4. Integration test for runtime, subprocess, state, filesystem, UI, config, or session behavior.
+5. Full suite before commit/release or broad changes.
+6. Real Pi smoke only when safe and needed.
+
+## Done Report
+
+Include:
+
+- changed files or read-only status;
+- commands run and pass/fail result;
+- artifacts, run IDs, logs, or state paths inspected;
+- behavior actually verified;
+- skipped checks and why;
+- risks and rollback notes.
+
+## Red Flags
+
+Stop before saying done if you are using words like “should”, “probably”, “looks”, “seems”, “I think”, or if you are trusting an agent report without checking evidence.

package/skills/worktree-isolation/SKILL.md

@@ -1,39 +1,39 @@
----
-name: worktree-isolation
-description: Conflict-safe git worktree workflow. Use when running parallel implementation workers, isolating risky edits, or cleaning up task worktrees.
----
-
-# worktree-isolation
-
-Use this skill for worktree-based execution or cleanup.
-
-## Source patterns distilled
-
-- pi-subagents worktree runner and cleanup patterns
-- pi-crew worktrees: `src/worktree/worktree-manager.ts`, `src/worktree/cleanup.ts`, `src/worktree/branch-freshness.ts`
-- Team runner workspace mode: `src/runtime/team-runner.ts`, workflow/team resource fields
-
-## Rules
-
-- Use worktree mode for parallel or risky code-changing tasks when the repository is clean enough and merge ownership is clear.
-- Assign one owner per file/symbol/migration path to avoid conflict-heavy merges.
-- Name branches/worktrees deterministically from run/task IDs; avoid user-controlled path fragments without sanitization.
-- Before cleanup, check dirty state. Preserve dirty worktrees unless `force` is explicitly set.
-- Record worktree paths and branch metadata in artifacts/events so the operator can inspect or recover.
-- Do not run destructive git operations without explicit confirmation and evidence of target path containment.
-
-## Anti-patterns
-
-- Parallel editing the same file in multiple worktrees without a merge plan.
-- Force-removing dirty worktrees by default.
-- Reusing stale worktrees after the base branch has moved without freshness checks.
-- Storing worktrees outside the intended contained workspace root.
-
-## Verification
-
-```bash
-cd pi-crew
-npx tsc --noEmit
-node --experimental-strip-types --test test/integration/worktree-mode.test.ts test/unit/run-index.test.ts
-npm test
-```
+---
+name: worktree-isolation
+description: Conflict-safe git worktree workflow. Use when running parallel implementation workers, isolating risky edits, or cleaning up task worktrees.
+---
+
+# worktree-isolation
+
+Use this skill for worktree-based execution or cleanup.
+
+## Source patterns distilled
+
+- pi-subagents worktree runner and cleanup patterns
+- pi-crew worktrees: `src/worktree/worktree-manager.ts`, `src/worktree/cleanup.ts`, `src/worktree/branch-freshness.ts`
+- Team runner workspace mode: `src/runtime/team-runner.ts`, workflow/team resource fields
+
+## Rules
+
+- Use worktree mode for parallel or risky code-changing tasks when the repository is clean enough and merge ownership is clear.
+- Assign one owner per file/symbol/migration path to avoid conflict-heavy merges.
+- Name branches/worktrees deterministically from run/task IDs; avoid user-controlled path fragments without sanitization.
+- Before cleanup, check dirty state. Preserve dirty worktrees unless `force` is explicitly set.
+- Record worktree paths and branch metadata in artifacts/events so the operator can inspect or recover.
+- Do not run destructive git operations without explicit confirmation and evidence of target path containment.
+
+## Anti-patterns
+
+- Parallel editing the same file in multiple worktrees without a merge plan.
+- Force-removing dirty worktrees by default.
+- Reusing stale worktrees after the base branch has moved without freshness checks.
+- Storing worktrees outside the intended contained workspace root.
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/integration/worktree-mode.test.ts test/unit/run-index.test.ts
+npm test
+```

package/src/agents/agent-config.ts

@@ -25,6 +25,12 @@ export interface AgentConfig {
 	inheritSkills?: boolean;
 	routing?: RoutingMetadata;
 	memory?: "user" | "project" | "local";
+	/** Tool loading strategy: "essential" = always load all tools, "lean" = only load tools in defaultTools list */
+	loadMode?: "essential" | "lean";
+	/** Explicit tool list when loadMode is "lean". null means all available tools. */
+	defaultTools?: string[] | null;
+	/** Context mode: "fresh" = clean start, "fork" = inherit parent session context */
+	contextMode?: "fresh" | "fork";
 	disabled?: boolean;
 	override?: { source: "config"; path: string };
 }

package/src/agents/agent-search.ts

@@ -0,0 +1,98 @@
+import type { AgentConfig } from "./agent-config.ts";
+
+// ─── BM25 Agent Search ──────────────────────────────────────────────────────
+// Lightweight BM25 search over agent descriptors for task-to-agent matching.
+// Based on the same BM25 algorithm used in oh-my-pi's tool-index.ts.
+
+export interface AgentSearchDocument {
+	agent: AgentConfig;
+	termFrequencies: Map<string, number>;
+	length: number;
+}
+
+export interface AgentSearchIndex {
+	documents: AgentSearchDocument[];
+	averageLength: number;
+	documentFrequencies: Map<string, number>;
+}
+
+export interface AgentSearchResult {
+	agent: AgentConfig;
+	score: number;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const FIELD_WEIGHTS = {
+	name: 6,
+	description: 2,
+	role: 3,
+} as const;
+
+function tokenize(value: string): string[] {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.toLowerCase()
+		.trim()
+		.split(/\s+/)
+		.filter((token) => token.length > 0);
+}
+
+function addWeightedTokens(termFrequencies: Map<string, number>, value: string | undefined, weight: number): void {
+	if (!value) return;
+	for (const token of tokenize(value)) {
+		termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
+	}
+}
+
+function buildAgentSearchDocument(agent: AgentConfig): AgentSearchDocument {
+	const termFrequencies = new Map<string, number>();
+	addWeightedTokens(termFrequencies, agent.name, FIELD_WEIGHTS.name);
+	addWeightedTokens(termFrequencies, agent.description, FIELD_WEIGHTS.description);
+	// Role from agent name heuristic
+	const roleHint = agent.name?.replace(/[-_]/g, " ") ?? "";
+	addWeightedTokens(termFrequencies, roleHint, FIELD_WEIGHTS.role);
+	const length = Array.from(termFrequencies.values()).reduce((sum, value) => sum + value, 0);
+	return { agent, termFrequencies, length };
+}
+
+export function buildAgentSearchIndex(agents: Iterable<AgentConfig>): AgentSearchIndex {
+	const documents = Array.from(agents, buildAgentSearchDocument);
+	const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+	const documentFrequencies = new Map<string, number>();
+	for (const document of documents) {
+		for (const token of new Set(document.termFrequencies.keys())) {
+			documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+		}
+	}
+	return { documents, averageLength, documentFrequencies };
+}
+
+export function searchAgents(index: AgentSearchIndex, query: string, limit: number): AgentSearchResult[] {
+	const queryTokens = tokenize(query);
+	if (queryTokens.length === 0) return [];
+	if (index.documents.length === 0) return [];
+
+	const queryTermCounts = new Map<string, number>();
+	for (const token of queryTokens) {
+		queryTermCounts.set(token, (queryTermCounts.get(token) ?? 0) + 1);
+	}
+
+	return index.documents
+		.map((document) => {
+			let score = 0;
+			for (const [token, queryTermCount] of queryTermCounts) {
+				const termFrequency = document.termFrequencies.get(token) ?? 0;
+				if (termFrequency === 0) continue;
+				const documentFrequency = index.documentFrequencies.get(token) ?? 0;
+				const idf = Math.log(1 + (index.documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
+				const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (document.length / index.averageLength));
+				score += queryTermCount * idf * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
+			}
+			return { agent: document.agent, score };
+		})
+		.filter((result) => result.score > 0)
+		.sort((left, right) => right.score - left.score || left.agent.name.localeCompare(right.agent.name))
+		.slice(0, limit);
+}

package/src/agents/agent-serializer.ts

@@ -20,6 +20,10 @@ export function serializeAgent(agent: AgentConfig): string {
 		line("systemPromptMode", agent.systemPromptMode),
 		line("inheritProjectContext", agent.inheritProjectContext),
 		line("inheritSkills", agent.inheritSkills),
+		line("memory", agent.memory),
+		line("loadMode", agent.loadMode),
+		line("defaultTools", agent.defaultTools ?? undefined),
+		line("contextMode", agent.contextMode),
 		line("triggers", agent.routing?.triggers),
 		line("useWhen", agent.routing?.useWhen),
 		line("avoidWhen", agent.routing?.avoidWhen),

package/src/agents/discover-agents.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { AgentConfig, ResourceSource } from "./agent-config.ts";
 import { loadConfig, type LoadedPiTeamsConfig } from "../config/config.ts";
 import { parseCsv, parseFrontmatter } from "../utils/frontmatter.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 import { packageRoot, projectCrewRoot, userPiRoot } from "../utils/paths.ts";
 
 export interface AgentDiscoveryResult {
@@ -19,6 +20,14 @@ function parseMemory(value: string | undefined): "user" | "project" | "local" |
 	return value === "user" || value === "project" || value === "local" ? value : undefined;
 }
 
+function parseLoadMode(value: string | undefined): "essential" | "lean" | undefined {
+	return value === "essential" || value === "lean" ? value : undefined;
+}
+
+function parseContextMode(value: string | undefined): "fresh" | "fork" | undefined {
+	return value === "fresh" || value === "fork" ? value : undefined;
+}
+
 function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig | undefined {
 	try {
 		const content = fs.readFileSync(filePath, "utf-8");
@@ -43,13 +52,17 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			extensions: frontmatter.extensions === "" ? [] : parseCsv(frontmatter.extensions),
 			skills: parseCsv(frontmatter.skills ?? frontmatter.skill),
 			systemPromptMode: frontmatter.systemPromptMode === "append" ? "append" : "replace",
-			inheritProjectContext: frontmatter.inheritProjectContext as unknown === true || frontmatter.inheritProjectContext === "true",
-		inheritSkills: frontmatter.inheritSkills as unknown === true || frontmatter.inheritSkills === "true",
+			inheritProjectContext: frontmatter.inheritProjectContext === "true",
+		inheritSkills: frontmatter.inheritSkills === "true",
 		memory: parseMemory(frontmatter.memory),
-		disabled: frontmatter.disabled as unknown === true || frontmatter.disabled === "true" || frontmatter.enabled as unknown === false || frontmatter.enabled === "false",
+		loadMode: parseLoadMode(frontmatter.loadMode),
+		defaultTools: frontmatter.defaultTools !== undefined ? parseCsv(frontmatter.defaultTools) ?? null : undefined,
+		contextMode: parseContextMode(frontmatter.contextMode),
+		disabled: frontmatter.disabled === "true" || frontmatter.enabled === "false",
 			routing: triggers || useWhen || avoidWhen || cost || category ? { triggers, useWhen, avoidWhen, cost, category } : undefined,
 		};
-	} catch {
+	} catch (error) {
+		logInternalError("discoverAgents.parseAgentFile", error, `filePath=${filePath}`);
 		return undefined;
 	}
 }

package/src/config/config.ts

@@ -46,6 +46,7 @@ export interface CrewRuntimeConfig {
 	requirePlanApproval?: boolean;
 	completionMutationGuard?: CompletionMutationGuardMode;
 	effectivenessGuard?: EffectivenessGuardMode;
+	yield?: { enabled?: boolean; maxReminders?: number; reminderPrompt?: string };
 }
 
 export interface CrewControlConfig {
@@ -100,6 +101,11 @@ export interface CrewTelemetryConfig {
 	enabled?: boolean;
 }
 
+export interface CrewPolicyConfig {
+	requireIntentForDestructiveActions?: boolean;
+	disabledCapabilities?: string[];
+}
+
 export type CrewNotificationSeverity = "info" | "warning" | "error" | "critical";
 
 export interface CrewNotificationsConfig {
@@ -152,6 +158,7 @@ export interface PiTeamsConfig {
 	agents?: CrewAgentsConfig;
 	tools?: CrewToolsConfig;
 	telemetry?: CrewTelemetryConfig;
+	policy?: CrewPolicyConfig;
 	notifications?: CrewNotificationsConfig;
 	observability?: CrewObservabilityConfig;
 	reliability?: CrewReliabilityConfig;
@@ -363,6 +370,12 @@ function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfi
 			...withoutUndefined((override.telemetry ?? {}) as Record<string, unknown>),
 		};
 	}
+	if (base.policy || override.policy) {
+		merged.policy = {
+			...(base.policy ?? {}),
+			...withoutUndefined((override.policy ?? {}) as Record<string, unknown>),
+		};
+	}
 	if (base.notifications || override.notifications) {
 		merged.notifications = {
 			...(base.notifications ?? {}),
@@ -619,6 +632,16 @@ function parseTelemetryConfig(value: unknown): CrewTelemetryConfig | undefined {
 	return Object.values(telemetry).some((entry) => entry !== undefined) ? telemetry : undefined;
 }
 
+function parsePolicyConfig(value: unknown): CrewPolicyConfig | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const policy: CrewPolicyConfig = {
+		requireIntentForDestructiveActions: parseWithSchema(Type.Boolean(), obj.requireIntentForDestructiveActions),
+		disabledCapabilities: parseWithSchema(Type.Array(Type.String()), obj.disabledCapabilities),
+	};
+	return Object.values(policy).some((entry) => entry !== undefined) ? policy : undefined;
+}
+
 function parseNotificationsConfig(value: unknown): CrewNotificationsConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
@@ -700,6 +723,7 @@ export function parseConfig(raw: unknown): PiTeamsConfig {
 		agents: parseAgentsConfig(obj.agents),
 		tools: parseToolsConfig(obj.tools),
 		telemetry: parseTelemetryConfig(obj.telemetry),
+		policy: parsePolicyConfig(obj.policy),
 		notifications: parseNotificationsConfig(obj.notifications),
 		observability: parseObservabilityConfig(obj.observability),
 		reliability: parseReliabilityConfig(obj.reliability),

package/src/config/defaults.ts

@@ -12,6 +12,17 @@ export const DEFAULT_CHILD_PI = {
 	maxCompactContentChars: 4096,
 };
 
+export const DEFAULT_LIVE_SESSION = {
+	/** Maximum wall-clock time for a single live-session task before abort (ms). */
+	responseTimeoutMs: 5 * 60_000,
+	/** Maximum yield reminder attempts before accepting no-yield. */
+	maxYieldRetries: 3,
+	/** Polling interval for session idle check during yield enforcement (ms). */
+	yieldPollIntervalMs: 500,
+	/** Maximum time to wait for session idle after prompt (ms). */
+	idleWaitTimeoutMs: 60_000,
+};
+
 export const DEFAULT_LOCKS = {
 	staleMs: 30_000,
 };

package/src/extension/autonomous-policy.ts

@@ -73,46 +73,39 @@ export function buildAutonomousPolicy(prompt: string, config: PiTeamsAutonomousC
 		? "Do not suggest worktree mode unless the user explicitly asks for it."
 		: "Consider workspaceMode: 'worktree' for parallel or risky code-changing work in clean git repositories.";
 	return [
-		"# pi-crew Autonomous Delegation Policy",
+		"# pi-crew Delegation Policy (MANDATORY)",
 		"",
 		`Autonomy profile: ${effective.profile}.`,
-		"You have access to the `team` tool for coordinated multi-agent work. Use it proactively when the task benefits from specialized roles, planning, review, verification, durable artifacts, async execution, or worktree isolation.",
+		"You MUST evaluate EVERY user request against the delegation decision table below BEFORE acting.",
 		"",
-		"Decision framework (not keyword-only):",
-		"- Treat a user-supplied task list with 2+ actionable bullets/numbered items as a delegation candidate even when no pi-crew keyword appears.",
-		"- Prefer `team` when tasks span multiple files/subsystems, require sequencing, combine implementation + tests/docs/review, or need independent exploration before edits.",
-		"- If unsure whether subtasks conflict, call `team` with action='recommend' first instead of manually splitting work.",
-		"- For assisted/aggressive autonomy and non-trivial multi-task work, prefer a team run or plan over direct single-agent execution.",
+		"## Decision Table — Do I delegate?",
 		"",
-		"Use `team` automatically when:",
-		"- The task spans multiple files, subsystems, or unclear code areas.",
-		"- The prompt contains a non-trivial task list, roadmap, checklist, migration plan, or ordered implementation plan.",
-		"- The task requires planning before implementation.",
-		"- The task asks for implementation plus tests, review, verification, migration, architecture, security review, or debugging.",
-		"- The task would benefit from explorer/planner/executor/reviewer/verifier roles.",
+		"| Task characteristic | Delegate? | Method |",
+		"|---|---|---|",
+		"| Read/edit 1-2 files, simple question | NO | Do it directly |",
+		"| User explicitly says \"do it yourself\" / \"no team\" | NO | Do it directly |",
+		"| Destructive action (delete/prune/forget) | NO | Ask for confirmation first |",
+		"| Research / deep-read / source audit / \"nghiên cứu\" | YES | `team action='research'` |",
+		"| Multi-file implementation / feature / refactor | YES | `team action='run', team='implementation'` |",
+		"| Small bug fix (1-2 files, clear cause) | YES | `team action='run', team='fast-fix'` |",
+		"| Code review / security review | YES | `team action='run', team='review'` |",
+		"| Task list with 2+ actionable items | YES | `team action='plan'` or `action='run'` |",
+		"| Need exploration before knowing scope | YES | `Agent(explorer)` or `team action='recommend'` |",
+		"| Parallel independent subtasks | YES | `team action='parallel'` or multiple `Agent` background |",
+		"| Unsure which team/workflow fits | YES | `team action='recommend'` first |",
 		"",
-		"Do not use `team` when:",
-		"- The user asks a simple factual question or tiny single-file edit.",
-		"- The user explicitly asks you to work directly without delegation.",
-		"- The tasks clearly modify the same small file region and can be completed safer by one agent without parallel fanout.",
-		"- The action is destructive (`delete`, `forget`, `prune`, forced cleanup) and the user has not explicitly confirmed it.",
+		"## Rules",
 		"",
-		"Recommended mappings:",
-		"- Complex feature/refactor/migration -> action='run', team='implementation'.",
-		"- Small bug fix -> action='run', team='fast-fix'.",
-		"- Code/security review -> action='run', team='review'.",
-		"- Research or documentation synthesis -> action='run', team='research'.",
-		"- Unsure which team/workflow to use -> call the `team` tool with action='recommend' and the user's goal, then follow the suggested plan/run call if appropriate.",
-		"- After delegating exploration/research/review, do not duplicate the same search manually. Continue only with non-overlapping work.",
-		"- Before claiming delegated work is complete, inspect the run with action='status' or action='summary'.",
-		"- Unsure or risky work -> action='plan' first, then run the selected team.",
+		"1. If the task needs reading >3 files OR editing >2 files OR has a research/review/planning component → you MUST delegate via `team` or `Agent`. Do not do it yourself.",
+		"2. After delegating, do NOT duplicate the same exploration/reading/review manually. Continue only with non-overlapping work.",
+		"3. Before claiming delegated work is complete, verify with `team action='status'` or `action='summary'`.",
+		"4. If unsure whether subtasks conflict, use `team action='recommend'` first.",
+		"5. For parallel implementation, prefer `workspaceMode: 'worktree'` in clean git repos.",
 		"",
-		"Conflict-safe task splitting:",
-		"- Do not parallelize subtasks that may edit the same file, same symbol, same migration path, package manifest, lockfile, or generated schema unless a planner explicitly sequences them.",
-		"- For potential overlap, use plan/recommend first, assign one owner per file/symbol, and require workers to report intended changed files before editing.",
-		"- Prefer workspaceMode: 'worktree' for parallel implementation in clean git repositories, but still avoid merging overlapping edits without review.",
-		"- If workers discover overlap, blockers, missing requirements, or need leader decisions, they must use mailbox/status artifacts to ask the leader/orchestrator and pause risky edits.",
-		"- The leader should resolve conflicts by sequencing, narrowing scope, or reassigning ownership before continuing.",
+		"## Conflict-safe task splitting",
+		"- Do not parallelize subtasks that may edit the same file, same symbol, or same lockfile.",
+		"- Assign one owner per file/symbol. Workers must report intended changed files before editing.",
+		"- If workers discover overlap, they must pause and ask the leader to resolve.",
 		"",
 		asyncGuidance,
 		worktreeGuidance,