@bastani/atomic 0.9.13-alpha.2 → 0.9.13-alpha.4

package/dist/builtin/subagents/README.md

@@ -4,9 +4,9 @@
 
 # @bastani/subagents
 
-`@bastani/subagents` lets Atomic delegate work to focused child agents. It is Atomic's bundled adaptation of upstream `pi-subagents`; use it for code review, scouting, implementation, parallel audits, background jobs, and anything else that benefits from a second or third set of model eyes.
+`@bastani/subagents` lets Atomic delegate work to focused child agents. It is Atomic's bundled adaptation of upstream `pi-subagents`; use it for code review, scouting, implementation, parallel audits, and anything else that benefits from a second or third set of model eyes.
 
-Use subagents selectively for bounded specialist delegation while the parent remains in control: one focused agent or parallel independent tasks. Keep interactive, exploratory, conceptual, and conversation-led work inline. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. For a clearly delegated, well-defined autonomous job that is likely long-running/background-oriented or materially needs durable stages, checkpoints, resumability, HIL, gates, retries, or bounded loops, use an appropriate workflow instead. Choose async subagents only when background execution is genuinely useful; foreground is appropriate when the parent needs the result before proceeding.
+Use subagents selectively for bounded specialist delegation while the parent remains in control: one focused agent or parallel independent tasks. Keep interactive, exploratory, conceptual, and conversation-led work inline. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow. For clearly delegated autonomous jobs that need durable stages, checkpoints, resumability, HIL, gates, retries, or bounded loops, use an appropriate workflow instead. Subagent calls always run in the foreground and return their results to the parent.
 
 https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1
 
@@ -48,9 +48,9 @@ That is enough to start.
 
 Pi is the parent session. A subagent is a focused child Pi session with its own job.
 
-When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation. Background runs keep working and can be checked later.
+When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Single and parallel runs stream progress in the conversation and return their results before the call completes.
 
-Installing the extension does not start an automatic review in the background. It gives Pi a delegation tool. If you want every implementation reviewed, say that in your prompt or put it in your project instructions:
+Installing the extension does not start an automatic review. It gives Pi a delegation tool. If you want every implementation reviewed, say that in your prompt or put it in your project instructions:
 
 ```text
 When you finish implementing, run codebase-analyzer over the diff before summarizing.
@@ -100,9 +100,9 @@ Those are ordinary Pi requests. Pi decides whether to call `subagent`, which age
 | Execute a plan carefully | “Have worker implement this approved plan, then run reviewers and apply the feedback.” |
 | Diagnose a failure | “Use debugger to reproduce this test failure and fix it.” |
 | Simplify after it lands | “Use code-simplifier to clean up the change.” |
-| Run in the background | “Run this in the background.” |
+| Run a delegated task | “Have worker implement this plan and return the result.” |
 | Browse agents | “Show me the available subagents.” |
-| See running work | “Show active async runs.” |
+| See current status | “Show the current subagent status.” |
 | Check setup | “Check whether subagents are configured correctly.” |
 
 The extension ships with builtin agents you can use immediately.
@@ -157,20 +157,16 @@ Any parent chat or workflow stage that orchestrates subagents should omit the ex
 
 When an agent declares no model or fallback policy, consult `packages/coding-agent/docs/models/model-selection.md`, then call `workflow({ action: "models" })` when available. Use only a catalog-returned `fullId` and only a thinking level listed for that entry. If the catalog tool is unavailable, returns no models, or has no recommended model for the role, leave the child unpinned and report the limitation instead of inventing a model or inspecting credentials.
 
-Workflow invocations receive a stable, non-`default` Intercom group automatically. Their stages and delegated children inherit it across single, parallel, async, and follow-up calls, so omit `group` unless you intend to create a different coordination subgroup. Outside a workflow, children inherit the launching session's group. `contact_supervisor` remains available across group boundaries.
+Workflow invocations receive a stable, non-`default` Intercom group automatically. Their stages and delegated children inherit it across single, parallel, and follow-up calls, so omit `group` unless you intend to create a different coordination subgroup. Outside a workflow, children inherit the launching session's group. `contact_supervisor` remains available across group boundaries.
 
 ## Where running subagents show up
 
-Foreground runs stream progress in the conversation while they run.
+Foreground runs stream progress in the conversation while they run. Parallel calls keep their grouped task shape in progress and results, and status/control actions can inspect or interrupt retained foreground children.
 
-`async: true` means **do not wait**. Atomic admits an in-process child, returns its canonical child path immediately, and tracks the live child through the jobs widget. **Async work does not survive parent exit:** the live child is owned by the parent process and ends when Atomic quits; only its canonical identity and session file remain for a later cold resume.
-
-The jobs widget shows the live status-watch state and sends one terminal completion notification. Parallel background runs show per-agent progress and retain their grouped task shape in progress and results. There is no detached runner process or PID polling loop.
-
-You can also ask naturally:
+You can ask naturally:
 
 ```text
-Show me the current async runs.
+Show me the current subagent status.
 ```
 
 If something feels misconfigured, run:
@@ -228,7 +224,7 @@ Most users do not call `intercom` directly. When the intercom companion is avail
 Use it for work where the child might need a decision instead of guessing:
 
 ```text
-Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.
+Run this implementation. If the worker gets blocked or needs a product decision, have it ask me through intercom.
 ```
 
 ```text
@@ -239,10 +235,10 @@ The child can use one dedicated coordination tool:
 
 - `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
 
-Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side Atomic sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async terminal result. Intercom-confirmed foreground delivery returns a compact receipt with artifact/session paths; without that confirmation, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
-When the companion is enabled and available, the bridge gives eligible children deterministic Intercom identities and coordination tools without connecting them automatically. Parent and child connections remain tool-driven: if a child may need live coordination, the parent model should invoke `intercom({ action: "status" })` before launch, and the child connects when it invokes `contact_supervisor` or `intercom`. Foreground/background launch and management-only actions do not force Intercom loading or broker startup.
+Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side Atomic sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per detached child completion. Intercom-confirmed delivery returns a compact receipt with artifact/session paths; without that confirmation, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
+When the companion is enabled and available, the bridge gives eligible children deterministic Intercom identities and coordination tools without connecting them automatically. Parent and child connections remain tool-driven: if a child may need live coordination, the parent model should invoke `intercom({ action: "status" })` before launch, and the child connects when it invokes `contact_supervisor` or `intercom`. Foreground launches and management-only actions do not force Intercom loading or broker startup.
 
-For foreground runs, Intercom uses a targeted probe/reservation before delivery: only the exact live child can claim its message. Atomic then commits detach for that child and waits for its acknowledgement before placing claimed asks, sends, decisions, interviews, and progress updates in the parent's model-visible steering queue, so cancellation between phases cannot surface an orphaned request. Blocking calls remain alive for an exact threaded reply and then resume; fire-and-forget calls create no waiter. The retained child later replaces its detached status and artifacts with the real result. Cancellation/replacement invalidates stale handshakes, duplicate delivery cannot recommit, and background or unmatched messages retain queued-until-idle behavior.
+For foreground runs, Intercom uses a targeted probe/reservation before delivery: only the exact live child can claim its message. Atomic then commits detach for that child and waits for its acknowledgement before placing claimed asks, sends, decisions, interviews, and progress updates in the parent's model-visible steering queue, so cancellation between phases cannot surface an orphaned request. Blocking calls remain alive for an exact threaded reply and then resume; fire-and-forget calls create no waiter. The retained child later replaces its detached status and artifacts with the real result. Cancellation/replacement invalidates stale handshakes, duplicate delivery cannot recommit, and unmatched messages retain queued-until-idle behavior.
 
 If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
 
@@ -297,21 +293,14 @@ Append `[key=value,...]` to an agent name to override defaults for that step:
 |-----|---------|-------------|
 | `output` | `output=context.md` | Write results to a file. For `/parallel`, relative paths resolve against the child working directory; for `/run`, relative paths resolve against cwd. |
 | `outputMode` | `outputMode=file-only` | Return only a concise file reference for saved output instead of the full saved content. Requires `output`; default is `inline`. |
-| `reads` | `reads=a.md+b.md` | Read files before executing. `+` separates multiple paths. `/run` forwards these through the same resolver as tool-based foreground and background launches, so relative paths use the effective child working directory. |
+| `reads` | `reads=a.md+b.md` | Read files before executing. `+` separates multiple paths. `/run` forwards these through the same resolver as tool-based foreground launches, so relative paths use the effective child working directory. |
 | `model` | `model=anthropic/claude-sonnet-4` | Override model for this step. |
 | `skills` | `skills=planning+review` | Override injected skills. `+` separates multiple skills. |
 | `progress` | `progress` | Enable progress tracking. |
 
 Set `output=false`, `reads=false`, or `skills=false` to disable that behavior explicitly. Do not use `output=false` for file-only returns; use `outputMode=file-only` with an `output` path.
 
-### Background and forked runs
-
-Add `--bg` to run in the background:
-
-```text
-/run codebase-locator "audit the codebase" --bg
-/parallel codebase-locator "scan frontend" -> codebase-locator "scan backend" --bg
-```
+### Forked runs
 
 Add `--fork` to start each child from a real branched session created from the parent’s current leaf:
 
@@ -320,22 +309,11 @@ Add `--fork` to start each child from a real branched session created from the p
 /parallel codebase-locator "audit frontend" -> codebase-analyzer "audit backend" --fork
 ```
 
-You can combine them in either order:
-
-```text
-/run codebase-analyzer "review this diff" --fork --bg
-/run codebase-analyzer "review this diff" --bg --fork
-```
-
-Background runs use the same in-process continuation as foreground detach. A successful acknowledgement means the canonical child path was returned and completion is pending; the live child remains owned by the parent process and the jobs widget tracks it. **`async: true` does not survive parent exit.** If the parent exits, the in-flight run ends; its persisted identity/session can be listed and resumed later.
-
 `worker` is designed for an explicit decision loop. A typical pattern is to ask a read-only specialist such as `codebase-analyzer` or `debugger` for diagnosis and a recommended execution prompt, then only run `worker` after the main agent approves that direction.
 
 ## Non-interactive execution
 
