pi-subagents 0.37.0 → 0.37.2

package/skills/pi-subagents/references/prompting-and-roles.md

@@ -0,0 +1,268 @@
+# Pi Subagents: Prompting And Roles
+
+This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
+
+## Capability ceilings
+
+Parent extensions may register a session-scoped, out-of-band ceiling through `pi-subagents/capability-ceiling`. Child tools are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. Do not add a model-visible ceiling field or rely on role selection for enforcement. Restricted schedules are rejected until their ceiling can be persisted safely.
+
+## When to Use
+
+- **Complex work orchestration**: use Fable mode as the default parent-agent loop for complex work. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
+- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
+- **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
+- **Recon and planning**: use `scout` or `context-builder`, then `planner`
+- **Parallel exploration**: run multiple non-conflicting tasks concurrently
+- **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
+- **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard turn and tool-call caps for explicitly read-only children.
+- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
+- **Agent authoring**: create, update, or override agents and chains for a project
+
+## Tool vs Slash Commands
+
+Agents can use the `subagent(...)` tool directly for execution, management, status, and control.
+Humans often use the slash-command layer instead:
+
+- `/run` — launch a single agent
+- `/chain` — launch a chain of steps
+- `/parallel` — launch top-level parallel tasks
+- `/run-chain` — launch a saved `.chain.md` or `.chain.json` workflow
+- `/subagents` — interactive admin for inspecting agents and editing model, thinking, or system prompt
+- `/subagents-stop [run-id]` — stop a current-session top-level async run; opens a selector when no id is given
+- `/subagent-cost` — show parent plus child token usage and cost for the session
+- `/subagents-fleet` — open the live, inspection-only foreground/async fleet; `Ctrl+Alt+F` opens it during an active foreground turn, `↑↓`/`jk` selects children, and `PgUp`/`PgDn` scrolls transcript detail
+- `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
+- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
+- `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
+- `/subagents-profiles`, `/subagents-load-profile`, `/subagents-refresh-provider-models`, `/subagents-generate-profiles`, `/subagents-check-profile` — manage model profiles and provider catalogs
+- `/prompt-workflow` and `/chain-prompts` — run prompt templates through native subagent single/chain workflows
+
+Prefer the tool when you are writing agent logic. Prefer the slash commands when
+you are guiding a human through an interactive flow.
+
+Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)` and other tools:
+- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
+- `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
+- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/parallel-context-build` — parallel `context-builder` passes that produce planning handoff context and meta-prompts
+- `/parallel-handoff-plan` — external-reference research plus local `context-builder` passes, followed by a synthesis handoff plan and implementation-ready meta-prompt
+- `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
+- `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
+
+## Applying Prompt Techniques Without Slash Commands
+
+The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
+
+### Parallel review technique
+
+Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
+
+### Proactive skill-specialist technique
+
+Use this when `{ action: "list" }` reports proactive skill subagent suggestions and the user's task would benefit from perspectives the parent regularly uses. These suggestions are conservative: a skill is recommended only when it is available and referenced repeatedly by configured agents or saved chains. Treat the list as an opt-in hint for the current task, not a command to always fan out.
+
+Default guardrails:
+- Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
+- Prefer `context: "fresh"` and include only the files, diff, plan, URL, or request details each child needs. Use forked context only when private/session history is essential and appropriate to share.
+- Use read-only agents for analysis/review unless implementation was explicitly requested; do not create several writers in the same worktree.
+- Skip proactive skill subagents for tiny questions, direct commands, highly private requests, or when the user asks not to delegate.
+- Make cost and concurrency visible by using an ordinary `subagent(...)` call rather than hidden/background automation.
+
+Example shape:
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "reviewer", task: "Apply the available 'deslop' skill to review the current diff for concrete cleanup findings only. Do not modify files.", skill: "deslop" },
+    { agent: "reviewer", task: "Apply the available 'accessibility' skill to review the UI changes for concrete issues only. Do not modify files.", skill: "accessibility" }
+  ],
+  context: "fresh",
+  concurrency: 2
+})
+```
+
+### Review-loop technique
+
+Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background chain when the workflow is known, or continue with explicit follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless the user explicitly wants the foreground clarify UI. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
+
+As a conservative orchestration policy, do not pass `turnBudget` or a hard `toolBudget` to an implementation worker, fix worker, reviewer with edit authority, or other mutation-capable child. The default tool budget blocks read/search tools rather than mutation tools, but count limits still do not measure delivery safety. Use a narrow task plus an outer elapsed deadline with enough margin, then request a checkpoint after the current tool returns. The checkpoint should report changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be used as the checkpoint trigger.
+
+### Parallel research technique
+
+Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
+
+### Parallel context-build technique
+
+Use this before planning or implementation when a stronger handoff is needed. Run a chain with one parallel step of `context-builder` agents rather than top-level parallel tasks, so relative output files live under the temporary chain directory. Give every task a distinct output path such as `context-build/request-and-scope.md`, `context-build/codebase-and-patterns.md`, and `context-build/validation-and-risks.md`. Choose two or three builders: request/scope, codebase/patterns, and validation/risks. Each builder must read every relevant file needed to understand its slice, follow imports/callers/tests/docs/config, conduct tool-available web research when needed, and include a compact `meta-prompt` section. The parent synthesizes the outputs into important context, recommended next meta-prompt, open questions, assumptions, and artifact paths.
+
+Example shape:
+
+```typescript
+subagent({
+  chain: [{
+    parallel: [
+      { agent: "context-builder", task: "Build request/scope context for: ...", output: "context-build/request-and-scope.md" },
+      { agent: "context-builder", task: "Build codebase/pattern context for: ...", output: "context-build/codebase-and-patterns.md" },
+      { agent: "context-builder", task: "Build validation/risk context for: ...", output: "context-build/validation-and-risks.md" }
+    ]
+  }],
+  context: "fresh"
+})
+```
+
+### Parallel handoff-plan technique
+
+Use this when the user needs a solution brief or implementation-ready handoff from an external reference plus local code context, such as “study this library behavior, inspect our codebase, then produce a worker prompt.” Run a chain with a first parallel group and a second synthesis `context-builder` step. The first group usually includes `researcher` for external projects/docs/prompt guidance and `context-builder` for local code context; add a second `context-builder` for implementation strategy only when the scope is large enough to benefit. Use distinct output paths under `handoff/`, then have the synthesis `context-builder` read those outputs and write `handoff/final-handoff-plan.md` with the recommended approach, likely files, constraints, non-goals, validation, risks, unresolved questions, and final compact implementation-ready meta-prompt.
+
+Example shape:
+
+```typescript
+subagent({
+  chain: [
+    { parallel: [
+      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
+      { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
+      { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
+    ] },
+    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
+  ],
+  context: "fresh"
+})
+```
+
+### Gather-context-and-clarify technique
+
+Use this at the start of non-trivial work. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
+
+### Parallel cleanup technique
+
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+
+### Staged fix orchestration technique
+
+Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep the active worktree safe with a three-stage chain:
+
+1. A parallel read-only planning fanout, one planner/reviewer per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
+2. One writer worker. It receives the planner summaries through `{previous}`, the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
+3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
+
+Prefer `async: true`, `context: "fresh"` for planners/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Add `phase` and `label` to make async status readable, and use `as` plus `{outputs.name}` when a later step needs a specific earlier result instead of the whole `{previous}` blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
+
+When the first step can return a structured target list, prefer dynamic fanout instead of hand-authoring a static parallel group. Use `outputSchema` and `as` on the producer, then an `expand` step with `from: { output, path }`, an explicit `maxItems`, one `parallel` child template, and `collect.as`. Item templates may use `{item}` or a named item such as `{target.path}`. Do not use dynamic fanout for prose outputs, nested fanout, dynamic agent selection, reducers, `when` conditions, or arbitrary expressions; `.chain.md` does not support this syntax, so use direct JSON or a saved `.chain.json`.
+
+Example shape:
+
+```typescript
+subagent({
+  async: true,
+  context: "fresh",
+  chain: [
+    { parallel: [
+      { agent: "reviewer", phase: "Planning", label: "Deploy docs", as: "deployPlan", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" },
+      { agent: "reviewer", phase: "Planning", label: "Scheduler contract", as: "schedulerPlan", task: "Plan fixes for scheduler contract. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/scheduler.md", outputMode: "file-only" },
+      { agent: "reviewer", phase: "Planning", label: "Sandbox/security", as: "sandboxPlan", task: "Plan fixes for sandbox/security. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/sandbox.md", outputMode: "file-only" }
+    ], concurrency: 3 },
+    { agent: "worker", phase: "Implementation", label: "Apply accepted fixes", as: "workerResult", task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\n\nDeploy plan:\n{outputs.deployPlan}\n\nScheduler plan:\n{outputs.schedulerPlan}\n\nSandbox plan:\n{outputs.sandboxPlan}", output: "worker/fixes.md", outputMode: "file-only", progress: true },
+    { parallel: [
+      { agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
+      { agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
+    ], concurrency: 2 }
+  ]
+})
+```
+
+## Builtin Agents
+
+Builtin agents load at the lowest priority. Project agents override user agents,
+and user/project agents override builtins with the same name.
+
+| Agent | Purpose | Model | Typical output / role |
+|-------|---------|-------|------------------------|
+| `scout` | Fast codebase recon | inherits default | Writes `context.md` handoff material |
+| `planner` | Creates implementation plans | inherits default | Writes `plan.md` |
+| `worker` | Implementation and approved oracle handoffs | inherits default | Single-writer implementation with decision escalation |
+| `reviewer` | Review specialist | inherits default | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
+| `context-builder` | Requirements/codebase handoff builder | inherits default | Writes structured context files |
+| `researcher` | Web research brief generator | inherits default | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
+| `advisor` | Claude Code-compatible alias for `oracle` | inherits default | Same advisory role as `oracle` |
+
+Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+
+Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. Set `subagents.defaultModel` when subagents should use a different default model than the parent session. Override builtin defaults before copying full agent files when a small tweak is enough.
+
+Set `subagents.defaultThinking` to apply a shared thinking level to builtin, package, user, and project agents whose frontmatter leaves `thinking` unset. Project settings win over user settings; explicit frontmatter (including `thinking: false`), `agentOverrides.<name>.thinking`, and per-run overrides remain more specific. This setting affects child agents only and does not change the parent session's default thinking level.
+
+```json
+{
+  "subagents": {
+    "defaultThinking": "medium"
+  }
+}
+```
+
+For one run, use inline config:
+
+```text
+/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
+```
+
+For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
+
+Model ids do not have to be exact. Separator variations (`claude-haiku-4.5` vs `claude-haiku-4-5`), case (`Claude-Sonnet-4`), and optional trailing date stamps (`claude-haiku-4-5-20251001`) all resolve to the same registry model. Exact `provider/id` wins; a qualified `provider/model` never switches providers. To constrain subagents to a budget or compliance profile, set `subagents.modelScope: { enforce: true, allow: ["anthropic/*", "openai/gpt-5-*"] }` in user or project settings. Out-of-scope models you pass explicitly error and abort; models inherited from frontmatter, `subagents.defaultModel`, agent frontmatter, or the parent session only warn.
+
+For model fleets, use the profile commands instead of hand-editing repeated overrides: `/subagents-refresh-provider-models <provider>`, `/subagents-generate-profiles <provider>`, `/subagents-load-profile <name>`, and `/subagents-check-profile <name>`. Profiles live under `~/.pi/agent/profiles/pi-subagents/` and replace only `settings.subagents` when loaded.
+
+## Prompting role subagents
+
+Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
+
+A strong subagent prompt usually includes:
+- **Goal**: the concrete outcome the child should produce.
+- **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
+- **Success criteria**: what must be true before the child can finish.
+- **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is an explicitly assigned `tools: subagent` fanout child, or escalation for unapproved decisions.
+- **Validation**: targeted checks to run, or the next-best check when validation is impossible.
+- **Output**: the expected summary shape, artifact path, or finding format.
+- **Stop rules**: when to ask via `intercom`, when to stop after enough evidence, and when not to keep searching.
+
+Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop.
+
+For implementation handoffs, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation.
+
+Settings locations:
+- User scope: `~/.pi/agent/settings.json`
+- Project scope: `.pi/settings.json`
+
+Direct settings example:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "model": "anthropic/claude-sonnet-4",
+        "thinking": "high",
+        "fallbackModels": ["openai/gpt-5-mini"],
+        "acceptanceRole": "read-only"
+      }
+    }
+  }
+}
+```
+
+Useful override fields: `model`, `fallbackModels`, `thinking`,
+`systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`,
+`acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
+Use `acceptanceRole: false` to clear an override. Create a user or project
+agent with the same name only when you want a substantially different agent.
+
+If a provider rejects model IDs with thinking suffixes, use
+`subagents.disableThinking: true` in user or project settings to clear bundled
+builtin thinking defaults globally. A higher-precedence per-agent `thinking`
+override can opt one builtin back in. Existing custom-agent frontmatter remains authoritative.
+
+Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Explicit custom-agent frontmatter still wins.
+
+Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. Set `toolDescriptionMode` to `compact` to reduce tool-description prompt cost while keeping the execution, async/`subagent_wait`, child-safety, one-writer, management/action, and artifact/status guardrails. Set it to `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/src/agents/skills.ts

@@ -379,19 +379,21 @@ function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candi
 	return candidate.order < existing.order ? candidate : existing;
 }
 
-function maybeReadSkillDescription(filePath: string): string | undefined {
-	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		const normalized = content.replace(/\r\n/g, "\n");
-		if (!normalized.startsWith("---")) return undefined;
+function parseSkillDescription(content: string): string | undefined {
+	const normalized = content.replace(/\r\n/g, "\n");
+	if (!normalized.startsWith("---")) return undefined;
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) return undefined;
 
-		const endIndex = normalized.indexOf("\n---", 3);
-		if (endIndex === -1) return undefined;
+	const frontmatter = normalized.slice(3, endIndex).trim();
+	const match = frontmatter.match(/^description:\s*(.+)$/m);
+	return match?.[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+}
 
-		const frontmatter = normalized.slice(3, endIndex).trim();
-		const match = frontmatter.match(/^description:\s*(.+)$/m);
-		if (!match) return undefined;
-		return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+function maybeReadSkillDescription(filePath: string): string | undefined {
+	try {
+		return parseSkillDescription(fs.readFileSync(filePath, "utf-8"));
 	} catch {
 		// Description parsing is best-effort metadata extraction.
 		return undefined;
@@ -585,7 +587,7 @@ function readSkill(
 
 		const raw = fs.readFileSync(skillPath, "utf-8");
 		const content = stripSkillFrontmatter(raw);
-		const description = maybeReadSkillDescription(skillPath);
+		const description = parseSkillDescription(raw);
 		const skill: ResolvedSkill = {
 			name: skillName,
 			path: skillPath,

package/src/api/delegation.ts

@@ -131,6 +131,7 @@ export interface SubagentDelegationStarted {
 }
 
 export interface SubagentDelegationUpdate extends SubagentDelegationStarted {
+	runId?: string;
 	currentTool?: string;
 	currentToolArgs?: string;
 	recentOutput?: string;
@@ -230,6 +231,7 @@ export interface SubagentDelegationV2Started {
 }
 
 export interface SubagentDelegationV2Update extends SubagentDelegationV2Started {
+	runId?: string;
 	currentTool?: string;
 	currentToolArgs?: string;
 	recentOutput?: string;
@@ -266,6 +268,7 @@ export interface SubagentDelegationV2TerminalResponse extends SubagentDelegation
 	model?: string;
 	thinking?: string;
 	exitCode?: number;
+	launchContractDigest?: string;
 	result?: SubagentDelegationV2Value;
 	usage?: SubagentDelegationV2Usage;
 }

package/src/extension/index.ts

@@ -26,7 +26,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
-import { SubagentFleetStatus } from "../tui/fleet-status.ts";
+import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
 import { SubagentParams } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
@@ -143,10 +143,13 @@ function createSlashResultComponent(
 }
 
 class SubagentControlNoticeComponent implements Component {
-	constructor(
-		private readonly details: SubagentControlMessageDetails,
-		private readonly theme: ExtensionContext["ui"]["theme"],
-	) {}
+	private readonly details: SubagentControlMessageDetails;
+	private readonly theme: ExtensionContext["ui"]["theme"];
+
+	constructor(details: SubagentControlMessageDetails, theme: ExtensionContext["ui"]["theme"]) {
+		this.details = details;
+		this.theme = theme;
+	}
 
 	invalidate(): void {}
 
@@ -193,6 +196,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const waitToolConfig = resolveWaitToolConfig(config.waitTool);
 	const asyncByDefault = config.asyncByDefault === true;
 	const fleetViewEnabled = config.fleetView !== false;
+	const fleetViewPlacement = resolveFleetViewPlacement(config.fleetViewPlacement);
 	const asyncWidgetEnabled = config.asyncWidget === true || (!fleetViewEnabled && config.asyncWidget !== false);
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
@@ -236,14 +240,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const ctx = state.lastUiContext;
 			if (!ctx?.hasUI) return;
 			await openSubagentFleet(ctx, state, { initialKey: itemKey });
-		})
+		}, { placement: fleetViewPlacement })
 		: undefined;
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
 		RESULTS_DIR,
 		10 * 60 * 1000,
-		{ notifier: completionNotifier },
+		{
+			notifier: completionNotifier,
+			deliverIntercomResults: config.intercomBridge?.resultDelivery !== false,
+		},
 	);
 
 	const runtimeCleanup = () => {

package/src/extension/rpc.ts

@@ -6,6 +6,7 @@ import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
 import { deliverStopRequest } from "../runs/background/control-channel.ts";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import {
 	type Details,
 	ASYNC_DIR,
@@ -23,7 +24,7 @@ export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
 export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
 export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
 
-export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop"] as const;
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop", "resume"] as const;
 export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
 
 export interface SubagentRpcRequestEnvelope {
@@ -183,6 +184,7 @@ function pingData(ctx: ExtensionContext | null) {
 			nonRecoveringSteer: true,
 			interrupt: true,
 			stop: true,
+			resume: true,
 			processTerminalProof: { version: 1, lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION },
 		},
 		events: {
@@ -238,6 +240,24 @@ function steerParams(params: unknown): SubagentParamsLike {
 	};
 }
 
+function resumeParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "resume");
+	if (typeof input.message !== "string" || !input.message.trim())
+		throw new SubagentRpcError("invalid_params", "RPC resume requires a non-empty message.");
+	const target = normalizeTargetParams(input, "resume");
+	if (!target.id && !target.runId && !target.dir) throw new SubagentRpcError("invalid_params", "RPC resume requires id, runId, or dir.");
+	if (input.output !== undefined && (typeof input.output !== "string" || !input.output.trim()))
+		throw new SubagentRpcError("invalid_params", "RPC resume output must be a non-empty path.");
+	if (input.outputMode !== undefined && input.outputMode !== "file-only")
+		throw new SubagentRpcError("invalid_params", "RPC resume supports only file-only output mode.");
+	return {
+		action: "resume",
+		...target,
+		message: input.message.trim(),
+		...(typeof input.output === "string" ? { output: input.output.trim(), outputMode: "file-only" } : {}),
+	};
+}
+
 function stopAsyncRun(
 	params: unknown,
 	options: RegisterSubagentRpcBridgeOptions,
@@ -257,7 +277,7 @@ function stopAsyncRun(
 		throw new SubagentRpcError("not_found", "Async run not found or already completed; stop requires a live async run directory.");
 	}
 
-	const currentSessionId = ctx.sessionManager.getSessionId();
+	const currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 	const initialStatus = readStatus(location.asyncDir);
 	const initialRunId = initialStatus?.runId ?? location.resolvedId ?? path.basename(location.asyncDir);
 	if (!initialStatus) throw new SubagentRpcError("not_found", `Status file not found for async run '${initialRunId}'.`);
@@ -324,6 +344,9 @@ async function handleRequest(
 	if (request.method === "stop") {
 		return stopAsyncRun(request.params, options, ctx);
 	}
+	if (request.method === "resume") {
+		return executeChecked(options, ctx, request.requestId, request.method, resumeParams(request.params));
+	}
 	throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
 }
 

package/src/extension/schemas.ts

@@ -290,8 +290,8 @@ const SubagentParamsSchema = Type.Object({
 	})),
 	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout for foreground and async/background runs; foreground defaults to 30m absent call/agent. Alias maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs for foreground and async/background runs; foreground defaults to 30m absent call/agent." })),
 	turnBudget: Type.Optional(TurnBudgetOverride),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),

package/src/extension/tool-description.ts

@@ -23,7 +23,7 @@ EXECUTION (use exactly ONE mode):
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
 • Fork thinking: model strings accept a thinking suffix (provider/model:off|minimal|low|medium|high|xhigh|max). Forking over a parent transcript that carries signed Anthropic thinking blocks forces thinking off only when a child's effective primary or fallback model resolves to the Anthropic provider or anthropic-messages API; unresolved models are treated conservatively. The result notes affected children, including on failures. Use fresh context when an Anthropic child needs thinking.
-• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs
+• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided
 • Acceptance: omit acceptance for reviewer/read-only calls. Evidence levels end at verified. Use acceptance.review.required to require independent review of a writer result. Never request acceptance:"reviewed"; reviewed is achieved only after an independent reviewer result.
 • If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
 
@@ -80,7 +80,7 @@ export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with {
 EXECUTE:
 • Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.
 • SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{parallel:[...]}]}.
-• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs.
+• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided.
 • Omit acceptance for reviewer/read-only calls. Evidence levels end at verified; use acceptance.review.required for independent writer review. reviewed is an achieved status, never an explicit input.
 • Chain templates may use {task}, {previous}, {chain_dir}, and named outputs. Parallel worktree isolation requires a clean git repo.
 • Chain example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {parallel: [{agent:"agent-b", task:"Check {previous}", count: 3}]}] }

package/src/intercom/intercom-bridge.ts

@@ -32,6 +32,7 @@ Do not use contact_supervisor or intercom for routine completion handoffs. If no
 export interface IntercomBridgeState {
 	active: boolean;
 	mode: IntercomBridgeMode;
+	resultDelivery: boolean;
 	orchestratorTarget?: string;
 	extensionDir: string;
 	instruction: string;
@@ -78,11 +79,12 @@ export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 
 function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return { mode: "always", instructionFile: "" };
+		return { mode: "always", instructionFile: "", resultDelivery: true };
 	}
 	return {
 		mode: resolveIntercomBridgeMode(value.mode),
 		instructionFile: typeof value.instructionFile === "string" ? value.instructionFile : "",
+		resultDelivery: value.resultDelivery !== false,
 	};
 }
 
@@ -146,11 +148,12 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 	);
 	const reason = inactiveReason(mode, input.context, orchestratorTarget);
 	if (reason || !orchestratorTarget) {
-		return { active: false, mode, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
+		return { active: false, mode, resultDelivery: config.resultDelivery, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
 	}
 	return {
 		active: true,
 		mode,
+		resultDelivery: config.resultDelivery,
 		orchestratorTarget,
 		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
 		instruction: buildIntercomBridgeInstruction(orchestratorTarget, resolveInstructionTemplate(config.instructionFile, settingsDir)),

package/src/runs/background/async-job-tracker.ts

@@ -60,6 +60,19 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
 		ctx.ui.requestRender?.();
 	};
+	const rerenderLastWidget = (jobs = Array.from(state.asyncJobs.values())) => {
+		const ctx = state.lastUiContext;
+		if (!ctx) return;
+		try {
+			if (ctx.hasUI) rerenderWidget(ctx, jobs);
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("extension ctx is stale")) {
+				state.lastUiContext = null;
+				return;
+			}
+			throw error;
+		}
+	};
 	const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
 	const restoredControlEventCursor = (asyncDir: string) => {
 		try {
@@ -131,9 +144,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		const timer = setTimeout(() => {
 			state.cleanupTimers.delete(asyncId);
 			state.asyncJobs.delete(asyncId);
-			if (state.lastUiContext) {
-				rerenderWidget(state.lastUiContext);
-			}
+			rerenderLastWidget();
 		}, completionRetentionMs);
 		state.cleanupTimers.set(asyncId, timer);
 	};
@@ -254,7 +265,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		if (state.poller) return;
 		state.poller = setInterval(() => {
 			if (state.asyncJobs.size === 0) {
-				if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext, []);
+				rerenderLastWidget([]);
 				if (state.poller) {
 					clearInterval(state.poller);
 					state.poller = null;
@@ -378,7 +389,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
 			}
 
-			if (widgetChanged && state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+			if (widgetChanged) rerenderLastWidget();
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};
@@ -421,9 +432,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		});
 		rememberFleetJob(state, state.asyncJobs.get(info.id)!);
 		ensurePoller();
-		if (state.lastUiContext) {
-			rerenderWidget(state.lastUiContext);
-		}
+		rerenderLastWidget();
 	};
 
 	const handleComplete = (data: unknown) => {
@@ -446,9 +455,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			}
 		}
 		if (job) rememberFleetJob(state, job);
-		if (state.lastUiContext) {
-			rerenderWidget(state.lastUiContext);
-		}
+		rerenderLastWidget();
 		if (!nestedRefreshFailed && !hasLiveNestedDescendants(job?.nestedChildren)) scheduleCleanup(asyncId);
 	};
 
@@ -485,7 +492,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		}
 		if (runs.length === 0) return;
 		ensurePoller();
-		if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+		rerenderLastWidget();
 	};
 
 	return { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs };