pi-orchestrator-config 4.24.2 → 4.26.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [4.26.0] - 2026-11-06
+
+- Async `chain` mode: steps run in sequence and each step's result is substituted into `{previous}`,
+  with per-step `taskId`/`cwd`, the step position in the status line and result header, a durable
+  `chain.json` for reload reporting, and stop-on-failure. `onComplete` receives `{ text, isError }` and
+  fires exactly once, so a retried reconciliation pass cannot spawn the next step twice.
+- A tool call pi rejects for invalid arguments now forces a retry. Such a call skips `tool_call` and
+  `tool_result`, so nothing told the model its action never ran and a turn could end silently. The guard
+  matches pi's own rejection preamble, keeps only the parameter diagnostics (argument values can hold
+  credentials and the system note is a provenance-marked channel), and names the likely mistake.
+- The UI bridge degrade path honours an approval again: without `ctx.ui.custom`, `confirm` returned a
+  boolean while the wrapper compared `"__confirmed__"`, so every prompt in that runtime cancelled.
+
+## [4.25.0] - 2026-11-06
+
+- `.pi/tmp` is cleaned at session start: above `project_tmp_max_size` (default `2G`), entries older than
+  `project_tmp_retention_days` (default 7 days) are deleted oldest-first until the tree fits, and `0`
+  disables it entirely. The sweep lock lives in `.pi/run` rather than in the directory being swept, a run
+  that cannot take the lock deletes nothing, an entry replaced mid-scan is skipped, and oneshot sessions
+  skip the whole thing. A bad size value deletes nothing rather than falling back to a deleting default.
+- Daemon control files moved to `.pi/run` — `pidiff.pid`, `pidiff.port`, and the `reload.flag` /
+  `reload.done` / `reload.pending` handshake. Readers fall back to `.pi/tmp` and `reload.done` is mirrored
+  back, so a daemon started before the upgrade is still found instead of a second one spawning on its
+  port. **The migration release needs exactly one manual `/reload`**: a session whose watcher was loaded
+  before the move cannot observe the new flag path. The old temp-dir reload files stay protected until no
+  pre-upgrade daemon remains.
+- The pending-task reminder keys on how long a task has actually been pending rather than on the first
+  60-second tick, so it no longer fires about a minute after creation. It measures the oldest active task,
+  treats an undated task as old so a fresh sibling cannot mask it, and covers `agentBusy` in tests.
+- `reviews fetch` approves on a clean findings catalog at the PR head instead of requiring a `completed`
+  Qodo session, so a legitimately skipped auto-run can approve. A run that is still in progress never does.
+  `reason` reports `no_findings`, `open_findings`, `not_at_head`, or `all_resolved` instead of always
+  claiming `all_resolved`, and the review-loop exit names which reviewer actually approved — a CodeRabbit
+  approval is no longer reported as Qodo's.
+
 ## [4.24.2] - 2026-11-04
 
 - Async work is tracked even when an agent starts it: the task trigger now covers work set in

package/README.md

@@ -12,9 +12,9 @@ Single extension that provides:
 
 | Feature                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Subagent tool**             | Delegate tasks to specialist agents (single, parallel, chain, async modes); optional `model` param for model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Subagent tool**             | Delegate tasks to specialist agents (single, parallel, chain, async, and async-chain modes); optional `model` param for model override. Chains also run async: every step needs its own `taskId` and `cwd`, each step receives the previous step's output as `{previous}`, and a failed step stops the chain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **`list_models`**             | List available models and providers for subagent model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). Async applies to chains too: step 1 spawns immediately and each step starts when the previous one ends. On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | **CLI / ACPX providers**      | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.84): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable. Missing context window / maxTokens / cost filled from models.dev (`~/.pi/pi-config/models.dev.json`, 1-day refresh). Cold-start default restore (#753): gates `startup`\|`resume` (`new` only when no model is selected), empty `enabledModels`, trusted project merge — see `docs/cli-provider.md`. Headless Cursor `--approve-mcps` when `CLI_APPROVE_MCPS` is set (`false` opts out) or the process is a sidecar (`SIDECAR_PORT`; `startSidecar()` stamps it while running and restores it on `close()`). Executable sidecar consumers should call `bindSidecarListenExit()` so bind/`stopped` fatals exit 1. Headless Gemini defaults `GEMINI_CLI_TRUST_WORKSPACE=true` and preserves an explicit parent value (including `false`). |
 | **`/async-status` command**   | Show status of background agents — select one for live output streaming, multi-select and kill (`x`), or kill everything (`a`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **`ask_user` tool**           | Structured user input with options and free-text — used by workflows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

package/extensions/orchestrator/async-agents.ts

@@ -35,6 +35,7 @@ import { setSlot } from "./status-bar.js";
 import { getSetting } from "./project-settings.js";
 import { substituteSettingsPlaceholders } from "./rule-placeholders.js";
 import { isLiveExtensionCtx } from "../shared/live-ctx.js";
+import { sendSystemNote } from "../shared/system-note.js";
 
 const SETTINGS_KEYS: Record<string, unknown> = JSON.parse(
   fs.readFileSync(
@@ -66,7 +67,8 @@ export interface AsyncJob {
   delivered?: boolean;
   sideEffectsApplied?: boolean;
   fireAndForget?: boolean;
-  onComplete?: () => void;
+  /** One-shot: fires once with the ingested result text. Used by async chains to feed {previous}. */
+  onComplete?: (result: { text: string; isError: boolean }) => void;
   groupId?: string;
   taskId?: string;
   cwd?: string;
@@ -87,6 +89,26 @@ export interface AsyncJob {
  */
 export type AsyncKillOrigin = "user" | "orchestrator" | "task-system";
 
+/** Durable record of an async chain's position, written into each step's workerDir
+ *  as chain.json. The step's continuation lives in the onComplete closure, which a
+ *  reload destroys — this file is what lets restoration report the chain instead of
+ *  dropping it silently. */
+export interface AsyncChainState {
+  steps: Array<{ agent: string; task: string }>;
+  /** Index (0-based) of the step being spawned when this was written. */
+  index: number;
+  previous: string;
+  /** Set once restoration has reported this chain as interrupted. */
+  interruptedAt?: number;
+}
+
+function readChainState(workerDir: string): AsyncChainState | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(workerDir, "chain.json"), "utf-8"));
+    return Array.isArray(parsed?.steps) ? parsed as AsyncChainState : null;
+  } catch { return null; }
+}
+
 /** Human-readable attribution per origin. The single source for every surface. */
 export const KILL_ORIGIN_LABELS: Record<AsyncKillOrigin, string> = {
   user: "Killed by user",
@@ -99,6 +121,32 @@ function jobCwd(job: { cwd?: string; projectCwd?: string }): string {
   return job.cwd || job.projectCwd || process.cwd();
 }
 
+/** Fire the job's completion hook exactly once, with the already-ingested result.
+ *  Clearing it first stops the reconciliation pass from re-firing it (which would
+ *  spawn the next async-chain step twice after a failed delivery). */
+export function fireOnComplete(job: AsyncJob): void {
+  const cb = job.onComplete;
+  job.onComplete = undefined;
+  if (!cb) return;
+  try {
+    cb({ text: typeof job.output === "string" ? job.output : "", isError: job.status === "failed" });
+  } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
+}
+
+/** Fire every pending completion hook in one reconciliation pass.
+ *  Returns how many fired. Exported so the PASS is testable, not just the
+ *  single-job helper — the hook-once guarantee is a property of the loop. */
+export function firePendingCompletions(jobs: Iterable<AsyncJob>): number {
+  let fired = 0;
+  for (const job of jobs) {
+    if (!job.onComplete) continue;
+    fireOnComplete(job);
+    fired++;
+  }
+  if (fired > 0) log.info("fire_pending_completions", { fired });
+  return fired;
+}
+
 interface AsyncState {
   jobs: Map<string, AsyncJob>;
   poller: ReturnType<typeof setInterval> | null;
@@ -145,7 +193,7 @@ export function registerAsyncAgents(
     discoverAgents?: (cwd: string, scope: "both") => Pick<AgentDiscoveryResult, "agents">;
   } = {},
 ): {
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string };
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: (result: { text: string; isError: boolean }) => void; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState }) => { id: string; error?: string; model?: string };
   killAsyncAgent: (target: string, origin?: AsyncKillOrigin) => { killed: string[]; errors: string[] };
   getAsyncJobs: () => Array<{ id: string; agent: string; name?: string; task: string; status: string; startedAt: number }>;
 } {
@@ -625,9 +673,7 @@ export function registerAsyncAgents(
                   content: msgContent,
                   display: true,
                 }, { triggerTurn: true, deliverAs: "followUp" });