-Every supported subagent launch starts immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, foreground, background, fanout, prompt-template, and human-entered `/run` and `/parallel` execution. Gather any needed context and ask the user questions in the parent conversation before launching.
-
-The human slash commands remain on their separate parsing and event-bridge path, including background and fork flags.
+Every supported subagent launch starts immediately without opening a preview/editor prompt or waiting for terminal input. This applies to single, parallel, forked, fanout, prompt-template, and human-entered `/run` and `/parallel` execution. Gather any needed context and ask the user questions in the parent conversation before launching.
 
 ## Agents
 
@@ -517,7 +495,7 @@ Missing skills do not fail execution. The result summary shows a warning.
 The package bundles a `subagent` skill that is automatically available to the parent agent when the extension is installed. It is for the orchestrating parent only: it is stripped from every child prompt, including fanout-authorized children, and child context is filtered to strip parent-only orchestration instructions. A child may still have the `subagent` tool registered; typed admission policy, not the skill, decides which of its actions are allowed.
 
 What the bundled skill covers:
-- **Delegation patterns**: when to launch which agent, whether to use single, parallel, or async mode, and whether to use fresh or forked context
+- **Delegation patterns**: when to launch which agent, whether to use single or parallel mode, and whether to use fresh or forked context
 - **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup
 - **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers
 - **Safety boundaries**: child agents must not run subagents, must not invent intercom targets, and must escalate unapproved decisions
@@ -615,7 +593,6 @@ Agent definitions are not loaded into context by default. Management actions let
 | `worktree` | boolean | false | Create isolated git worktrees for parallel tasks. |
 | `context` | `fresh \| fork` | agent default or `fresh` | `fork` creates real branched sessions from the parent leaf. Packaged `worker` defaults to `fork`; every other builtin runs fresh. |
 | `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
-| `async` | boolean | false | Background execution. Programmatic calls start without prompting in either foreground or background mode. |
 | `cwd` | string | runtime cwd | Override working directory. |
 | `maxOutput` | object | 200KB, 5000 lines | Final output truncation limits. |
 | `artifacts` | boolean | true | Write debug artifacts. |
@@ -639,7 +616,7 @@ subagent({ action: "resume", id: "<run-id>", index: 1, message: "follow-up for c
 subagent({ action: "doctor" })
 ```
 
-`resume` sends the follow-up directly when a child is still reachable. After completion or eviction, it cold-reloads the same canonical child identity from the stored session file. Multi-child async runs and remembered foreground single or parallel runs can be revived by passing `index` to choose the child; no new OS process is created.
+`resume` sends the follow-up directly when a child is still reachable. After completion or eviction, it cold-reloads the same canonical child identity from the stored session file. Remembered foreground single or parallel runs can be revived by passing `index` to choose the child; no new OS process is created.
 
 ## Worktree isolation
 
@@ -669,21 +646,7 @@ After a worktree parallel step completes, per-agent diff stats are appended to t
 
 Atomic subagents read optional JSON config from `~/.atomic/agent/extensions/subagent/config.json` and still check the legacy `~/.pi/agent/extensions/subagent/config.json` path for compatibility.
 
-### `asyncByDefault`
-
-```json
-{ "asyncByDefault": true }
-```
-
-Makes top-level calls use background execution when the request does not explicitly set `async`. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
-
-### `forceTopLevelAsync`
-
-```json
-{ "forceTopLevelAsync": true }
-```
-
-Forces depth-0 single and parallel runs into background mode. Calls remain non-interactive in both foreground and background mode; nested calls keep their own inherited settings.
+Subagent configuration controls discovery, parallel limits, session storage, depth, control notices, and intercom delivery. There are no execution-mode toggles; every execution request is foreground.
 
 ### `parallel`
 
@@ -769,9 +732,9 @@ Metadata records timing, usage, typed status, termination cause, final model, at
 
 Session files are stored under a per-run session directory. With `context: "fork"`, each child starts from the parent’s current leaf through the session manager; this is a real session fork, not an injected summary.
 
-Async completions notify only the originating session. The in-process status watch emits live lifecycle updates, and the extension consumes the terminal event to render completion notifications.
+Foreground completions notify the originating session. The in-process status watch emits live lifecycle updates, and the extension consumes the terminal event to render completion notifications.
 
-Async runs persist their durable session and user-facing artifacts beside the parent session:
+Foreground runs persist their session and user-facing artifacts beside the parent session:
 
 ```text
 {parent-session-dir}/subagent-artifacts/
@@ -782,7 +745,7 @@ Async runs persist their durable session and user-facing artifacts beside the pa
   run-history.jsonl
 ```
 
-The Rust registry and status watch power the widget and `subagent({ action: "status" })` output. Terminal delivery is an in-memory bounded envelope persisted once with typed `status`, `cause`, and `stats`; there is no `status.json`, `events.jsonl`, PID reconciler, result watcher, or claim pipeline.
+The Rust registry and status watch power `subagent({ action: "status" })` output. Terminal delivery is an in-memory bounded envelope persisted once with typed `status`, `cause`, and `stats`; there is no `status.json`, `events.jsonl`, PID reconciler, result watcher, or claim pipeline.
 
 ## Completion and output
 
@@ -800,7 +763,7 @@ For existing subagent integrations and agent definitions:
 
 Foreground runs show compact live progress for single and parallel modes: current tool, recent output, token counts, duration, activity freshness, current-tool duration, and artifact paths when available.
 
-File-based tracking and returned telemetry are separate. On a single-agent call, `progress: true` creates a run-scoped `progress.md` under isolated subagent artifact storage and asks the child to maintain it in foreground or background mode without writing `progress.md` into the child working directory. `progress: false` disables an agent's `defaultProgress`. `includeProgress: true` only adds detailed runtime progress data to the final foreground tool result; it does not enable the file.
+File-based tracking and returned telemetry are separate. On a single-agent call, `progress: true` creates a run-scoped `progress.md` under isolated subagent artifact storage and asks the child to maintain it without writing `progress.md` into the child working directory. `progress: false` disables an agent's `defaultProgress`. `includeProgress: true` only adds detailed runtime progress data to the final foreground tool result; it does not enable the file.
 
 Press `CTRL+O` to expand the full streaming view with complete output per step.
 
@@ -828,19 +791,13 @@ Configure a lower or equal limit with:
 
 The depth policy is typed admission state and is not inherited through an environment variable.
 
-## Events
-
-Async events:
-
-- `subagent:async-started`
-- `subagent:async-complete`
-
-Intercom delivery events:
+Completion and intercom events:
 
+- `subagent:complete`
 - `subagent:control-intercom`
 - `subagent:result-intercom`
 
-The in-process status watch emits `subagent:async-complete`; `src/extension/index.ts` registers the notification handler that consumes it. Control/attention events are surfaced as visible parent notices, and typed terminal records carry the canonical path, status, cause, and session statistics. With `pi-intercom`, needs-attention notices and grouped parent-side subagent result deliveries can reach the orchestrator over intercom.
+Foreground status/control events are surfaced as visible parent notices, and typed terminal records carry the canonical path, status, cause, and session statistics. With `pi-intercom`, needs-attention notices and grouped parent-side subagent result deliveries can reach the orchestrator over intercom.
 
 ## Prompt-template integration
 
@@ -889,9 +846,8 @@ The main runtime files are:
 | `src/agents/agents.ts` | Agent discovery and frontmatter parsing. |
 | `src/runs/foreground/subagent-executor.ts` | Main execution routing for single, parallel, management, status, interrupt, and doctor actions. |
 | `src/runs/foreground/execution.ts` | Core foreground `runSync` handling. |
-| `src/runs/background/subagent-runner.ts` | Detached async runner. |
-| `src/runs/background/async-execution.ts` | Background launch support. |
-| `src/runs/background/async-status.ts` | Status discovery and formatting for async runs. |
+| `src/runs/foreground/notify.ts` | Completion-notification delivery for a detached Intercom child. |
+| `src/runs/foreground/completion-notification.ts` | Local completion acknowledgement and ordering barrier for detached children. |
 | `src/shared/settings.ts` | Shared task behavior, instructions, and config helpers. |
 | `src/runs/shared/worktree.ts` | Git worktree isolation. |
 | `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |

package/dist/builtin/subagents/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.13-alpha.2",
+  "version": "0.9.13-alpha.4",
   "private": true,
-  "description": "Atomic extension for delegating tasks to subagents with parallel execution and background runs. Fork of: https://github.com/nicobailon/pi-subagents",
+  "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [
     "Norin Lavaee",
     "Alex Lavaee"

package/dist/builtin/subagents/prompts/parallel-cleanup.md

@@ -40,7 +40,7 @@ Both scouts are read-only; `codebase-analyzer` cannot edit. Their reports are re
 
 Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not cleanup scope; remove it before identifying the target. After synthesis, launch one async `code-simplifier` writer with only the fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
+In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not cleanup scope; remove it before identifying the target. After synthesis, launch one foreground `code-simplifier` writer with only the fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
 
 Without autofix mode, ask before applying fixes unless I already authorized addressing the cleanup feedback. End that request with a compact numbered menu, including when applicable:
 

package/dist/builtin/subagents/prompts/parallel-review.md

@@ -26,7 +26,7 @@ Use `/parallel-cleanup` instead for simplicity, slop, or verbosity angles. Every
 
 Synthesize fixes worth doing now, optional improvements, and ignored or deferred feedback with a short reason; assess findings rather than applying them blindly. Delegate only independent work too large for a handful of tool calls; do not delegate auditing your own work, and prefer one subagent over several. Parallelize independent reads; stay sequential when one result determines the next; synthesize after retrieval. Keep work within the requested scope.
 
-In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not review scope; remove it before identifying the target. After synthesis, launch one async writer—`debugger` for correctness/regression fixes or `code-simplifier` for cleanup-shaped feedback—with only the explicit fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
+In **autofix** mode, an invocation containing the exact word `autofix` uses it as workflow control, not review scope; remove it before identifying the target. After synthesis, launch one foreground writer—`debugger` for correctness/regression fixes or `code-simplifier` for cleanup-shaped feedback—with only the explicit fixes-worth-doing-now list as scope. Validate and summarize. Do not apply optional improvements unless explicitly requested; if no fixes are worth doing now, do not edit.
 
 Without autofix mode, ask before applying fixes unless I already authorized addressing review feedback. End that request with a compact numbered menu, including when applicable:
 

package/dist/builtin/subagents/prompts/review-loop.md

@@ -16,7 +16,7 @@ Use the `subagent` tool and specialist roles rather than a generic worker or rev
 
 Default to at most 3 review rounds unless I set another cap. A round is a fresh-context inspection of the current diff after a writer pass.
 
-If the invocation requests implementation, first launch one async writer for the approved scope: `debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work. If the current diff is already the target, begin with review. Launch the planned work as an async/background set of tasks or continue with follow-up runs after each completion. Because launches are non-interactive, resolve questions with me first. Use one writer against the active worktree at a time unless I explicitly request isolated worktrees.
+If the invocation requests implementation, first launch one foreground writer for the approved scope: `debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work. If the current diff is already the target, begin with review. Continue with follow-up runs after each completion. Because launches are non-interactive, resolve questions with me first. Use one writer against the active worktree at a time unless I explicitly request isolated worktrees.
 
 Each review round uses fresh context. Reviewers inspect repository instructions, relevant files, and the current diff directly, without main-conversation history, and cannot edit; explicitly put `debugger` in inspect-only mode. Choose angles from the change. Common angles are correctness/regressions, failure modes, and pattern fit; add external-spec or prior-decision coverage when applicable. Prefer three strong reviewers over many vague ones.
 
@@ -24,7 +24,7 @@ Delegate only independent work too large for a handful of tool calls; do not del
 
 After each round, synthesize blockers or scope/product/architecture decisions needing approval, fixes worth doing now, optional improvements, and feedback to ignore or defer with a short reason. Assess findings rather than applying them blindly. Pause for my approval before a writer acts on any unapproved product, scope, or architecture decision.
 
-An async implementation writer's handoff transitions into review; it is not final completion unless I requested writer-only work, review-only output, or a stop after implementation. When implementation is authorized and fixes are worth doing now, launch one async writer to apply only the synthesized fixes—`debugger` for correctness or `code-simplifier` for cleanup. Require it to preserve approved scope, run focused validation, and report changed files, commands with exit codes, validation evidence, surprises, and unfinished work.
+The implementation writer's handoff transitions into review; it is not final completion unless I requested writer-only work, review-only output, or a stop after implementation. When implementation is authorized and fixes are worth doing now, launch one foreground writer to apply only the synthesized fixes—`debugger` for correctness or `code-simplifier` for cleanup. Require it to preserve approved scope, run focused validation, and report changed files, commands with exit codes, validation evidence, surprises, and unfinished work.
 
 Run another review round after a fix only when it made material changes or addressed non-trivial findings. Do not loop for optional polish, speculative improvements, or already deferred findings.
 

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -2,7 +2,7 @@
 name: subagent
 description: |
   Delegate work to builtin or custom subagents with single-agent,
-  parallel, selective async, forked-context, and intercom-coordinated runs.
+  parallel, forked-context, and intercom-coordinated runs.
   Use for bounded specialist delegation where a single parent agent stays in
   control while subagents contribute locate, analyze, pattern-find, research,
   debug, or simplify passes.
@@ -22,7 +22,6 @@ Use this skill when bounded specialist delegation adds value and the parent shou
 - **Debug and fix**: use `debugger` for actual failures that need reproduction, root-cause diagnosis, and a validated patch; conceptual or exploratory debugging can stay inline.
 - **Refinement**: use `code-simplifier` to clean up recently changed code without altering behavior.
 - **Adversarial review**: compose read-only specialists (`codebase-analyzer`, `codebase-pattern-finder`, `debugger` in inspect-only mode, `codebase-online-researcher`) into a parallel review pass — there is no generic `reviewer` agent.
-- **Long-running bounded delegation**: selectively launch async/background runs when the result is independently useful; otherwise use foreground execution.
 - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked.
 - **Agent authoring**: create, update, or override agents for a project.
 
@@ -33,7 +32,7 @@ Humans often use the slash-command layer instead:
 
 - `/run` — launch a single agent
 - `/parallel` — launch top-level parallel tasks
-- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
+- `/subagents-doctor` — diagnose setup, execution paths, current session, and intercom bridge state
 
 Prefer the tool when you are writing agent logic. Prefer the slash commands when you are guiding a human through an interactive flow.
 
@@ -57,7 +56,7 @@ Use this when the user wants adversarial review of a diff, plan, issue, file, or
 
 ### 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 writer (`debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work), fresh-context specialist reviewers inspect the actual repo and diff, the parent synthesizes accepted fixes, and one writer applies them. Choose foreground or async for each bounded run based on whether the parent needs its result next or has independent useful work. The parent can express the sequence up front as a set of parallel tasks or continue with explicit follow-up runs after each completion. Programmatic runs are non-interactive, so resolve only material unanswered questions before launching. Treat a writer handoff as an intermediate state, not final completion, unless the user explicitly asked for writer-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.
+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 writer (`debugger` for correctness-shaped work or `code-simplifier` for refinement-shaped work), fresh-context specialist reviewers inspect the actual repo and diff, the parent synthesizes accepted fixes, and one writer applies them. Run each bounded call in the foreground so the parent receives the result before the next step. Programmatic runs are non-interactive, so resolve only material unanswered questions before launching. Treat a writer handoff as an intermediate state, not final completion, unless the user explicitly asked for writer-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 I set another cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
 
 ### Parallel research technique
 
