pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/src/async-subagents/async-subagents.sample.jsonc

@@ -1,38 +1,10 @@
 {
-  // This sample is the value for `asyncSubagents` in ~/.config/pi/pi-tools-suite.jsonc.
+  // Value of asyncSubagents in pi-tools-suite.jsonc.
+  // Bundled role definitions and ordered models live in agents/*.md.
   // Full config schema: https://unpkg.com/pi-ui-extend/schemas/pi-tools-suite.json
-
-  // Global async-subagents routing.
-  // Rule of thumb:
-  // - GLM: cheap/fast discovery, grep-style scanning, docs/test inventory.
-  // - GLM-5.3 Flash: frontend/UI/UX, visual/product polish, and multimodal-heavy analysis.
-  // - GPT/Claude: review/audit, deep reasoning, tests, and implementation/refactoring.
-  // Override exact model IDs here if your pi provider uses different names.
-  "defaultType": "quick",
-
-  // Maximum concurrent sub-agent processes for this project/session.
-  // 0 means unlimited. Excess agents stay queued as planned until a slot opens.
+  "defaultType": "research",
   "maxConcurrent": 5,
-
-  // Optional global retry defaults. Per-type `retry` overrides these values.
-  // `retryableExitCodes` omitted = retry any non-zero exit; [] = disable retry by exit-code filter.
-  // "retry": { "maxRetries": 1, "backoffMs": 2000, "retryableExitCodes": [1, 124] },
-
-  // Maximum bytes copied from raw result.md into result.json's `resultText`.
-  // result.md itself remains the full raw sub-agent output.
   "maxResultBytes": 100000,
-
-  // Optional wall-clock timeout for each spawned agent in milliseconds.
-  // The built-in default is 30 minutes when this is omitted. You can also set
-  // `timeoutMs` per type/preset, or pass `timeoutSeconds` to a spawn call/task
-  // for short synthetic tests.
-  // "timeoutMs": 1800000,
-
-  // Parent-model image-capability overrides. Pi provider metadata can be missing
-  // or stale after switching models, so async-subagents treats these glob-like
-  // model refs as text-only when dynamic detection is inconclusive. Blind-model
-  // screenshot inspection should use lookup; this only keeps guidance honest.
-  // Matching is case-insensitive and supports `*` wildcards.
   "vision": {
     "blindModelPatterns": [
       "zai/glm-4.5*", "glm-4.5*", "*/glm-4.5*",
@@ -40,231 +12,43 @@
       "zai/glm-5.3", "glm-5.3", "*/glm-5.3"
     ]
   },
-
-  // Optional per-type prompt customization (leave commented until needed):
-  // - promptAppend: append extra instructions after the generated prompt.
-  // - promptOverride: replace the generated prompt entirely.
-  // Supports placeholders: {id}, {task}, {scope}, {parentObjective}, {subagentType}, {model}, {thinking}.
-  // Example inside any type profile:
-  // "promptAppend": [
-  //   "Use this role-specific checklist.",
-  //   "Return file paths before conclusions."
-  // ],
-  // "promptOverride": "You are a specialized {subagentType} sub-agent.\nParent: {parentObjective}\nTask: {task}\nScope: {scope}",
-
-  // Parent-model-aware model selection (optional, any type profile).
-  // modelByParent maps glob model refs (matched against the current parent
-  // model, e.g. "zai/*") to a model for this role. The first matching key wins.
-  // Values may be a model string or { model, fallbackModels? }. It is resolved
-  // after an explicit task.model / forcedModel, but before the preset/static
-  // profile model, so a role like an "oracle" can always pick a flagship from a
-  // DIFFERENT provider than the parent. Example:
-  // "modelByParent": {
-  //   "zai/*": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },
-  //   "openai-codex/*": "zai/glm-5.3",
-  //   "antigravity/*": { "model": "zai/glm-5.3", "fallbackModels": ["openai-codex/gpt-5.6-sol"] }
-  // }
-
-  // Role auto-selection when subagentType is omitted is handled by a small LLM
-  // router request. The router receives each task plus the configured type
-  // descriptions, then returns one allowed subagentType per task. Explicit
-  // task subagentType still wins. If the router model is unavailable or returns
-  // invalid JSON, async-subagents falls back to defaultType.
+  // Only omitted roles use the LLM router. Model selection itself is deterministic.
   "routing": {
     "enabled": true,
-    "model": "zai/glm-4.5-air",
-    // Ordered router model fallbacks tried when the primary routing model is
-    // unavailable or fails. The current parent model is always tried last.
+    "model": "zai/glm-5-turbo",
     "fallbackModels": ["openai-codex/gpt-5.6-luna"],
     "maxTaskChars": 1200,
     "maxTokens": 512,
-    "maxRetries": 3,
-    "timeoutMs": 10000,
+    "maxRetries": 1,
+    "timeoutMs": 12000,
     "debug": false
   },
-
-  // Presets are named agent/model configurations selected with /subagent-preset.
-  // They do not replace role routing below: `types` still defines what each role means.
-  // A preset overrides the models/thinking used by roles.
-  // Set AGENTS_PRESET=<name> before launching Pi to override the saved
-  // /subagent-preset selection for only the current process/session without
-  // modifying the saved selection file. If Pi is already running, use
-  // /subagent-preset session <name> and /subagent-preset session-clear instead.
-  // Shape:
-  // "presets": {
-  //   "name": {
-  //     "description": "shown in the selector",
-  //     "model": "optional fallback model for roles not listed in types",
-  //     "fallbackModels": ["optional/session fallback when model quota is exhausted"],
-  //     "thinking": "optional fallback thinking level",
-  //     "extraArgs": ["optional", "global", "pi", "args"],
-  //     "timeoutMs": 1800000,
-  //     "types": {
-  //       "roleName": { "model": "provider/model", "fallbackModels": ["provider/backup"], "thinking": "off|low|medium|high|xhigh|max", "timeoutMs": 1800000 }
-  //     }
-  //   }
-  // }
-  // Fallbacks are intended to cross provider boundaries: zai/* roles usually omit
-  // fallbackModels when that provider is effectively unlimited. If GPT/openai-codex
-  // is exhausted, use the matching zai/* role model. If Antigravity is exhausted,
-  // use the matching GPT/openai-codex role model, then matching zai/*. Exhausted
-  // providers are skipped for the current Pi process/session.
-  // Explicit task model/thinking and FORCE_CURRENT_MODEL still take precedence.
-
+  // A preset is an available model pool, NOT a role-to-model mapping.
+  // Choose the first usable entry in each agent's models that is in
+  // this pool. Pool order does not reorder agent preferences. The remaining
+  // matching candidates are the only quota fallbacks; never leave the pool.
+  // Oracle uses its strong candidate list, preferring another provider when
+  // possible, but also respects this pool. An empty intersection is an error.
+  // Explicit task.model, CLI --model, and FORCE_CURRENT_MODEL remain overrides.
+  // Legacy preset model/types/fallbackModels fields still load for compatibility.
   "presets": {
     "cheap": {
-      "description": "Use GLM models by role, including GLM-5.3 Flash for multimodal work.",
-      "types": {
-        "quick": { "model": "zai/glm-4.5-air", "thinking": "off" },
-        "scan": { "model": "zai/glm-4.5-air", "thinking": "off" },
-        "research": { "model": "zai/glm-5-turbo", "thinking": "low" },
-        "docs": { "model": "zai/glm-4.5-air", "thinking": "low" },
-        "frontend": { "model": "zai/glm-5.3-flash", "thinking": "medium" },
-        "browser-qa": { "model": "zai/glm-5.3-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna"], "thinking": "low" },
-        "tests": { "model": "zai/glm-5-turbo", "thinking": "medium" },
-        "review": { "model": "zai/glm-5.3", "thinking": "high" },
-        "implement": { "model": "zai/glm-5.3", "thinking": "high" },
-        "deep": { "model": "zai/glm-5.3", "thinking": "high" }
-      }
+      "description": "GLM pool: economical workers plus GLM-5.3 for oracle.",
+      "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
     },
-
     "gpt": {
-      "description": "Use the GPT-5.6 family by role: luna for fast tasks, terra for balanced work, and sol for heavy reasoning; fallback cross-provider on quota.",
-      "types": {
-        "quick": { "model": "openai-codex/gpt-5.6-luna", "fallbackModels": ["zai/glm-4.5-air"], "thinking": "off" },
-        "scan": { "model": "openai-codex/gpt-5.6-luna", "fallbackModels": ["zai/glm-4.5-air"], "thinking": "off" },
-        "research": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5-turbo"], "thinking": "low" },
-        "docs": { "model": "openai-codex/gpt-5.6-luna", "fallbackModels": ["zai/glm-4.5-air"], "thinking": "low" },
-        "frontend": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"], "thinking": "medium" },
-        "browser-qa": { "model": "zai/glm-5.3-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna"], "thinking": "low" },
-        "tests": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5-turbo"], "thinking": "medium" },
-        "review": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
-        "implement": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
-        "deep": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" }
-      }
+      "description": "GPT pool: Luna/Terra workers; Sol is available to oracle.",
+      "models": ["openai-codex/gpt-5.6-luna", "openai-codex/gpt-5.6-terra", "openai-codex/gpt-5.6-sol"]
     },
-
     "deep": {
-      "description": "Use only enabled strong models, mixing GPT, Claude, and Gemini by role.",
-      "types": {
-        "quick": { "model": "openai-codex/gpt-5.6-luna", "fallbackModels": ["zai/glm-4.5-air"], "thinking": "low" },
-        "scan": { "model": "antigravity/gemini-3-flash-preview", "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-4.5-air"], "thinking": "off" },
-        "research": { "model": "antigravity/gemini-3.1-pro-preview", "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-5-turbo"], "thinking": "medium" },
-        "docs": { "model": "antigravity/gemini-2.5-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-4.5-air"], "thinking": "medium" },
-        "frontend": { "model": "antigravity/gemini-3.1-pro-preview-customtools", "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-5.3"], "thinking": "low" },
-        "browser-qa": { "model": "zai/glm-5.3-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna"], "thinking": "low" },
-        "tests": { "model": "antigravity/antigravity-claude-sonnet-4-6", "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-5-turbo"], "thinking": "high" },
-        "review": { "model": "antigravity/antigravity-claude-sonnet-4-6", "fallbackModels": ["openai-codex/gpt-5.6-sol", "zai/glm-5.3"], "thinking": "high" },
-        "implement": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
-        "deep": { "model": "antigravity/antigravity-claude-opus-4-6-thinking", "fallbackModels": ["openai-codex/gpt-5.6-sol", "zai/glm-5.3"], "thinking": "high" }
-      }
+      "description": "Legacy preset name for the mixed pool; workers retain economical candidate order, oracle uses strong models.",
+      "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "openai-codex/gpt-5.6-luna", "openai-codex/gpt-5.6-terra", "openai-codex/gpt-5.6-sol", "zai/glm-5.3"]
     }
   },