-                if (job.onComplete) {
-                  try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-                }
+                fireOnComplete(job);
                 job.delivered = true;
                 recordDelivered(job.id);
                 log.debug("reconcile_deliver_ok", job.id);
@@ -646,9 +692,7 @@ export function registerAsyncAgents(
               } catch {}
             }
           } else if (job.fireAndForget) {
-            if (job.onComplete) {
-              try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-            }
+            fireOnComplete(job);
             job.delivered = true;
           }
         }
@@ -719,12 +763,8 @@ export function registerAsyncAgents(
 
     // Skip delivery if ALL jobs in group are fire-and-forget
     if (groupJobs.every(j => j.fireAndForget)) {
-      for (const j of groupJobs) {
-        if (j.onComplete) {
-          try { j.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${j.id}: ${e?.message}`); }
-        }
-        j.delivered = true;
-      }
+      firePendingCompletions(groupJobs);
+      for (const j of groupJobs) j.delivered = true;
       // Clean up result files for fire-and-forget groups
       for (const j of groupJobs) {
         const rp = path.join(ASYNC_RESULTS_DIR, `${j.id}.json`);
@@ -986,10 +1026,8 @@ export function registerAsyncAgents(
         sendSucceeded = true; // fire-and-forget doesn't need sendMessage
       }
 
-      // Invoke onComplete callback if registered (e.g., dreaming → rebuildAndOrganize)
-      if (job.onComplete) {
-        try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-      }
+      // Invoke onComplete callback if registered (e.g., dreaming, async chain step)
+      fireOnComplete(job);
       if (sendSucceeded) {
         job.delivered = true;
         // Persist delivered state so restore skips this job
@@ -1035,7 +1073,7 @@ export function registerAsyncAgents(
     task: string,
     cwd: string,
     agents: AgentConfig[],
-    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } },
+    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: (result: { text: string; isError: boolean }) => void; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState },
   ): { id: string; error?: string; model?: string } {
     const agent = agents.find(a => a.name === agentName);
     if (!agent) return { id: "", error: `Unknown agent: "${agentName}"` };
@@ -1070,6 +1108,12 @@ export function registerAsyncAgents(
       sessionId: getLiveAsyncCtx()?.sessionManager?.getSessionId?.() || null,
     }), { mode: 0o600 });
 
+    // Chain position — a reload drops the onComplete continuation, so restore reads
+    // this file to report the chain it can no longer resume instead of losing it.
+    if (options?.chain) {
+      fs.writeFileSync(path.join(workerDir, "chain.json"), JSON.stringify(options.chain), { mode: 0o600 });
+    }
+
     // Track reviewer spawn BEFORE building args — addReviewerPending sets status to
     // in_progress, so all reviewers in the same batch see consistent state.
     if (agentName.startsWith("code-reviewer-")) {
@@ -1516,6 +1560,22 @@ export function registerAsyncAgents(
           };
           asyncState.jobs.set(id, job);
           log.info(`restored job: ${id} state=${job.status}`);
+
+          // A chain's continuation lived in the onComplete closure this reload destroyed.
+          // chain.json records what was still pending — report it, never drop it silently.
+          const chain = readChainState(job.workerDir);
+          if (chain && chain.interruptedAt === undefined && chain.index + 1 < chain.steps.length) {
+            const remaining = [...new Set(chain.steps.slice(chain.index + 1).map(s => s.agent))];
+            log.error(`async_chain_interrupted: chain interrupted at step ${chain.index + 1} of ${chain.steps.length} (${job.agent}), remaining agents: ${remaining.join(", ")}`);
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain interrupted at step ${chain.index + 1} of ${chain.steps.length} — the extension reloaded, so the chain cannot continue. Step ${chain.index + 1} (${job.agent}) may still be running; steps ${chain.index + 2}-${chain.steps.length} were never spawned. Remaining agents: ${remaining.join(", ")}. Re-run them with subagent(chain: ...).`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            ).catch((e: any) => log.error(`chain_interrupted note failed: ${e?.message || e}`));
+            // Durable so a second reload does not repeat the note.
+            chain.interruptedAt = Date.now();
+            try { fs.writeFileSync(path.join(job.workerDir, "chain.json"), JSON.stringify(chain), { mode: 0o600 }); } catch {}
+          }
         }
       }
     } catch (e: any) { log.error(`job restore failed: ${e?.message || e}`); }

package/extensions/orchestrator/index.ts

@@ -19,9 +19,11 @@ import { registerAskUser } from "./ask-user.js";
 import { registerAsyncAgents } from "./async-agents.js";
 import { registerDreaming } from "./dreaming.js";
 import { registerEnforcement } from "./enforcement.js";
+import { registerToolArgGuard } from "./tool-arg-guard.js";
 import { registerProjectSettings } from "./project-settings.js";
 import { registerRules } from "./rules.js";
 import { registerSessionValidation } from "./session-validation.js";
+import { registerTmpCleanup } from "./tmp-cleanup.js";
 import { registerStatusLine } from "./status-line.js";
 import { registerSubagentTool } from "./subagent-tool.js";
 import { registerGithubAutocomplete } from "./github-autocomplete.js";
@@ -131,6 +133,8 @@ export default function (pi: ExtensionAPI) {
   registerProjectSettings(pi);
   registerTrail(pi);
   registerEnforcement(pi, IN_CONTAINER);
+  // A rejected-before-run tool call must force a retry, not end the turn silently.
+  registerToolArgGuard(pi);
   registerReviewUI(pi);
   registerRules(pi, getAsyncJobs);
 
@@ -144,6 +148,7 @@ export default function (pi: ExtensionAPI) {
   registerPreferenceExtractor(pi);
   registerMemoryTools(pi);
   registerReviewLearning(pi);
+  registerTmpCleanup(pi);
   registerSessionSearch(pi);
   registerSettingsTui(pi);
   registerMarkdownTransformer(pi);

package/extensions/orchestrator/subagent-tool.ts

@@ -31,6 +31,7 @@ import {
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
+import type { AsyncChainState } from "./async-agents.js";
 
 // Task store access via the pitasks module.
 // `taskStore` is `export let` — a live binding the pitasks extension assigns when it
@@ -107,6 +108,23 @@ const SYNC_TIME_EXCEEDED_ERROR = (seconds: number, limit: number, cwd: string) =
 };
 const MISSING_ESTIMATE_ERROR = "Missing required parameter: estimatedSeconds. Provide an estimated duration in seconds for sync agent tasks.";
 
+/** Cap for the {previous} substitution: the whole task becomes ONE argv entry, so a
+ *  large result would blow past ARG_MAX and fail the next step's spawn. */
+const MAX_PREVIOUS_CHARS = 32_000;
+
+/** Truncate a step result for the next step, saying how much was dropped. */
+function capPrevious(previous: string): string {
+  const dropped = previous.length - MAX_PREVIOUS_CHARS;
+  if (dropped <= 0) return previous;
+  return `${previous.slice(0, MAX_PREVIOUS_CHARS)}\n\n[truncated: ${dropped} of ${previous.length} chars dropped to keep the next step's task argument under the OS limit]`;
+}
+
+/** Substitute {previous} literally — String.replace would expand $&, $$, $' and $` in the result. */
+function withPrevious(task: string, previous: string): string {
+  if (!task.includes("{previous}")) return task;
+  return task.split("{previous}").join(capPrevious(previous));
+}
+
 let syncPenalty = 0;
 let lastSyncAgent = "";
 let lastSyncEstimate = 0;
@@ -139,6 +157,7 @@ const ChainItem = Type.Object({
   }),
   cwd: Type.String({ description: "Working directory" }),
   estimatedSeconds: Type.Number({ description: "Estimated step duration in seconds" }),
+  taskId: Type.Optional(Type.String({ description: "Task ID to auto-complete when this async chain step finishes" })),
 });
 // pi 1.5.0's StringEnum returns a pi-schema Schema, which TypeBox's Static cannot
 // read — params.agentScope degraded to `unknown`. Unsafe keeps the JSON-Schema