@@ -105,8 +104,7 @@ Use this when unresolved requirements and genuinely missing repository context j
 
 ### 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 `codebase-analyzer` scouts 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 scout; otherwise inline the criteria. Both scouts are read-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. When the user opts to autofix, the parent launches one async `code-simplifier` writer with the synthesized fixes as its explicit scope.
-
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `codebase-analyzer` scouts 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 scout; otherwise inline the criteria. Both scouts are read-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. When the user opts to autofix, the parent launches one foreground `code-simplifier` writer with the synthesized fixes as its explicit scope.
 
 ## Builtin Agents
 
@@ -202,14 +200,13 @@ subagent({
 })
 ```
 
-Enable file-based progress tracking for foreground or async single-agent runs with `progress: true`. The child maintains a run-scoped `progress.md` under isolated subagent artifact storage without writing it into its effective `cwd`; `progress: false` disables an agent's `defaultProgress`. Omission inherits that default except for read-only tasks, and `artifacts: false` removes foreground progress storage after the child exits. This is distinct from `includeProgress: true`, which only returns detailed runtime telemetry in the final foreground result.
+Enable file-based progress tracking for foreground single-agent runs with `progress: true`. The child maintains a run-scoped `progress.md` under isolated subagent artifact storage without writing it into its effective `cwd`; `progress: false` disables an agent's `defaultProgress`. Omission inherits that default except for read-only tasks, and `artifacts: false` removes foreground storage after the child exits. This is distinct from `includeProgress: true`, which only returns detailed runtime progress data in the final foreground result.
 
 ```typescript
 subagent({
   agent: "debugger",
   task: "Implement the approved fix and validate it.",
   progress: true,
-  async: true
 })
 ```
 
@@ -254,39 +251,11 @@ Avoid duplicate output paths in parallel tasks. Concurrent children should not w
 Concurrent writers conflict. `code-simplifier` and `debugger` change files. Do not run two writers in parallel against the same worktree unless you isolate them with `worktree: true`.
 
 
-### Async/background
-
-Choose async/background mode selectively when delegated work is genuinely long-running or independently useful while the parent proceeds. Use foreground execution when the parent needs the result. This applies consistently to read-only specialists, writers, and parallel groups; keep the write path single-threaded in either mode.
-
-Async does not mean parallel writes. Do not edit the same active worktree while an async `debugger` or `code-simplifier` is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree.
-
-Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed. If there is no independent work left and you would only be running `sleep` or status polling commands to wait, end your turn instead. Pi will deliver the async completion when it arrives.
-
-```typescript
-subagent({
-  agent: "debugger",
-  task: "Run the full test suite, identify the failing test, and patch the root cause.",
-  async: true
-})
-```
-
-File-only output mode works for async single runs and top-level parallel task items. A compact saved-file reference is returned instead of the full saved content.
-
-For review fanout where the parent continues a local audit:
-
-```typescript
-const run = subagent({
-  agent: "codebase-analyzer",
-  task: "Review the current diff for correctness issues. Inspect files directly. Do not edit.",
-  async: true,
-  context: "fresh"
-})
-// Continue local inspection, then later call status with the returned id.
-```
+### Foreground execution and resume
 
-Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs.
+All subagent execution runs in the foreground and returns its result to the parent call. Parallel tasks may still run concurrently within one foreground invocation, and forked context still creates branched child sessions.
 
-Use `resume` for follow-up work after a delegated run:
+Use `resume` for a follow-up on a retained child:
 
 ```typescript
 subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
@@ -295,11 +264,10 @@ subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer
 
 Resume behavior:
 
-- If an async child is still running and reachable, `resume` sends the follow-up to that live child over intercom (only when the child carries an intercom bridge target).
-- If an async child has completed, `resume` revives it by starting a new async child from the persisted child session file.
-- Multi-child async runs require `index` unless only one running child is selectable.
-- Completed foreground single and parallel runs can also be revived by `index` while their run metadata remains in extension state.
-- Revive starts a new child process from the old session context; it does not restart the same OS process.
+- If a child is still running and reachable, `resume` sends the follow-up through its intercom route when available.
+- Completed foreground single and parallel runs can be revived by `index` while their run metadata remains in extension state.
+- A revived child starts a new in-process attempt from its persisted session file.
+- Multi-child runs require `index` unless only one child is selectable.
 - If the chosen child has no persisted `.jsonl` session file, resume fails and reports that directly.
 
 Use diagnostics when setup or child startup looks wrong:
@@ -308,13 +276,13 @@ Use diagnostics when setup or child startup looks wrong:
 subagent({ action: "doctor" })
 ```
 
-Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
+Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, current session context, and intercom bridge state.
 
 ### Subagent control
 
 Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck.
 
-Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
+Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs push this as a `subagent:control-event` event, and notification-worthy control events are inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
 
 Use soft interrupt when a child is clearly blocked or drifting and the parent needs to regain control:
 
@@ -347,7 +315,7 @@ If the run already has an active intercom bridge target, needs-attention notific
 
 ## Non-Interactive Execution
 
-Every supported subagent launch starts immediately without a preview/editor prompt or terminal input. This applies to single, parallel, foreground, background, fanout, prompt-template, and human-entered `/run` and `/parallel` execution.
+Every supported subagent launch starts immediately without a preview/editor prompt or terminal input. This applies to single, parallel, forked, fanout, prompt-template, and human-entered `/run` and `/parallel` execution.
 
 Resolve questions in the parent conversation before launching children. Use `interview` when the user must answer a question, then put the resolved scope and validation contract in the child task. Human slash commands retain their separate parsing and event-bridge path.
 
@@ -396,9 +364,8 @@ intercom({ action: "pending" })
 
 Message conventions:
 
-- `reason: "need_decision"` waits for the parent reply and returns it to the child.
 - `reason: "progress_update"` is non-blocking and should stay concise.
-- Child-side routine completion handoffs are not expected. With the intercom bridge active, parent-side subagents send grouped completion results through the intercom companion: one grouped message per foreground parent run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved.
+- Child-side routine completion handoffs are not expected. With the intercom bridge active, parent-side subagents send grouped completion results through the intercom companion: one grouped message per foreground parent run and one per detached child completion. Acknowledged delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved.
 
 Most agents should not call generic `intercom` directly unless bridge instructions provide a target and `contact_supervisor` is unavailable. Do not invent a target.
 
@@ -503,9 +470,9 @@ If a prompt-template extension is installed, additional user prompt templates ca
 
 ## Best Practices
 
-### Choose foreground or async intentionally
+### Choose foreground intentionally
 
-Use foreground runs when the result gates the parent's next action. Use `async: true` when a bounded delegated job is genuinely long-running or the parent has independent useful work to do. Do not launch background work merely because async is available, and do not duplicate a delegated job while waiting.
+Use foreground runs for every delegated call so the result gates the parent's next action. Do not duplicate a delegated job while waiting.
 
 ### Keep writes single-threaded by default
 
@@ -578,7 +545,7 @@ clarify when needed → validation contract → optional bounded discovery → o
 
 The validation contract defines completion before code is written: expected behavior, checks, commands or user flows to exercise, and evidence the writer should return. Keep it lightweight for small tasks, but make it explicit enough that reviewers and validators are checking the intended outcome rather than the writer’s own assumptions. Subagent runs do not carry a structured `acceptance` field, infer acceptance policies, inject acceptance-report prompts, or run acceptance gates; put any evidence requirements directly in the task text. Do not set removed acceptance config fields on `subagent()` calls, parallel task items, or agent frontmatter; move those requirements into the assigned task text instead.
 
-The first writer implements the approved change. When it runs in the background, the parent may continue independent inspection or validation prep, but not parallel edits to the same worktree. Treat the writer handoff as the transition into review, not as final completion, unless the user explicitly asked for writer-only work, review-only output, or to stop after implementation. Specialist reviewers inspect the resulting diff from fresh context when warranted. The final fix writer applies synthesized review fixes, then the parent looks over the final diff before completing. The parent may launch these steps as separate background or foreground runs. Ask only needed questions before a non-interactive launch.
+The first writer implements the approved change. The parent waits for its foreground handoff before review, and does not make parallel edits to the same worktree. Treat the writer handoff as the transition into review, not as final completion, unless the user explicitly asked for writer-only work, review-only output, or to stop after implementation. Specialist reviewers inspect the resulting diff from fresh context when warranted. The final fix writer applies synthesized fixes, then the parent looks over the final diff before completing. Ask only needed questions before a non-interactive launch.
 
 For complex or risky changes, increase review and validation fanout when user intent or correctness risk materially warrants it rather than automatically trusting one reviewer. Use distinct angles such as correctness/regressions (`codebase-analyzer`), failure-mode hunt (`debugger` inspect-only), pattern fit (`codebase-pattern-finder`), prior-decision conformance (`codebase-research-*`), and external-spec conformance (`codebase-online-researcher`). When reviewers find non-trivial issues or the fix writer touches many lines, consider another focused review round before final validation.
 
@@ -589,10 +556,10 @@ Keep orchestration authority in the parent session. Child subagents should not l
 1. Clarify only when needed. Use existing context first; gather missing code or research context selectively, then ask only unresolved questions that materially affect scope, completion criteria, constraints, or non-goals.
 2. Define the validation contract. State completion expectations before implementation: expected behavior, checks to run, user flows to exercise, and evidence required in the writer handoff. For UI, CLI, integration, or workflow changes, include at least one validator angle that uses the product the way a user would rather than only reading code.
 3. Plan when useful. For complex work, write a plan doc yourself and get approval before implementation. For simple work, confirm shared understanding and explicitly note why planning is skipped.
-4. Implement with one writer. After approval, launch `debugger` (for correctness-shaped work) or `code-simplifier` (for refinement-shaped work) in the foreground or selectively in the background with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
+4. Implement with one writer. After approval, launch `debugger` (for correctness-shaped work) or `code-simplifier` (for refinement-shaped work) in the foreground with a proper meta prompt that includes clarified requirements, relevant context, plan path or summary, the validation contract, and output expectations. While it runs, prepare validation or inspect adjacent code instead of editing the same worktree.
 5. Require a useful writer handoff. Ask the writer to report changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises or new risks, decisions made inside approved scope, and decisions needing parent approval.
 6. Review after implementation. After the writer completes, launch bounded fresh-context specialist reviewers when risk or user intent warrants it — `codebase-analyzer` for correctness/regressions, `debugger` (inspect-only) for failure-mode hunts, and `codebase-pattern-finder` for consistency. Add `codebase-online-researcher` for external-spec angles and `codebase-research-*` for prior-decision angles when the work calls for it. Use `output: false` unless review artifacts are explicitly needed.
-7. Synthesize, then run the fix writer when needed. Separate blockers, fixes worth doing now, optional improvements, and feedback to ignore/defer, then launch one foreground or background writer (`debugger` or `code-simplifier`) to apply accepted fixes when implementation is authorized. If reviewers found scope/product/architecture choices that were not approved, ask the user first instead of applying them.
+7. Synthesize, then run the fix writer when needed. Separate blockers, fixes worth doing now, optional improvements, and feedback to ignore/defer, then launch one foreground writer (`debugger` or `code-simplifier`) to apply accepted fixes when implementation is authorized. If reviewers found scope/product/architecture choices that were not approved, ask the user first instead of applying them.
 8. Review again when warranted. If the fix writer made substantial changes or addressed non-trivial findings, run another focused parallel review round before final validation.
 9. Validate and complete. After the fix writer and any follow-up review return, inspect the final diff yourself, run or confirm focused validation, update docs/changelog when relevant, and summarize what changed and why.
 
@@ -602,7 +569,6 @@ Example writer handoff after clarification and optional planning:
 subagent({
   agent: "debugger",
   task: "Implement the approved fix.\n\nClarified requirements:\n- ...\n\nPlan: see ~/Documents/docs/...-plan.md\n\nValidation contract:\n- ...\n\nReturn a handoff with changed files, what was implemented, what was left undone, commands run with exit codes, validation evidence, surprises/new risks, and decisions needing parent approval.",
-  async: true
 })
 ```
 