-
-  "types": {
-    "quick": {
-      "description": "Use for tiny cheap tasks: answer a simple question, inspect one known file, or verify one fact. Not for broad repo search.",
-      "model": "openai-codex/gpt-5.6-luna",
-      "fallbackModels": ["zai/glm-4.5-air"],
-      "thinking": "off"
-    },
-
-    "scan": {
-      "description": "Use for finding files, symbols, text, or inventory across a repo. Return paths/facts; do not judge code quality.",
-      "model": "openai-codex/gpt-5.6-luna",
-      "fallbackModels": ["zai/glm-4.5-air"],
-      "thinking": "off",
-      "tools": ["read", "grep"]
-    },
-
-    "research": {
-      "description": "Use for multi-file codebase research: read several files and explain how something works. No edits.",
-      "model": "openai-codex/gpt-5.6-terra",
-      "fallbackModels": ["zai/glm-5-turbo"],
-      "thinking": "low",
-      "tools": ["read", "grep"]
-    },
-
-    "docs": {
-      "description": "Use for documentation work: README/API docs review, docs gaps, changelog, migration notes, examples.",
-      "model": "openai-codex/gpt-5.6-luna",
-      "fallbackModels": ["zai/glm-4.5-air"],
-      "thinking": "low"
-    },
-
-    "frontend": {
-      "description": "Use for frontend UI/UX visual work: styling, layout, typography, animation, responsive states, component polish, accessibility. Avoid backend/business logic unless needed for UI behavior.",
-      "model": "antigravity/gemini-3-flash-preview",
-      "fallbackModels": ["openai-codex/gpt-5.6-luna", "zai/glm-5.3"],
-      "thinking": "medium",
-      "promptAppend": [
-        "Act as a frontend UI/UX engineer for visual and product-facing work.",
-        "Prioritize layout, typography, spacing, color, motion, responsive states, accessibility, and consistency with the existing design system.",
-        "Before editing, inspect nearby components/styles and infer the project's design language. Avoid backend/business-logic changes unless required for UI behavior.",
-        "When no mockup exists, choose a clear aesthetic direction and explain it briefly. Verify with targeted build/lint/tests or screenshot-relevant checks when possible."
-      ]
-    },
-
-    "browser-qa": {
-      "description": "Use for browser-based visual QA: reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.",
-      "model": "zai/glm-5.3-flash",
-      "fallbackModels": ["openai-codex/gpt-5.6-luna"],
-      "thinking": "low",
-      "timeoutMs": 300000,
-      "tools": ["read", "grep", "bash"]
-    },
-
-    "tests": {
-      "description": "Use for tests: locate coverage, find gaps, run/check targeted test commands, diagnose failing tests.",
-      "model": "openai-codex/gpt-5.6-terra",
-      "fallbackModels": ["zai/glm-5-turbo"],
-      "thinking": "medium",
-      "tools": ["read", "grep", "bash"]
-    },
-
-    "review": {
-      "description": "Use for review/audit of existing code or changes: correctness, security, performance, maintainability, API risks, quality. Do not implement new code.",
-      "model": "openai-codex/gpt-5.6-sol",
-      "fallbackModels": ["zai/glm-5.3"],
-      "thinking": "high",
-      "tools": ["read", "grep"]
-    },
-
-    "implement": {
-      "description": "Use when the sub-agent should make or plan code changes for a feature, bug fix, or refactor.",
-      "model": "openai-codex/gpt-5.6-sol",
-      "fallbackModels": ["zai/glm-5.3"],
-      // Avoid Sol recursively doing routine implementation work for a Sol parent.
-      // Luna also escalates substantial implementation to Terra. modelByParent
-      // wins over preset role models, so this prevents both Luna -> Sol and
-      // Sol -> Sol for implement tasks under the built-in `gpt` preset.
-      "modelByParent": {
-        "openai-codex/gpt-5.6-luna*": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5.3"] },
-        "openai-codex/gpt-5.6-sol*": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5.3"] }
-      },
-      "thinking": "high"
-    },
-
-    "deep": {
-      "description": "Use for broad hard reasoning: architecture, system design, cross-module impact, complex tradeoffs.",
-      "model": "openai-codex/gpt-5.6-sol",
-      "fallbackModels": ["zai/glm-5.3"],
-      "thinking": "high"
-    },
-
-    "oracle": {
-      "description": "Oracle: cross-provider flagship second opinion for hard or high-stakes uncertainty. Use sparingly to pressure-test architecture, plans, root-cause hypotheses, risk/security calls, or final recommendations when independent disagreement is valuable. Read-only; advise, do not edit.",
-      "model": "openai-codex/gpt-5.6-sol",
-      "fallbackModels": ["zai/glm-5.3"],
-      "thinking": "max",
-      "tools": ["read", "grep", "bash"],
-      "modelByParent": {
-        "zai/*": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },
-        "openai-codex/*": { "model": "zai/glm-5.3", "fallbackModels": ["openai-codex/gpt-5.6-sol"] },
-        "antigravity/*": { "model": "zai/glm-5.3", "fallbackModels": ["openai-codex/gpt-5.6-sol"] },
-        "anthropic/*": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] }
-      },
-      "promptAppend": "You are an oracle: a flagship model from a different provider giving a second opinion to the parent agent. Give a concise, decisive recommendation with key tradeoffs and risks. Disagree when warranted; do not rubber-stamp. Do not edit unless explicitly asked."
-    }
-  }
+  // Override role behavior here or define project specialists in .pi/agents/.
+  // Old builtin names are not aliases; define them explicitly only when you
+  // intentionally want custom types with those exact names.
+  // Per-type "icon" names the agent glyph for UI widgets (agent, search, code,
+  // flask, globe, sparkles, brain, wrench, terminal, bug, book, eye, zap, rocket).
+  "types": {}
 }

package/external/pi-tools-suite/src/async-subagents/commands.ts

@@ -53,13 +53,13 @@ const COPY_SAMPLE_CONFIG_LABEL = "Copy sample asyncSubagents config";
 
 export const ULTRAWORK_PROMPT = `Run ultrawork mode for the current objective.
 
-Use subagents when independent parallel tracks help. Pick subagentType from configured roles: quick, scan, research, docs, frontend, implement, tests, review, deep, oracle. Use review for security/performance/audit tracks, implement for refactors, deep for debugging/root-cause. Use frontend for UI/UX and visual frontend implementation; use oracle sparingly for cross-provider second opinions on high-stakes uncertainty.
+Use subagents when a lower-cost worker or isolation of noisy evidence helps, including one bounded sequential task. Pick subagentType from the effective catalog: research for reading/review, implement for code/docs/tests/UI changes, verify for running checks, browser-qa for real-browser testing, and oracle only for a deliberate strong independent opinion. Prefer an appropriate project-local specialist. Keep decisions and integration in the parent; do not create agents just to assign a discipline.
 
 Keep parent context lean: spawn for broad parallel work, read results only when needed, and finish unless genuinely blocked.`;
 
 const HYPERPLAN_PROMPT = `Run hyperplan mode for the current objective.
 
-Before implementation, use subagents to pressure-test the plan with configured roles such as deep, implement, frontend, tests, review, and docs. Synthesize the strongest objections into a revised plan before editing.`;
+Before implementation, use bounded research tasks to gather constraints and independently pressure-test the plan. Use oracle only when a strong second opinion is justified. Synthesize the evidence and objections in the parent before editing.`;
 
 export function buildUltraworkPrompt(objective: string): string {
 	const trimmed = objective.trim();
@@ -368,6 +368,10 @@ function sortedPresetNames(presets: Record<string, SubagentPreset>, activePreset
 function subagentPresetDescription(preset: SubagentPreset): string {
 	const parts: string[] = [];
 	if (preset.description) parts.push(preset.description);
+	if (preset.models !== undefined) {
+		parts.push(`models:${preset.models.join(",") || "(none)"}`);
+		return parts.join(", ");
+	}
 	if (preset.model) parts.push(`model:${preset.model}`);
 	if (preset.fallbackModels && preset.fallbackModels.length > 0) parts.push(`fallbacks:${preset.fallbackModels.join(",")}`);
 	if (preset.thinking) parts.push(`thinking:${preset.thinking}`);

package/external/pi-tools-suite/src/async-subagents/core/agent-catalog.ts

@@ -0,0 +1,41 @@
+import type { SubagentConfig } from "./config.js";
+import { SUBAGENT_DELEGATION_GUIDANCE } from "./agent-strategy.js";
+
+export const SUBAGENT_TYPE_SELECTION_GUIDANCE = "Choose and set subagentType from the available catalog when a role clearly matches, preferring a matching project-local specialist. Preserve a user-requested role. Omit subagentType only when unsure or when the user explicitly requests automatic routing; the LLM router handles omissions only. Model/thinking overrides are not substitutes for choosing a role.";
+
+const MAX_DESCRIPTION_CHARS = 500;
+
+/**
+ * Render the effective sub-agent type catalog for the parent system prompt.
+ * The config has already merged built-ins, config files, and project-local
+ * `.pi/agents/*.md`, so this stays aligned with what spawn/routing can use.
+ */
+export function buildSubagentCatalogPrompt(config: SubagentConfig): string | undefined {
+	const entries = Object.entries(config.types).sort(([left], [right]) => left.localeCompare(right));
+	if (entries.length === 0) return undefined;
+
+	return [
+		'<available_subagent_types>',
+		"Effective sub-agent types available to the `subagents` tool for this project.",
+		"These names are valid explicit `subagentType` values. Project-local `.pi/agents/*.md` roles are included when enabled by the current config.",
+		SUBAGENT_TYPE_SELECTION_GUIDANCE,
+		SUBAGENT_DELEGATION_GUIDANCE,
+		...entries.map(([name, profile]) => `- ${escapePromptText(name)}: ${catalogDescription(profile.description)}`),
+		'</available_subagent_types>',
+	].join("\n");
+}
+
+function catalogDescription(description: string | undefined): string {
+	const text = description?.trim() || "No description; use only when the task explicitly names this type.";
+	const bounded = text.length <= MAX_DESCRIPTION_CHARS
+		? text
+		: `${text.slice(0, MAX_DESCRIPTION_CHARS - 1).trimEnd()}…`;
+	return escapePromptText(bounded.replace(/\s+/g, " "));
+}
+
+function escapePromptText(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}

