@selesai/code 0.8.3 → 0.8.4

package/dist/extensions/pi-subagents/agents/builder.md

@@ -1,7 +1,6 @@
 ---
 name: builder
 description: Mutation-capable scoped implementation
-aliases: developer, coder, implementer, develop
 acceptanceRole: writer
 thinking: high
 systemPromptMode: replace

package/dist/extensions/pi-subagents/agents/delegate.md

@@ -0,0 +1,14 @@
+---
+name: delegate
+description: Lightweight subagent that inherits the parent model with no default reads
+systemPromptMode: append
+inheritProjectContext: true
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+inheritSkills: false
+---
+
+You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
+
+The builtin delegate uses a strict tool allowlist and does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
+
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return normally when no coordination is needed.

package/dist/extensions/pi-subagents/agents/oracle.md

@@ -0,0 +1,74 @@
+---
+name: oracle
+aliases: advisor
+description: High-context decision-consistency oracle that protects inherited state and prevents drift
+tools: read, grep, find, ls, bash, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+---
+
+You are the oracle: a high-context decision-consistency subagent.
+
+Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
+
+Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
+
+If you need clarification from the main agent and runtime bridge instructions are present, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
+
+Do not send routine completion handoffs. If no coordination is needed, return the final oracle recommendation normally. Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target.
+
+Core responsibilities:
+- reconstruct inherited decisions, constraints, and open questions from the context
+- identify drift between the current trajectory and those inherited decisions
+- surface contradictions and hidden assumptions the main agent may be missing
+- call out when a proposed move conflicts with an earlier decision or constraint
+- protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
+- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
+
+What you do not do by default:
+- do not edit files or write code
+- do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
+- do not assume a `worker` implementation handoff is the default outcome
+- do not propose broad pivots unless the context clearly supports them
+- do not continue the user conversation directly
+
+Working rules:
+- Use `bash` only for inspection, verification, or read-only analysis.
+- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` before continuing.
+- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
+
+Your output should follow this shape. If no executor handoff is warranted, say so plainly.
+
+Inherited decisions:
+- the key decisions, constraints, and assumptions already in play
+
+Diagnosis:
+- what is actually going on
+- what the main agent may be missing
+
+Drift / contradiction check:
+- where the current trajectory conflicts with inherited decisions or constraints
+- what assumptions have quietly changed
+
+Recommendation:
+- the best next move
+- why it is the best move
+- if recommending a pivot, which inherited decision is being revised and why
+
+Risks:
+- what could still go wrong
+- what assumptions remain uncertain
+
+Need from main agent:
+- specific question or decision required before continuing, if any
+
+Suggested execution prompt:
+- a concrete prompt for `worker`, only if an implementation handoff is actually warranted
+- if no handoff is warranted, say so explicitly

package/dist/extensions/pi-subagents/agents/reviewer.md

@@ -0,0 +1,78 @@
+---
+name: reviewer
+description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
+tools: read, grep, find, ls, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
+
+## Review types you handle
+
+### 1. Code diffs (changed files)
+Inspect the actual diff or changed files. Verify:
+- Implementation matches intent and requirements.
+- Code is correct, coherent, and handles edge cases.
+- Tests cover the change and still pass.
+- No unintended side effects or regressions.
+- The change is minimal and readable.
+
+### 2. Plans
+Validate a proposed plan for:
+- Feasibility and completeness.
+- Missing steps or hidden risks.
+- Alignment with existing architecture and constraints.
+- Whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach for:
+- Correctness and tradeoffs.
+- Fit with existing codebase patterns.
+- Whether simpler alternatives exist.
+- Edge cases the proposal may miss.
+
+### 4. Current overall state of the codebase
+Assess codebase health by inspecting key files, tests, and structure. Look for:
+- Architecture drift or tech debt.
+- Inconsistent patterns or naming.
+- Areas lacking tests or documentation.
+- Obvious bugs or fragile code.
+- Opportunities to simplify or consolidate.
+
+### 5. Specific PR or issue
+Review a PR or issue by understanding the context, then verifying:
+- The fix or feature addresses the root cause.
+- Changes are minimal and focused.
+- No regressions are introduced.
+- Tests and docs are updated as needed.
+
+## Working rules
+- Read the relevant files first. Read plan and progress when the task supplies them.
+- Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
+- Do not use shell commands or write files. Report any test or Git command that a supervisor must run.
+- Do not invent issues. Only report problems you can justify from evidence.
+- Prefer small corrective edits over broad rewrites.
+- If everything looks good, say so plainly.
+- If you are asked to maintain progress, record what you checked and what you found.
+- If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
+
+Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
+
+## Review output format
+Structure your findings clearly:
+
+```
+## Review
+- Correct: what is already good (with evidence)
+- Fixed: issue, location, and resolution (if you applied a fix)
+- Blocker: critical issue that must be resolved before proceeding
+- Note: observation, risk, or follow-up item
+```
+
+When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.

package/dist/extensions/pi-subagents/agents/scout.md

@@ -0,0 +1,50 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff
+tools: read, grep, find, ls, bash, write, intercom
+thinking: low
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+output: context.md
+defaultProgress: true
+---
+
+You are a scouting subagent running inside pi.
+
+Use the provided tools directly. Move fast, but do not guess. Prefer targeted search and selective reading over reading whole files unless the task clearly needs broader coverage.
+
+Focus on the minimum context another agent needs in order to act:
+- relevant entry points
+- key types, interfaces, and functions
+- data flow and dependencies
+- files that are likely to need changes
+- constraints, risks, and open questions
+
+Working rules:
+- Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper.
+- Use `bash` only for non-interactive inspection commands.
+- When you cite code, use exact file paths and line ranges.
+- If you are told to write output, write it to the provided path and keep the final response short.
+- When running solo, summarize what you found after writing the output.
+
+Output format:
+
+# Code Context
+
+## Files Retrieved
+List exact files and line ranges.
+1. `path/to/file.ts` (lines 10-50) - why it matters
+2. `path/to/other.ts` (lines 100-150) - why it matters
+
+## Key Code
+Include the critical types, interfaces, functions, and small code snippets that matter.
+
+## Architecture
+Explain how the pieces connect.
+
+## Start Here
+Name the first file another agent should open and why.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed scout findings normally.

package/dist/extensions/pi-subagents/agents/worker.md

@@ -0,0 +1,58 @@
+---
+name: worker
+description: Implementation agent for normal tasks and approved oracle handoffs
+aliases: developer, coder, implementer, develop
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+defaultContext: fork
+defaultReads: context.md, plan.md
+defaultProgress: true
+---
+
+You are `worker`: the implementation subagent.
+
+You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
+
+Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
+
+The builtin worker uses a strict tool allowlist. It does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
+
+If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
+
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
+
+Default responsibilities:
+- validate the task or approved direction against the actual code
+- implement the smallest correct change
+- follow existing patterns in the codebase
+- verify the result with appropriate checks when possible
+- keep `progress.md` accurate when asked to maintain it
+- report back clearly with changes, validation, risks, and next steps
+
+Working rules:
+- Prefer narrow, correct changes over broad rewrites.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Do not leave placeholder code, TODOs, or silent scope changes.
+- Use `bash` for inspection, validation, and relevant tests.
+- If there is supplied context or a plan, read it first.
+- If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
+- If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
+- Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
+
+When running in a chain, expect instructions about:
+- which files to read first
+- where to maintain progress tracking
+- where to write output if a file target is provided
+
+Your final response should follow this shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/dist/extensions/pi-subagents/docs/configuration.md

@@ -0,0 +1,328 @@
+# Configuration
+
+`pi-subagents` reads optional JSON config from `~/.selesai/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
+
+Settings-level keys (`subagents.defaultModel`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `modelScope`, `disableThinking`, `disableBuiltins`, watchdog settings) live in Selesai settings files, not this config file. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
+
+## Project root resolution (settings)
+
+By default, project settings resolve from the nearest parent directory that contains `.pi` or `.agents`, preserving existing nested-project behavior. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository-level config, set this in the repository root `.selesai/settings.json`:
+
+```json
+{
+  "subagents": {
+    "projectRootResolution": "git-root"
+  }
+}
+```
+
+`"git-root"` keeps package discovery, project agents, chains, and `agentOverrides` anchored to the git worktree root when that root also has Selesai project config. A nested project can still opt back into nearest-root behavior by setting `"projectRootResolution": "nearest"` in its own `.selesai/settings.json`.
+
+## `toolDescriptionMode`
+
+```json
+{ "toolDescriptionMode": "compact" }
+```
+
+Controls the parent-facing `subagent` tool description registered at startup. `full` is the default. `compact` keeps the execution modes, async/`subagent_wait` guidance, child-safety boundary, management/action split, one-writer review guidance, and artifact/status essentials with less prompt bloat.
+
+`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.selesai/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Selesai after changing the mode or custom file.
+
+## `legacyChainControls`
+
+```json
+{ "legacyChainControls": true }
+```
+
+Defaults to `false`. The default registered model-facing tool schema and description omit the legacy `append-step` `step` schema and legacy checkpoint controls. This does not change runtime support for existing durable legacy chains. Set this to `true` before directly managing a legacy chain with `append-step`, `approve-checkpoint`, or `reject-checkpoint`.
+
+## `inlineToolDisplay`
+
+```json
+{ "inlineToolDisplay": "summary" }
+```
+
+Controls the `subagent` tool result shown inline in chat. The default, `"rich"`, shows live child activity and expands to detailed output. `"summary"` keeps the inline result at one stable row for running, completed, failed, stopped, and paused runs; it does not animate, show elapsed time, preview child output, or change when Selesai's expand key is pressed. FleetView remains available for live progress and detailed inspection.
+
+## `asyncByDefault`
+
+```json
+{ "asyncByDefault": false }
+```
+
+WorkflowScript calls use background execution when the request omits `async`. Set `asyncByDefault` to `false` to restore foreground-by-default behavior for tool launches that still use the internal single-run primitive. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
+
+## `fleetView`
+
+```json
+{ "fleetView": false }
+```
+
+Controls the persistent, navigable FleetView. The default is `true`. Set it to `false` to hide FleetView without disabling status tracking, completion notifications, `/subagents-fleet`, or lifecycle events.
+
+## `fleetViewPlacement`
+
+```json
+{ "fleetViewPlacement": "aboveEditor" }
+```
+
+Places the persistent FleetView either `"belowEditor"` or `"aboveEditor"`. The default is `"belowEditor"`; invalid values fall back to `"belowEditor"`.
+
+## `fleetKeybindings`
+
+```json
+{
+  "fleetKeybindings": {
+    "pageUp": ["u"],
+    "pageDown": ["d"],
+    "selectFirst": ["g"],
+    "selectLast": ["G"]
+  }
+}
+```
+
+Customizes only the full Fleet inspector opened by `/subagents-fleet` or FleetView inspection. It does not change Selesai's global keybindings or the compact persistent FleetView.
+
+Each action accepts a non-empty array of key strings. Configured actions replace their defaults. Unset actions keep the defaults: `selectUp` is `up`/`k`, `selectDown` is `down`/`j`, `scrollUp` is `K`, `scrollDown` is `J`, `pageUp` is `pageUp`, `pageDown` is `pageDown`, `selectFirst` is `home`, `selectLast` is `end`, `toggleTools` is `x`/`X`/`ctrl+o`, `refresh` is `r`/`R`, `steer` is `s`, `stop` is `D`, `inspect` is `H`, and `close` is `escape`/`ctrl+c`/`q`.
+
+Prompt modes keep their fixed keys. For example, `Esc` still cancels steer text or stop confirmation even when the Fleet-level close binding is changed.
+
+## `asyncWidget`
+
+```json
+{ "asyncWidget": true }
+```
+
+Controls the under-editor widget for active background runs. It defaults to `true`, including when FleetView is enabled, so active work remains visible after reload. Set it to `false` to hide this widget while keeping FleetView available.
+
+## `waitTool`
+
+```json
+{ "waitTool": { "enabled": false } }
+```
+
+Keeps the `subagent_wait` tool registered but makes direct calls return immediately instead of blocking on active subagent or provider work. The default is enabled. You can also set `"waitTool": false`; set `SELESAI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. The effective value is passed explicitly to child runtimes. Headless `agent_end` auto-drain remains a lifecycle safeguard even when direct wait calls are disabled. Invalid config or environment values fail instead of being coerced.
+
+Blocking `subagent_wait({ id: "..." })` keeps the current tool call open until that run changes. In a long-lived interactive parent session, `subagent_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work.
+
+This is different from `waitTool.enabled=false`, which returns immediately without registering any future wake. Provider items remain available only to blocking fleet-wide waits; non-blocking subscriptions require one async or remembered detached foreground run id.
+
+## `forceTopLevelAsync`
+
+```json
+{ "forceTopLevelAsync": true }
+```
+
+Forces depth-0 internal single, parallel, and chain runs into background mode and bypasses launch UI by forcing `clarify: false`. Nested calls keep their own inherited settings.
+
+## `globalConcurrencyLimit`
+
+```json
+{ "globalConcurrencyLimit": 20 }
+```
+
+Caps simultaneously running children inside existing durable legacy multi-child runs. New orchestration uses `workflowScript` and `runs.all`.
+
+## `maxSubagentSpawnsPerSession`
+
+```json
+{ "maxSubagentSpawnsPerSession": 100 }
+```
+
+Optionally caps the total number of child subagent launches during one parent session, including completed and failed children, parallel task counts, static chain steps, and bounded dynamic fanout children. Sessions are unlimited by default. Set this value to `0` to disable a configured cap. `SELESAI_SUBAGENT_MAX_SPAWNS_PER_SESSION` overrides the config for a process and follows the same positive-cap/zero-unlimited semantics.
+
+`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, remaining capacity, grants, and the remaining grant allowance. Static chains and parallel calls fail before creating run artifacts or starting partial work when their declared capacity cannot fit. Later retries or unbounded dynamic work are not guaranteed by that preflight.
+
+A user may explicitly call `subagent({ action: "grant-spawn-budget", additional: 10 })` from the root interactive parent after all children settle and confirm the native prompt. Grants are additive: they never erase cumulative usage, are rejected for unlimited sessions and child/headless callers, and total granted capacity cannot exceed the original configured cap. Compaction remains part of the same logical parent session and does not reset usage or grants; starting a new parent session does.
+
+## `scheduledRuns`
+
+```json
+{ "scheduledRuns": { "enabled": false, "maxPending": 20 } }
+```
+
+Durable schedules are enabled by default and stored per project under `.pi-subagents/schedules/<id>/`. See [missions.md](missions.md#schedules) for usage.
+
+Set `storeRoot` to keep durable schedules outside project repositories. It must be an absolute path or a `~/` path, which expands from the user home directory. Each project is stored under a hash of its resolved working directory, so projects do not share schedules.
+
+```json
+{ "scheduledRuns": { "storeRoot": "~/.local/share/pi-subagents/schedules" } }
+```
+
+When `storeRoot` is omitted, schedules remain at `<cwd>/.pi-subagents/schedules`.
+
+## `parallel`
+
+```json
+{
+  "parallel": {
+    "maxTasks": 12,
+    "concurrency": 6
+  }
+}
+```
+
+`maxTasks` defaults to `8`; `concurrency` defaults to `4`. Per-call `concurrency` takes precedence.
+
+## `defaultSessionDir`
+
+```json
+{ "defaultSessionDir": "~/.selesai/agent/sessions/subagent/" }
+```
+
+Session directory precedence is: `params.sessionDir`, then `config.defaultSessionDir`, then a directory derived from the parent session. Sessions are always enabled.
+
+## `singleRunOutputBaseDir`
+
+```json
+{ "singleRunOutputBaseDir": "~/.selesai/subagent-outputs" }
+```
+
+Routes relative `output` paths for single-agent `/run` calls under this directory. Absolute per-call or agent output paths are still used as-is. When unset, relative single-run outputs go under the run's output artifact directory instead of the project root.
+
+## `maxSubagentDepth`
+
+```json
+{ "maxSubagentDepth": 1 }
+```
+
+Controls nested delegation when no inherited `SELESAI_SUBAGENT_MAX_DEPTH` is already in effect. Per-agent `maxSubagentDepth` can tighten the limit for that agent's child runs, but cannot relax an inherited stricter limit. This applies even to children that explicitly declare `tools: subagent`; at the cap, execution fanout is blocked instead of silently hiding nested work.
+
+## `SELESAI_SUBAGENT_PI_BINARY`
+
+```bash
+export SELESAI_SUBAGENT_PI_BINARY=/path/to/pi-or-wrapper
+```
+
+Overrides the command used to launch child Selesai processes. Package wrappers can set this to their own `pi`/agent binary so subagents inherit wrapper flags, environment setup, and bundled resources without relying on `PATH` ordering. Empty or whitespace-only values are ignored.
+
+## `intercomBridge`
+
+```json
+{
+  "intercomBridge": {
+    "mode": "always",
+    "instructionFile": "./intercom-bridge.md",
+    "resultDelivery": true
+  }
+}
+```
+
+Controls whether subagents receive runtime intercom coordination instructions and whether `intercom` and `contact_supervisor` are auto-added to their tool allowlist when needed.
+
+Fields:
+
+- `mode`: default `always`; use `fork-only` to inject only for forked runs, or `off` to disable the bridge.
+- `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.selesai/agent/extensions/subagent/`.
+- `resultDelivery`: default `false`; set `true` only when an external listener consumes `subagent:result-intercom` and acknowledges the grouped completion payload. This is optional external result delivery, not native supervisor messaging. Enabled delivery waits for acknowledgement and reports acknowledgement failures. It does not change supervisor asks or progress updates.
+
+Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply. The external `intercom` tool is fallback plumbing when present.
+
+The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, generic `intercom` as fallback plumbing, and avoid routine completion handoffs.
+
+## `worktreeBaseDir`
+
+```json
+{ "worktreeBaseDir": "/Users/matt/code/.worktrees/pi-subagents" }
+```
+
+Sets the base directory for `worktree: true` runs. Relative paths resolve from the repository root, `~/...` expands to your home directory, and `SELESAI_SUBAGENTS_WORKTREE_DIR` is used when config is unset. The default remains the system temp directory.
+
+## `worktreeSetupHook`
+
+```json
+{
+  "worktreeSetupHook": "./scripts/setup-worktree.mjs",
+  "worktreeSetupHookTimeoutMs": 45000
+}
+```
+
+The hook runs once per created worktree. Paths must be absolute, `~/...`, or repo-relative; bare command names are rejected.
+
+stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `index`, `runId`, and `baseCommit`. stdout must be one JSON object, for example:
+
+```json
+{ "syntheticPaths": [".venv", ".env.local"] }
+```
+
+`syntheticPaths` must be relative to the worktree root. They are removed before diff capture so helper files do not pollute patches. Tracked files are never excluded; marking a tracked path as synthetic fails setup. Default timeout is `30000` ms.
+
+## `missions`
+
+```json
+{
+  "missions": {
+    "enabled": true,
+    "directory": ".pi-subagents/missions",
+    "globalIndex": true,
+    "retainTerminal": 200
+  }
+}
+```
+
+Automatic missions are enabled by default for ordinary launches with a task. Use per-launch `mission: false` for intentionally ephemeral work, or set `enabled: false` to disable automatic creation globally; explicit mission actions and `missionId`/`mission` launch fields still work.
+
+- `directory` may be absolute, `~/...`, or project-relative.
+- `retainTerminal` is a positive count (default `200`); pruning removes only the oldest completed, failed, or cancelled records and their pointers, never planned, active, waiting, needs-decision, or corrupt records.
+- The user-global index contains pointers only; missing-record pointers self-heal when globally listed. Set `globalIndex: false` to disable writes or `globalIndexDir` to redirect it.
+
+## `authorityPolicy`
+
+```json
+{
+  "authorityPolicy": {
+    "discardWorktree": "confirm",
+    "destructiveCleanup": "confirm",
+    "spawnBudgetGrant": "confirm",
+    "scheduleCreate": "auto",
+    "stopRun": "auto",
+    "steerRun": "auto"
+  }
+}
+```
+
+Each fixed action resolves to `"auto"`, `"confirm"`, or `"forbid"`. This is intentionally a small action map, not a generic policy language. Confirm-required control actions fail closed without an interactive UI.
+
+## `artifactDir`
+
+```json
+{ "artifactDir": "session" }
+```
+
+Controls where subagent artifact files (inputs, outputs, transcripts, metadata) are stored:
+
+- `"project"` (default): writes to `<cwd>/.pi-subagents/artifacts/`.
+- `"session"`: stores artifacts under pi's session directory (`~/.selesai/agent/sessions/<session>/subagent-artifacts/`), keeping the working directory clean.
+- `"temp"`: uses the OS temp directory.
+
+This preference also controls the default chain scratch directory. `"project"` uses `<cwd>/.pi-subagents/chain-runs/`, while `"session"` and `"temp"` use the user-scoped temp chain directory.
+
+The `"session"` option uses the same directory that `cleanupAllArtifactDirs` already scans for age-based cleanup, so artifacts are still cleaned up automatically. Temporary chain directories are cleaned up separately after 24 hours.
+
+When a project-scoped launch runs from an npm package directory, pi-subagents warns if package settings can include `.pi-subagents/` in the published package. Add `.pi-subagents/` to `.npmignore` (or `.gitignore` when no `.npmignore` exists), use a `files` allowlist that does not include `.pi-subagents/`, or select `"session"` or `"temp"`.
+
+## `completionBatch`
+
+```json
+{
+  "completionBatch": {
+    "enabled": true,
+    "debounceMs": 150,
+    "maxWaitMs": 1000,
+    "stragglerDebounceMs": 75,
+    "stragglerMaxWaitMs": 400,
+    "stragglerWindowMs": 2000
+  }
+}
+```
+
+Controls smart batching of async-completion notifications. When several background subagents finish within a short window, their successful completions are held briefly and delivered as a single quiet grouped completion instead of separate completions.
+
+- A hard `maxWaitMs` cap (measured from the first completion in a group) guarantees nothing is held indefinitely.
+- Late-finishing siblings that arrive within `stragglerWindowMs` of a group emit join a shorter straggler group governed by `stragglerDebounceMs` and `stragglerMaxWaitMs`.
+- Failed and paused completions bypass batching and fire immediately, flushing any held successes first, so failure and needs-attention signals are never delayed.
+- Set `enabled` to `false` to restore the original one-notification-per-completion behavior. Changes apply on the next session start.
+
+## `permissions`
+
+Native child tool permission rules. See [watchdog.md](watchdog.md#native-child-tool-permissions).