@@ -617,7 +583,6 @@ subagent({
   ],
   concurrency: 3,
   context: "fresh",
-  async: true
 })
 ```
 
@@ -627,7 +592,6 @@ Example fix writer after parallel reviews:
 subagent({
   agent: "debugger",
   task: "Apply the synthesized reviewer feedback below. Only apply fixes worth doing now; preserve user-approved scope; ask before unapproved product or architecture changes. Run focused validation and summarize what changed.\n\nReviewer synthesis:\n...",
-  async: true
 })
 ```
 
@@ -635,7 +599,7 @@ subagent({
 
 When implementation review is part of the requested shape, do not treat the first review as the final step: synthesize findings against user scope and the validation contract, then launch one writer for accepted fixes when implementation is authorized.
 
-When a writer completes, treat its handoff as an intermediate state when review is part of the requested shape. The next parent action is bounded review, then synthesis, then a fix writer if reviewers found fixes worth doing now. This can be planned as separate background or foreground runs.
+When a writer completes, treat its handoff as an intermediate state when review is part of the requested shape. The next parent action is bounded review, then synthesis, then a fix writer if reviewers found fixes worth doing now. Keep these calls in the foreground so each handoff is available before the next action.
 
 For explicit review-loop requests, repeat writer → fresh-specialist-reviewers → synthesized-fix-writer cycles until reviewers find no blockers or fixes worth doing now, remaining feedback is optional or intentionally deferred, an unapproved product/scope/architecture decision needs the user, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap.
 
@@ -664,7 +628,7 @@ subagent({ action: "list" })
 
 ```typescript
 subagent({ action: "doctor" })
-// Check runtime paths, async support, discovery counts, current session, and intercom bridge state.
+// Check runtime paths, execution support, discovery counts, current session, and intercom bridge state.
 ```
 
 **"Max subagent depth exceeded"**

package/dist/builtin/subagents/skills/tmux/SKILL.md

@@ -52,7 +52,7 @@ metadata:
 
 # tmux
 
-Use for existing interactive tmux sessions. For one-shot commands, use normal shell. For new non-interactive background jobs, use background execution.
+Use for existing interactive tmux sessions. For one-shot commands, use normal shell. When a command must outlive a tool call, start it inside an interactive tmux session; Atomic tools do not provide background execution.
 
 On Windows, use [psmux](https://github.com/psmux/psmux), the native Windows tmux-compatible multiplexer. psmux automatically provides the `tmux` alias, so keep using the `tmux` commands below; no command changes are needed.
 

package/dist/builtin/subagents/src/extension/control-notices.ts

@@ -6,8 +6,7 @@ export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
 
 export interface SubagentControlMessageDetails {
 	event: ControlEvent;
-	source?: "foreground" | "async";
-	asyncDir?: string;
+	source?: "foreground";
 	childIntercomTarget?: string;
 	noticeText?: string;
 }
@@ -52,7 +51,7 @@ function deliverControlNotice(input: {
 			display: true,
 			details: { ...input.details, childIntercomTarget, noticeText },
 		},
-		{ triggerTurn: input.details.source !== "foreground" },
+		{ triggerTurn: false },
 	);
 }