package/external/pi-tools-suite/src/async-subagents/core/agent-strategy.ts

@@ -1,5 +1,3 @@
-import { isGptLikeModel } from "./ultrawork-auto.js";
-
 export type AgentStrategyName = "parallel-first" | "deep-work" | "escalation-aware" | "cost-aware-orchestrator";
 
 export interface AgentStrategyOptions {
@@ -8,106 +6,28 @@ export interface AgentStrategyOptions {
 	env?: NodeJS.ProcessEnv;
 }
 
-const FALSE_ENV_PATTERN = /^(0|false|off|no|disabled|none)$/i;
-const TRUE_ENV_PATTERN = /^(1|true|on|yes|auto)$/i;
-
-const PARALLEL_FIRST_STRATEGY_PROMPT = `<agent_strategy name="parallel-first">
-Execution hint for Pi, not a replacement for system/developer/user instructions.
-
-Default: orchestration-first. For broad, multi-file, ambiguous, review/audit, frontend, test-strategy, architecture, or root-cause work, prefer ultrawork: split independent tracks into focused async subagents, adding one oracle only for high-stakes uncertainty. Keep parent context lean, read compact results when needed, synthesize, then verify.
-
-Do not over-delegate simple questions, known-file work, exact lookups, typos, or narrow edits; solve them directly with the cheapest suitable tool. If compressing unfinished work, preserve active objective + next step via todo/DCP rules.
-</agent_strategy>`;
-
-const DEEP_WORK_STRATEGY_PROMPT = `<agent_strategy name="deep-work">
-Execution hint for Pi, not a replacement for system/developer/user instructions.
-
-Default: autonomous deep worker. Build context directly, make progress, edit, and verify end-to-end. Use async subagents/ultrawork only when the user asks for delegation or independent tracks clearly reduce risk; do not force orchestration onto narrow tasks.
+/** Shared by the strategy, tool description and role catalog. */
+export const SUBAGENT_DELEGATION_GUIDANCE = "Delegate bounded work when a lower-cost worker can do it or noisy intermediate evidence should stay out of the parent context; one sequential task can qualify. Keep planning, decisions, integration and the final answer in the parent. Use research for evidence/review, implement for code/docs/tests/UI changes, verify for running checks, browser-qa for browser testing. Reserve oracle for a deliberate strong independent opinion, not automatic escalation. Do trivial lookups/edits directly; redirect a noisy command to a log instead of spawning an LLM when no interpretation is needed.";
 
-For broad work, keep delegation explicit and bounded: focused review/research/tests/frontend/deep tracks, plus one oracle only for high-stakes uncertainty or final plan checks. Read compact results, decide in the parent session, and report only what matters. If compressing unfinished work, preserve active objective + next step via todo/DCP rules.
-</agent_strategy>`;
-
-const ESCALATION_AWARE_STRATEGY_PROMPT = `<agent_strategy name="escalation-aware">
+export function agentStrategyPrompt(options: AgentStrategyOptions = {}): string | undefined {
+	const env = options.env ?? process.env;
+	const override = env.PI_AGENT_STRATEGY?.trim() || env.ASYNC_SUBAGENTS_AGENT_STRATEGY?.trim();
+	if (/^(0|false|off|no|disabled|none)$/i.test(override ?? "")) return undefined;
+	const allowCustom = env.PI_AGENT_STRATEGY_WITH_CUSTOM_PROMPT ?? env.ASYNC_SUBAGENTS_AGENT_STRATEGY_WITH_CUSTOM_PROMPT;
+	if (options.customPrompt && !/^(1|true|on|yes|auto)$/i.test(allowCustom?.trim() ?? "")) return undefined;
+	// Old strategy names remain accepted, but no longer cause hidden tier escalation.
+	return `<agent_strategy name="cost-aware-orchestrator">
 Execution hint for Pi, not a replacement for system/developer/user instructions.
 
-Default: self-sufficient with tiered escalation. Solve narrow, well-bounded work directly, but do not grind through a large or uncertain task at the current model tier when a stronger focused subagent is appropriate. Use todo for the plan and async subagents for escalation; read compact results first and keep the parent context lean.
-
-For a Luna parent, prefer Terra workers for substantial multi-file research, tests, or implementation, and escalate deep root-cause analysis, architecture/security review, high-risk decisions, or repeatedly failing complex work to Sol through the deep/review roles. For a Terra parent, handle routine research/tests/implementation directly; escalate deep root-cause analysis, architecture/security review, high-risk decisions, or stubborn complex failures to Sol through deep/review. Do not escalate merely because a plan has several steps, and do not delegate a tiny known-file edit or exact lookup.
-
-Keep user questions, plan/todo changes, integration decisions, and the final report in the parent. Independent read-only escalations may run in parallel; serialize overlapping edits unless scopes are clearly disjoint. When work is delegated, synchronize its todo lifecycle: mark it in progress, collect and verify the worker result, then complete/update it before moving on.
-</agent_strategy>`;
-
-const COST_AWARE_ORCHESTRATOR_STRATEGY_PROMPT = `<agent_strategy name="cost-aware-orchestrator">
-Execution hint for Pi, not a replacement for system/developer/user instructions.
+${SUBAGENT_DELEGATION_GUIDANCE}
 
-Default: cost-aware orchestration. You are an expensive parent model, so keep the parent session focused on planning, decisions, integration, verification, and the final user-facing answer. For non-trivial todo work, prefer focused async subagents for repo scanning, multi-file research, documentation, tests, frontend work, and implementation steps that would otherwise require several repository tool calls. Read compact subagent results first; inspect raw artifacts or redo work in the parent only when verification or uncertainty requires it.
+Give each worker a scoped task, necessary context, acceptance criteria, and a compact return contract. Put task-specific discipline in the brief, not a new persona. Respect the configured worker budget; do not force the parent model or repeatedly retry with stronger workers. On a capability or reasoning blocker, collect the evidence and decide in the parent whether an oracle is justified.
 
-Keep user questions, todo/plan changes, architecture tradeoffs, cross-worker integration decisions, high-stakes review, and the final report in the parent. Do not delegate merely to avoid one cheap exact lookup or a tiny known-file edit. Independent read-only tracks may run in parallel; serialize overlapping edits unless scopes are clearly disjoint. When a todo item is delegated, keep its lifecycle synchronized: mark it in progress, collect and verify the worker result, then complete/update it before moving on.
+Read compact results first and verify selectively; do not reload every source file or repeat the worker's whole investigation. Independent tracks may run in parallel; serialize overlapping edits. Keep delegated todo lifecycle synchronized, preserve active objective + next step via todo/DCP rules, and do not poll merely for progress.
 </agent_strategy>`;
-
-export function agentStrategyPrompt(options: AgentStrategyOptions = {}): string | undefined {
-	const env = options.env ?? process.env;
-	const override = strategyOverride(env);
-	if (override === "off") return undefined;
-	if (options.customPrompt && shouldSkipCustomPrompt(env)) return undefined;
-
-	const strategy = override
-		?? (isExpensiveGptParent(options.modelRef)
-			? "cost-aware-orchestrator"
-			: isEscalationAwareGptParent(options.modelRef)
-				? "escalation-aware"
-			: isGptLikeModel(options.modelRef)
-				? "deep-work"
-				: "parallel-first");
-	if (strategy === "cost-aware-orchestrator") return COST_AWARE_ORCHESTRATOR_STRATEGY_PROMPT;
-	if (strategy === "escalation-aware") return ESCALATION_AWARE_STRATEGY_PROMPT;
-	return strategy === "deep-work" ? DEEP_WORK_STRATEGY_PROMPT : PARALLEL_FIRST_STRATEGY_PROMPT;
 }
 
 export function appendAgentStrategyPrompt(systemPrompt: string, strategyPrompt: string): string {
 	const base = systemPrompt.trimEnd();
 	return base ? `${base}\n\n${strategyPrompt}` : strategyPrompt;
 }
-
-function strategyOverride(env: NodeJS.ProcessEnv): AgentStrategyName | "off" | undefined {
-	const raw = firstEnv(env, "PI_AGENT_STRATEGY", "ASYNC_SUBAGENTS_AGENT_STRATEGY");
-	if (!raw) return undefined;
-	const value = normalizeStrategyName(raw);
-	if (FALSE_ENV_PATTERN.test(value)) return "off";
-	if (value === "parallel-first") return "parallel-first";
-	if (value === "deep-work") return "deep-work";
-	if (value === "escalation" || value === "escalation-aware") return "escalation-aware";
-	if (value === "cost-aware" || value === "cost-aware-orchestrator" || value === "orchestrator") return "cost-aware-orchestrator";
-	if (TRUE_ENV_PATTERN.test(value)) return undefined;
-	return undefined;
-}
-
-function isExpensiveGptParent(modelRef: string | undefined): boolean {
-	if (!modelRef) return false;
-	return /(?:^|\/)gpt-5\.6-sol(?:$|[-.:])/i.test(modelRef.trim());
-}
-
-function isEscalationAwareGptParent(modelRef: string | undefined): boolean {
-	if (!modelRef) return false;
-	return /(?:^|\/)gpt-5\.6-(?:luna|terra)(?:$|[-.:])/i.test(modelRef.trim());
-}
-
-function shouldSkipCustomPrompt(env: NodeJS.ProcessEnv): boolean {
-	const raw = firstEnv(env, "PI_AGENT_STRATEGY_WITH_CUSTOM_PROMPT", "ASYNC_SUBAGENTS_AGENT_STRATEGY_WITH_CUSTOM_PROMPT");
-	return raw ? !TRUE_ENV_PATTERN.test(raw.trim()) : true;
-}
-
-function normalizeStrategyName(raw: string): string {
-	const value = raw.trim().toLowerCase().replace(/_/g, "-");
-	if (value === "parallel" || value === "parallel-first") return "parallel-first";
-	if (value === "deep" || value === "deep-work") return "deep-work";
-	return value;
-}
-
-function firstEnv(env: NodeJS.ProcessEnv, ...keys: string[]): string | undefined {
-	for (const key of keys) {
-		const value = env[key];
-		if (typeof value === "string" && value.trim()) return value;
-	}
-	return undefined;
-}