@@ -638,7 +657,7 @@ async function validateTaskId(taskId: string, _cwd: string, _sessionId?: string)
 
 export function registerSubagentTool(
   pi: ExtensionAPI,
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string },
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState; onComplete?: (result: { text: string; isError: boolean }) => void }) => { id: string; error?: string; model?: string },
   killAsyncAgent: (target: string, origin?: AsyncKillOrigin) => { killed: string[]; errors: string[] },
 ): void {
   // Only the orchestrator (top-level pi) can spawn subagents.
@@ -668,6 +687,130 @@ export function registerSubagentTool(
     };
   }
 
+  /** Async chain — spawns step 1, and each step's completion hook spawns the next
+   *  with {previous} replaced by that step's result text. */
+  async function executeAsyncChain(
+    params: any,
+    agents: AgentConfig[],
+    mkd: (mode: "single" | "parallel" | "chain") => (results: SingleResult[]) => SubagentDetails,
+    parentModelId: string | undefined,
+    parentProvider: string | undefined,
+    ctx: any,
+    explicit?: { model?: string; provider?: string },
+  ) {
+    const steps = (params.chain ?? []) as Array<{ agent: string; task: string; cwd: string; taskId?: string }>;
+    const total = steps.length;
+    const fail = (text: string) => ({
+      content: [{ type: "text" as const, text }],
+      details: mkd("chain")([]),
+      isError: true,
+    });
+
+    if (total === 0) return fail("Error: chain array is empty — at least one step is required.");
+    for (let i = 0; i < total; i++) {
+      const s = steps[i];
+      if (!s.agent || !s.task) return fail(`Async chain step ${i + 1} requires both agent and task.`);
+      if (!s.cwd) return fail(`${MISSING_CWD_ERROR} (chain step ${i + 1}, agent: ${s.agent})`);
+      if (s.taskId == null) {
+        // Force a follow-up turn so the AI MUST deal with this error, as the other async paths do
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: Async chain call was REJECTED — missing taskId for step ${i + 1} (${s.agent}). NO agents were spawned. You MUST retry with a taskId on every chain step. Use TaskList to find task IDs; "-1" is only for a single read-only check.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
+        return fail(`Missing required parameter: taskId. Every async agent MUST have a taskId (chain step ${i + 1}, agent: ${s.agent}).\n\nIf this step is working on a task: pass the task ID (e.g., taskId: "5")\nIf it is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)`);
+      }
+      const taskErr = await validateTaskId(s.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+      if (taskErr) {
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: ${taskErr} (chain step ${i + 1}, agent: ${s.agent}). NO agents were spawned. Fix the taskId and retry.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
+        return fail(`${taskErr} (chain step ${i + 1}, agent: ${s.agent})`);
+      }
+    }
+    if (syncPenalty > 0) {
+      log.info("sync_penalty_reset", "async chain used");
+      syncPenalty = 0;
+    }
+
+    /** Step names carry the position so the status line and result header say which step ran. */
+    const stepName = (i: number): string =>
+      i === 0 && params.name ? params.name : `${steps[i].agent} (chain ${i + 1}/${total})`;
+
+    /** A step's cwd may hold project agents the parent's cwd does not — discover per step. */
+    const stepAgents = (cwd: string): AgentConfig[] => discoverAgents(cwd, params.agentScope ?? "both").agents;
+
+    const spawnStep = (i: number, prev: string): { id: string; error?: string; model?: string } => {
+      const s = steps[i];
+      const name = stepName(i);
+      log.info("async_chain_step_spawn", { step: i + 1, total, agent: s.agent, name });
+      return spawnAsyncAgent(s.agent, withPrevious(s.task, prev), s.cwd, stepAgents(s.cwd), {
+        name,
+        parentModelId,
+        parentProvider,
+        taskId: s.taskId,
+        persistSession: params.persistSession,
+        explicit,
+        // Durable so a reload can report the chain it can no longer continue.
+        chain: {
+          steps: steps.map(st => ({ agent: st.agent, task: st.task })),
+          index: i,
+          previous: capPrevious(prev),
+        },
+        onComplete: (result) => {
+          if (result.isError) {
+            // Chain stops here — the delivered async result header names this step.
+            log.error("async_chain_step_failed", { step: i + 1, total, agent: s.agent, name, output: result.text.slice(0, 200) });
+            return;
+          }
+          log.info("async_chain_step_complete", { step: i + 1, total, agent: s.agent, name, output_chars: result.text.length });
+          if (i + 1 >= total) {
+            log.info("async_chain_done", { steps: total });
+            return;
+          }
+          log.info("async_chain_next_step", { from: i + 1, to: i + 2, agent: steps[i + 1].agent });
+          let next: { id: string; error?: string; model?: string };
+          try {
+            next = spawnStep(i + 1, result.text);
+          } catch (err) {
+            // A synchronous throw must not escape the completion hook — the chain is dead either way.
+            const reason = String((err as Error)?.message ?? err);
+            log.error("async_chain_next_step_spawn_failed", { step: i + 2, agent: steps[i + 1].agent, error: reason });
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain stopped: step ${i + 2} (${steps[i + 1].agent}) could not be spawned after step ${i + 1} completed — ${reason}`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            );
+            return;
+          }
+          if (next.error) {
+            log.error("async_chain_next_step_spawn_failed", { step: i + 2, agent: steps[i + 1].agent, error: next.error });
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain stopped: step ${i + 2} (${steps[i + 1].agent}) could not be spawned after step ${i + 1} completed — ${next.error}`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            );
+          } else {
+            log.info("async_chain_next_step_spawned", { step: i + 2, id: next.id });
+          }
+        },
+      });
+    };
+
+    const first = spawnStep(0, "");
+    if (first.error) return fail(`Async chain step 1 (${steps[0].agent}) failed to spawn: ${first.error}`);
+    const modelInfo = first.model ? ` (${first.model})` : "";
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Async chain started: ${stepName(0)} [${first.id}]${modelInfo}\n${total} step(s) run in sequence — each step receives the previous step's output as {previous}.\nA failed step stops the chain and is named in its result.\nUse /async-status to check progress.`,
+      }],
+      details: mkd("chain")([]),
+    };
+  }
+
   async function executeAsync(
     params: any,
     agents: AgentConfig[],
@@ -678,11 +821,7 @@ export function registerSubagentTool(
     explicit?: { model?: string; provider?: string },
   ) {
     if (params.chain) {
-      return {
-        content: [{ type: "text" as const, text: "Async mode does not support chain. Use agent + task or tasks array." }],
-        details: mkd("single")([]),
-        isError: true,
-      };
+      return executeAsyncChain(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
     }
 
     // Parallel async — spawn each task as a separate async agent
@@ -1628,9 +1767,14 @@ export function registerSubagentTool(
         const violators = [...new Set(requested.filter(n => ASYNC_ONLY_AGENTS.has(n)))];
         if (violators.length > 0) {
           const inChain = params.chain?.some(s => ASYNC_ONLY_AGENTS.has(s.agent));
-          if (inChain) {
+          // An async chain satisfies the async-only requirement; anything that would run the
+          // steps in the foreground (sync chain, or an acpx parent that coerces async→sync) cannot.
+          if (inChain && (params.async !== true || !asyncOk)) {
+            const why = params.async !== true
+              ? "a sync chain runs its steps in the foreground"
+              : `the parent provider cannot spawn async agents (${parentProvider ?? "unknown"})`;
             return {
-              content: [{ type: "text", text: `These agents cannot be used in chain mode: ${violators.join(", ")}. Dispatch them as separate async tasks instead.` }],
+              content: [{ type: "text", text: `These agents can only run async, and ${why}: ${violators.join(", ")}. Async chain needs async: true on a provider that supports async agents.` }],
               details: mkd("single")([]),
               isError: true,
             };
@@ -1670,14 +1814,45 @@ export function registerSubagentTool(
         if (params.chain) for (const s of params.chain) requested.add(s.agent);
         if (params.tasks) for (const t of params.tasks) requested.add(t.agent);
         if (params.agent) requested.add(params.agent);
-        const projAgents = Array.from(requested)
-          .map((n) => agents.find((a) => a.name === n))
-          .filter((a): a is AgentConfig => a?.source === "project");
+        // A chain step carries its own cwd, so it can resolve a DIFFERENT project agent set
+        // than the parent's — including a project agent that shadows a user agent of the
+        // same name. Resolve every step against its own cwd or the approval is bypassed.
+        const projAgents: AgentConfig[] = [];
+        const sources: string[] = [];
+        for (const name of requested) {
+          const parentAgent = agents.find((a) => a.name === name);
+          if (parentAgent?.source === "project") {
+            projAgents.push(parentAgent);
+            if (discovery.projectAgentsDir) sources.push(discovery.projectAgentsDir);
+          }
+        }
+        // Async chains resolve agents per step, so a step's own cwd can contribute a
+        // project agent — including one that SHADOWS a parent user agent of the same name.
+        // Sync chains still resolve against the parent list, so asking about their steps
+        // would prompt for an agent that never runs.
+        if (params.async === true) {
+          // Structured key: a "@" join is ambiguous when a name or path contains "@".
+          const seen = new Set(projAgents.map((a) => JSON.stringify([a.name, discovery.projectAgentsDir ?? ""])));
+          for (const step of params.chain ?? []) {
+            if (!step.cwd || step.cwd === ctx.cwd) continue;
+            const stepDiscovery = discoverAgents(step.cwd, scope);
+            const stepAgent = stepDiscovery.agents.find((a) => a.name === step.agent);
+            if (stepAgent?.source !== "project") continue;
+            // Dedupe on name+directory: the same name in a second project dir is a
+            // DIFFERENT agent and its source must appear in the prompt.
+            const key = JSON.stringify([stepAgent.name, stepDiscovery.projectAgentsDir ?? ""]);
+            if (seen.has(key)) continue;
+            seen.add(key);
+            projAgents.push(stepAgent);
+            if (stepDiscovery.projectAgentsDir) sources.push(stepDiscovery.projectAgentsDir);
+          }
+        }
         if (projAgents.length > 0) {
+          const uniqueSources = [...new Set(sources)];
           const ok = await bridgedUi.confirm(
             ctx,
             "Run project-local agents?",
-            `Agents: ${projAgents.map((a) => a.name).join(", ")}\nSource: ${discovery.projectAgentsDir}`,
+            `Agents: ${projAgents.map((a) => a.name).join(", ")}\nSource: ${uniqueSources.join(", ")}`,
           );
           if (!ok)
             return {