@bermudi/pi-delegate 0.1.1 → 0.1.2

package/README.md

@@ -126,8 +126,9 @@ over an installed extension.
 - **Resumed subagent** — A subagent rehydrated from a previous session `.jsonl`
   via `resumeFrom`. It can also be pooled by providing a `sessionId`.
 - **Async ticket** — A background execution handle returned when top-level
-  `async: true` is used. Poll or cancel tickets with top-level `action: "poll"`
-  or `action: "cancel"`.
+  `async: true` is used. Poll, wait, or cancel tickets with top-level
+  `ticketAction: "poll"`, `ticketAction: "wait"` (blocks until the ticket settles;
+  optional `timeoutMs`), or `ticketAction: "cancel"`.
 - **Skill** — A `SKILL.md` instruction bundle injected into the subagent system
   prompt. Skills are text instructions only; they do not unlock additional
   tools.

package/agents.ts

@@ -75,11 +75,15 @@ export function parseFrontmatter(
 
   // A bare `*` is a YAML alias indicator and is invalid as a scalar, so
   // `tools: *` (the full-agent shorthand) would throw. Quote any value that is
-  // exactly `*` so it parses as the string "*", which resolveFrontmatterTools
-  // then expands via TOOL_GROUPS. (A `*` mid-scalar, e.g. `use * here`, is a
-  // legal plain scalar and needs no quoting.)
+  // exactly `*`, including when it has a trailing YAML comment, so it parses
+  // as the string "*", which resolveFrontmatterTools then expands via
+  // TOOL_GROUPS. (A `*` mid-scalar, e.g. `use * here`, is a legal plain scalar
+  // and needs no quoting.)
   const sanitized = sanitizeYamlScalars(
-    yamlString.replace(/^(\s*[\w-]+):\s*\*(?=\s*$)/gm, '$1: "*"'),
+    yamlString.replace(
+      /^([ \t]*[\w-]+:[ \t]*)\*([ \t]*(?:#[^\r\n]*)?)(?=\r?$)/gm,
+      '$1"*"$2',
+    ),
   );
 
   try {
@@ -140,11 +144,13 @@ const CLAUDE_TOOL_ALIASES: Record<string, string> = {
 
 /** Parse a `tools:` frontmatter value into a resolved tool list.
  *  Omitted or blank → inherit the full agent set (`*`), matching CC/OpenCode/
- *  Devin convention. This is the only caller-owned knob — both inline tasks
- *  and named agents now inherit-all when `tools:` is absent. */
+ *  Devin convention. For Claude imports (`aliasMap` set), an explicit
+ *  allowlist that maps to an empty set means the agent gets no tools, with a
+ *  warning, instead of silently inheriting anything. */
 function resolveFrontmatterTools(
   raw: string | undefined,
   aliasMap?: Record<string, string>,
+  filePath?: string,
 ): string[] {
   if (!raw) return DEFAULT_TOOLS; // omitted/blank → inherit *
   const names = raw
@@ -154,11 +160,25 @@ function resolveFrontmatterTools(
   if (!names.length) return DEFAULT_TOOLS;
   const mapped = aliasMap
     ? names
-        .map((n) => aliasMap[n.toLowerCase()] ?? null)
+        .map((n) => {
+          const lower = n.toLowerCase();
+          // Preserve delegate tool-group shorthands when importing Claude files.
+          if (lower === "*" || lower === "ro") return lower;
+          return aliasMap[lower] ?? null;
+        })
         .filter((n): n is string => n !== null)
     : names;
-  // Empty after aliasing (e.g. a Claude agent listing only WebSearch) → inherit.
-  return mapped.length ? resolveToolGroups(mapped) : DEFAULT_TOOLS;
+  // Empty after aliasing (e.g. a Claude agent listing only WebSearch) must not
+  // silently inherit the full mutating set. An explicit allowlist that maps to
+  // nothing means the agent gets no tools.
+  if (!mapped.length) {
+    const where = filePath ? ` (${filePath})` : "";
+    console.warn(
+      `[delegate] Claude agent allowlist contained no mappable tools${where}; agent will have no tools.`,
+    );
+    return [];
+  }
+  return resolveToolGroups(mapped);
 }
 
 /** Parse and alias a comma-separated Claude tool list into delegate tool names,
@@ -201,15 +221,19 @@ export function loadAgentFile(filePath: string): AgentConfig | null {
   };
 }
 
-/** Variant for `.claude/agents/*.md` files. Two Claude-specific adaptations:
+/** Variant for `.claude/agents/*.md` files. Claude-specific adaptations:
  *  - Maps capitalized tool names (Read/Glob/…) to delegate tools, dropping
  *    unmappable ones (WebSearch, TodoWrite, …). Omitted `tools` inherits `*`.
  *  - Honors `disallowedTools` as a denylist layered on top of the resolved
  *    set (Claude semantics: denylist applies whether or not an allowlist is
  *    set). Since delegate has no runtime denylist, we bake it into `tools` at
- *    import time. A reviewer with `disallowedTools: Write, Edit` and no
- *    `tools` becomes `read, bash, grep, find, ls` — it does NOT silently
- *    inherit full tools.
+ *    import time. `bash` is special: in the delegate tool set it subsumes
+ *    `grep`/`find`/`ls` (a shell can run all of them), so an imported `Bash`
+ *    resolves to `bash` alone. If the denylist then removes `Bash` from an
+ *    inherited (omitted) allowlist, the dedicated read-only search tools it
+ *    was subsuming are restored. If the user explicitly allowlisted `Bash`,
+ *    removing it gives them no extra tools — they never asked for `grep`,
+ *    `find`, or `ls`.
  *  - `model: inherit` (Claude's default) is mapped to "omit" so the agent
  *    inherits the parent model; passing it through verbatim would crash
  *    resolveModel() with "model 'inherit' is not available". */
@@ -223,11 +247,32 @@ export function loadClaudeAgentFile(filePath: string): AgentConfig | null {
   const { data, body } = parseFrontmatter(content, filePath);
   if (!data.name || !data.description) return null;
 
-  let tools = resolveFrontmatterTools(data.tools, CLAUDE_TOOL_ALIASES);
+  // Track whether the user wrote an explicit `tools:` allowlist. Omitted or
+  // blank means "inherit the full default set" (`*`), and only in that case
+  // does denying `bash` restore the search tools it was subsuming.
+  const explicitTools = data.tools != null && data.tools.trim() !== "";
+  let tools = resolveFrontmatterTools(
+    data.tools,
+    CLAUDE_TOOL_ALIASES,
+    filePath,
+  );
   // disallowedTools is a denylist applied after the allowlist resolves.
-  // Empty-after-mapping denylist (e.g. only unmappable names) → no-op.
+  // `bash` subsumes `grep`/`find`/`ls`: if the denylist removes `bash` from an
+  // inherited (omitted) allowlist, restore the dedicated read-only search
+  // tools it was covering, but only the ones not already present and not also
+  // explicitly denied. If `bash` came from an explicit allowlist, do not add
+  // search tools the user never requested.
   const denied = new Set(mapClaudeToolNames(data.disallowedTools));
-  if (denied.size) tools = tools.filter((t) => !denied.has(t));
+  if (denied.size) {
+    const hadBash = tools.includes("bash");
+    tools = tools.filter((t) => !denied.has(t));
+    if (hadBash && !tools.includes("bash") && !explicitTools) {
+      const restored = ["grep", "find", "ls"].filter(
+        (t) => !tools.includes(t) && !denied.has(t),
+      );
+      if (restored.length) tools = tools.concat(restored);
+    }
+  }
 
   return {
     name: data.name,
@@ -324,6 +369,95 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
 export const DEFAULT_SUBAGENT_SYSTEM_PROMPT =
   "You are a helpful coding assistant.";
 
+/** First line of Pi's default generated system prompt. Used to detect an
+ *  inherited fully-assembled parent prompt that contains a stale tool
+ *  inventory. */
+const PI_DEFAULT_PROMPT_PREFIX =
+  "You are an expert coding assistant operating inside pi, a coding agent harness.";
+
+const PI_DEFAULT_PROMPT_INTRO = `${PI_DEFAULT_PROMPT_PREFIX} You help users by reading files, executing commands, editing code, and writing new files.`;
+
+function buildCapabilityProse(tools: string[]): string {
+  const set = new Set(tools);
+  const parts: string[] = [];
+  if (set.has("read")) parts.push("reading files");
+  if (set.has("grep") || set.has("find")) parts.push("searching code");
+  if (set.has("ls")) parts.push("listing directories");
+  if (set.has("bash")) parts.push("executing commands");
+  if (set.has("edit")) parts.push("editing code");
+  if (set.has("write")) parts.push("writing new files");
+  if (parts.length === 0) return "following the provided instructions";
+  if (parts.length === 1) return parts[0]!;
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+  return `${parts.slice(0, -1).join(", ")}, and ${parts[parts.length - 1]!}`;
+}
+
+function buildIntro(tools: string[]): string {
+  return `${PI_DEFAULT_PROMPT_PREFIX} You help users by ${buildCapabilityProse(tools)}.`;
+}
+
+const PI_DEFAULT_AVAILABLE_TOOLS_MARKER = "\n\nAvailable tools:\n";
+const PI_DEFAULT_PI_DOCS_MARKER = "\n\nPi documentation";
+const PI_DEFAULT_CWD_PREFIX = "\nCurrent working directory: ";
+
+/**
+ * Strip the default tool inventory, guidelines, and parent working directory
+ * line from an inherited parent prompt before it becomes a child's custom
+ * system prompt.
+ *
+ * Pi's `buildSystemPrompt()` synthesizes an "Available tools" list, tool
+ * guidelines, and a "Current working directory" line when no custom `SYSTEM.md`
+ * is in use. That assembled prompt is what the parent's `getSystemPrompt()`
+ * returns. If we pass it through as the child's custom prompt, the child keeps
+ * the parent's tool advertisement (and cwd) even when its actual tool set is
+ * restricted (e.g. `tools: ["ro"]`) and it is running in a different
+ * directory. AgentSession will append the correct child cwd when it rebuilds
+ * the system prompt, so the inherited parent cwd line is removed here.
+ *
+ * The function detects the default prompt by its stable intro, then removes
+ * only the "Available tools" + "Guidelines" region and the trailing
+ * "Current working directory" line, preserving the rest of the parent base
+ * (and any append/project context/skills that the resource loader added).
+ *
+ * Custom parent `SYSTEM.md` prompts are left untouched: they do not start with
+ * the default intro, so no heuristic stripping occurs.
+ */
+function sanitizeParentToolInventory(
+  prompt: string | undefined,
+  tools: string[] = DEFAULT_TOOLS,
+): string | undefined {
+  if (!prompt) return prompt;
+
+  // Only act on Pi's default generated prompt. Custom prompts may mention tools
+  // intentionally and should not be rewritten by a heuristic.
+  const trimmed = prompt.trimStart();
+  if (!trimmed.startsWith(PI_DEFAULT_PROMPT_INTRO)) return prompt;
+
+  const availableStart = prompt.indexOf(PI_DEFAULT_AVAILABLE_TOOLS_MARKER);
+  if (availableStart < 0) return prompt;
+
+  const piDocsStart = prompt.indexOf(
+    PI_DEFAULT_PI_DOCS_MARKER,
+    availableStart + PI_DEFAULT_AVAILABLE_TOOLS_MARKER.length,
+  );
+  if (piDocsStart < 0) return prompt;
+
+  const intro = buildIntro(tools);
+  const prefix = prompt
+    .slice(0, availableStart)
+    .replace(PI_DEFAULT_PROMPT_INTRO, intro);
+  let base = prefix + prompt.slice(piDocsStart);
+
+  // Remove the inherited parent cwd line; AgentSession adds the correct child
+  // cwd when it assembles the final system prompt.
+  const cwdIndex = base.lastIndexOf(PI_DEFAULT_CWD_PREFIX);
+  if (cwdIndex >= 0) {
+    return base.slice(0, cwdIndex).replace(/\n+$/, "");
+  }
+
+  return base;
+}
+
 function firstNonBlank(
   ...values: Array<string | undefined>
 ): string | undefined {
@@ -338,6 +472,7 @@ export function buildSubagentSystemPrompt(options: {
   agentSystemPrompt?: string;
   parentSystemPrompt?: string;
   pooledSystemPrompt?: string;
+  tools?: string[];
 }): string {
   // Pooled agents already have a frozen prompt baked into their session state.
   // Return it unchanged so repeated sessionId calls do not re-resolve.
@@ -347,11 +482,22 @@ export function buildSubagentSystemPrompt(options: {
   // from this custom prompt + its own resource-loader discovery (skills,
   // AGENTS.md, active-tool snippets). We previously appended skills/AGENTS.md
   // here; that duplicated AgentSession's work.
+  // An inherited parent prompt may be Pi's fully-assembled default prompt,
+  // which carries the parent's "Available tools" list and tool guidelines. A
+  // restricted child (e.g. `tools: ["ro"]`) must not advertise the parent's
+  // mutating tools as callable. Sanitize the parent prompt only; task and agent
+  // prompts are intentionally authored and are left untouched.
+  const resolvedTools = resolveToolGroups(options.tools ?? DEFAULT_TOOLS);
+  const parentSystemPrompt = sanitizeParentToolInventory(
+    options.parentSystemPrompt,
+    resolvedTools,
+  );
+
   const base =
     firstNonBlank(
       options.taskSystemPrompt,
       options.agentSystemPrompt,
-      options.parentSystemPrompt,
+      parentSystemPrompt,
     ) ?? DEFAULT_SUBAGENT_SYSTEM_PROMPT;
 
   return base;

package/concurrency.ts

@@ -10,21 +10,75 @@ import { getMaxConcurrent } from "./config.ts";
 
 let globalConcurrencyLimit = Math.max(1, getMaxConcurrent());
 let globalConcurrencyRunning = 0;
-const globalConcurrencyWaiters: Array<() => void> = [];
 
-function acquireGlobal(): Promise<void> {
+interface GlobalWaiter {
+  /** Resolve with `true` when a slot was acquired, `false` when the signal
+   *  aborted while queued (the caller must not release a slot it never held). */
+  resolve: (acquired: boolean) => void;
+  signal?: AbortSignal;
+  onAbort: () => void;
+}
+
+const globalConcurrencyWaiters: GlobalWaiter[] = [];
+
+/**
+ * Acquire a global concurrency slot.
+ *
+ * Resolves `true` when a slot is held (caller must pair with `releaseGlobal`),
+ * or `false` when `signal` aborted before a slot could be acquired. Waiters are
+ * abort-aware: an abort removes the queued waiter immediately and resolves
+ * `false`, so a cancelled ticket is not stranded in "cancelling" until some
+ * unrelated task happens to release capacity. The caller still invokes its fn
+ * on `false` — the production fn (runResolvedTask) observes the aborted signal
+ * at entry and returns an "Aborted" TaskResult without consuming a slot.
+ */
+function acquireGlobal(signal?: AbortSignal): Promise<boolean> {
+  // Already aborted: never queue (a slot would be wasted on a task that can
+  // only report Aborted) and never increment — nothing to release later.
+  if (signal?.aborted) return Promise.resolve(false);
   if (globalConcurrencyRunning < globalConcurrencyLimit) {
     globalConcurrencyRunning++;
-    return Promise.resolve();
+    return Promise.resolve(true);
   }
-  return new Promise<void>((r) => globalConcurrencyWaiters.push(r));
+  return new Promise<boolean>((resolve) => {
+    const waiter: GlobalWaiter = {
+      resolve,
+      signal,
+      onAbort: () => {
+        // Remove ourselves from the queue without taking a slot. The caller's
+        // fn sees the aborted signal at entry and settles promptly.
+        const index = globalConcurrencyWaiters.indexOf(waiter);
+        if (index === -1) return; // already woken by releaseGlobal
+        globalConcurrencyWaiters.splice(index, 1);
+        waiter.signal?.removeEventListener("abort", waiter.onAbort);
+        resolve(false);
+      },
+    };
+    if (signal) {
+      signal.addEventListener("abort", waiter.onAbort, { once: true });
+    }
+    globalConcurrencyWaiters.push(waiter);
+  });
 }
 
 function releaseGlobal(): void {
   globalConcurrencyRunning--;
+  // Never hand a slot to a waiter whose signal already aborted. The abort
+  // listener normally removes it synchronously during abort() dispatch; this
+  // drain is defensive for any ordering edge.
+  while (
+    globalConcurrencyWaiters.length > 0 &&
+    globalConcurrencyWaiters[0]!.signal?.aborted
+  ) {
+    const w = globalConcurrencyWaiters.shift()!;
+    w.signal?.removeEventListener("abort", w.onAbort);
+    w.resolve(false);
+  }
   if (globalConcurrencyWaiters.length > 0) {
     globalConcurrencyRunning++;
-    globalConcurrencyWaiters.shift()!();
+    const w = globalConcurrencyWaiters.shift()!;
+    w.signal?.removeEventListener("abort", w.onAbort);
+    w.resolve(true);
   }
 }
 
@@ -109,9 +163,18 @@ export async function mapConcurrentByModel<T, R>(
         groupItems,
         group.limit,
         async (_item, localIdx) => {
-          await acquireGlobal();
+          const globalIdx = group.indices[localIdx]!;
+          const acquired = await acquireGlobal(signal);
+          if (!acquired) {
+            // Aborted while queued for a global slot: we hold no slot, so we
+            // must NOT release one. Still invoke fn — runResolvedTask observes
+            // the aborted signal at entry and returns an "Aborted" TaskResult,
+            // keeping the results array dense for the sync dereference path
+            // (the same contract as mapConcurrent's worker loop).
+            results[globalIdx] = await fn(_item, globalIdx);
+            return results[globalIdx];
+          }
           try {
-            const globalIdx = group.indices[localIdx]!;
             results[globalIdx] = await fn(_item, globalIdx);
             return results[globalIdx];
           } finally {

package/delegate.ts

@@ -3,6 +3,7 @@ export { default } from "./extension.ts";
 export type {
   AgentConfig,
   SessionAction,
+  TicketAction,
   DelegateAction,
   DelegateArguments,
   TaskDef,
@@ -58,6 +59,7 @@ export {
   ticketRegistry,
   sweepTickets,
   cancelTicketForShutdown,
+  requestTicketCancel,
   isSessionBusy,
   handlePoll,
   handleCancel,
@@ -67,6 +69,13 @@ export {
   resolveFinalTicketStatus,
   formatCompletedTicket,
 } from "./tickets.ts";
+export type { TicketDelivery } from "./tickets.ts";
+export {
+  recordTreeNavigation,
+  getCurrentLeafId,
+  resetLeafTracking,
+  isCrossLeafTicket,
+} from "./leaf.ts";
 export { runAgentSession } from "./runner.ts";
 export {
   activeTicketSummary,
@@ -76,6 +85,8 @@ export {
   syncDelegateStatus,
   notifyActiveTicketsOnSettled,
   guardSessionReplacement,
+  guardTreeNavigation,
+  notifyCrossLeafDelivery,
 } from "./status.ts";
 export type { ActiveTicketSummary } from "./status.ts";
 export { getHostDeps, invalidateHostDepsCache } from "./host.ts";
@@ -99,6 +110,8 @@ export {
   indent,
   formatFailedTask,
   formatCompletedTask,
+  findTouchedOverlaps,
+  formatTouchedOverlapWarning,
 } from "./format.ts";
 export {
   parseFrontmatter,

package/dispatch.ts

@@ -10,12 +10,19 @@ import {
   notifyWaiters,
 } from "./tickets.ts";
 import { getConcurrencyLimit, getMaxAsyncTickets } from "./config.ts";
+import { getCurrentLeafId } from "./leaf.ts";
 import { getModelKey, mapConcurrentByModel } from "./concurrency.ts";
 import { sumUsage } from "./usage.ts";
 import { runResolvedTask, updateProgressFromRun } from "./lifecycle.ts";
-import { fmtDuration, formatCompletedTask, trunc } from "./format.ts";
+import {
+  fmtDuration,
+  formatCompletedTask,
+  trunc,
+  findTouchedOverlaps,
+  formatTouchedOverlapWarning,
+} from "./format.ts";
 import { validateDelegateOperation } from "./schema.ts";
-import { syncDelegateStatus } from "./status.ts";
+import { notifyCrossLeafDelivery, syncDelegateStatus } from "./status.ts";
 import { validateTasks, resolveTasks } from "./task-resolution.ts";
 import type {
   AgentConfig,
@@ -57,9 +64,10 @@ export function validateDelegateOperationResult(
 /** Build the initial per-task progress rows from resolved tasks. */
 export function initProgress(resolved: ResolvedTask[]): TaskProgress[] {
   return resolved.map((t, i) => ({
+    id: t.id,
     index: i,
     agent: t.agentName,
-    task: trunc(t.prompt || t.action || "", 50),
+    task: trunc(t.prompt || t.sessionAction || "", 50),
     status: "pending" as const,
     durationMs: 0,
     tokens: 0,
@@ -182,6 +190,15 @@ export async function dispatchDelegate(
   });
 }
 
+/** Deliver a settled ticket and, when leaf affinity downgraded delivery to a
+ *  non-waking `nextTurn` message, tell the human — otherwise the completion is
+ *  silent apart from the footer clearing. */
+function finishTicketDelivery(pi: ExtensionAPI, ticket: AsyncTicket): void {
+  if (deliverTicketResults(pi, ticket) === "deferred") {
+    notifyCrossLeafDelivery(ticket);
+  }
+}
+
 /** Fire-and-forget background execution. Registers an `AsyncTicket`, kicks off
  *  the concurrent run, and returns the ticket acknowledgment immediately.
  *  Results are delivered via `deliverTicketResults` when all tasks settle. */
@@ -216,6 +233,9 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     progress: [...progress],
     controller,
     parentModelId,
+    // Leaf affinity for delivery: a ticket that outlives a /tree navigation
+    // must not wake the agent on the branch the user moved to (issue #30).
+    spawnLeafId: getCurrentLeafId(),
   };
   ticketRegistry.set(ticketId, ticket);
   // Footer visibility for the new background work (see status.ts). Uses the
@@ -289,7 +309,7 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
         syncTicketBusyIndex(ticket);
       }
       syncDelegateStatus();
-      deliverTicketResults(pi, ticket);
+      finishTicketDelivery(pi, ticket);
     })
     .catch((err) => {
       // Defense-in-depth — should not happen if individual tasks catch properly.
@@ -304,7 +324,7 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       ticket.completedAt = Date.now();
       syncTicketBusyIndex(ticket);
       syncDelegateStatus();
-      deliverTicketResults(pi, ticket);
+      finishTicketDelivery(pi, ticket);
     });
 
   return {
@@ -316,8 +336,8 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
           `${resolved.length} task(s) dispatched · ${runningCount + 1}/${getMaxAsyncTickets()} async slots in use`,
           "",
           "Completed task results are available via poll. Final results delivered automatically when all tasks complete.",
-          `Check progress: delegate({ action: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
-          `Cancel if needed: delegate({ action: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
+          `Check progress: delegate({ ticketAction: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
+          `Cancel if needed: delegate({ ticketAction: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
         ].join("\n"),
       },
     ],
@@ -376,6 +396,11 @@ export async function dispatchSync(
     parts.push(...formatCompletedTask(t, r));
   }
 
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(finalResults),
+  );
+  if (overlapWarning) parts.push("", overlapWarning);
+
   return {
     content: [{ type: "text", text: parts.join("\n\n") }],
     details: {
@@ -383,6 +408,7 @@ export async function dispatchSync(
       results: finalResults,
       progress,
       parentModel: parentModelId,
+      overlapWarning: overlapWarning || undefined,
     },
     // Aggregate subagent spend so Pi folds it into the parent's
     // session/footer totals. Sync dispatch only — async results arrive via a

package/extension.ts

@@ -19,12 +19,14 @@ import {
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
 import { invalidateHostDepsCache } from "./host.ts";
+import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import {
   activeTicketSummary,
   clearDelegateStatusContext,
   describeActiveTickets,
   guardSessionReplacement,
+  guardTreeNavigation,
   notifyActiveTicketsOnSettled,
   syncDelegateStatus,
 } from "./status.ts";
@@ -36,7 +38,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     name: "delegate",
     label: "Delegate to Subagents",
     description:
-      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async returns a ticket.",
+      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async=ticket. tasks:[]=full manual.",
     parameters: delegateArgumentsSchema,
     // Runs before schema validation — recovers stringified `tasks` arrays
     // (a common model mistake that would otherwise be rejected upstream).
@@ -58,12 +60,12 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       if (operationResult) return operationResult;
 
       // ── Poll action ───────────────────────────────────────────────────
-      if (params.action === "poll") {
+      if (params.ticketAction === "poll") {
         return handlePoll(params, ctx);
       }
 
       // ── Cancel action ─────────────────────────────────────────────────
-      if (params.action === "cancel") {
+      if (params.ticketAction === "cancel") {
         const result = handleCancel(params);
         // A forced cancel flips the ticket to "cancelling" — keep the
         // footer status in step (deduped; the preview path is a no-op).
@@ -72,7 +74,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       }
 
       // ── Wait action ────────────────────────────────────────────────────
-      if (params.action === "wait") {
+      if (params.ticketAction === "wait") {
         return handleWait(params, signal, onUpdate, ctx);
       }
 
@@ -140,6 +142,17 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     guardSessionReplacement(ctx, "fork"),
   );
 
+  // /tree navigation stays inside the same session: nothing is torn down and
+  // live tickets keep running, but their results would land on the branch the
+  // user moves to. Ask first, and record the new leaf either way so delivery
+  // can detect the mismatch (issue #30). `session_tree` also fires for
+  // extension-driven ctx.navigateTree, which never reaches the guard.
+  pi.on("session_before_tree", (_event, ctx) => guardTreeNavigation(ctx));
+  pi.on("session_tree", (event, ctx) => {
+    recordTreeNavigation(event.newLeafId);
+    syncDelegateStatus(ctx);
+  });
+
   // ── Session shutdown: abort tickets and dispose live pooled sessions ──
   pi.on("session_shutdown", async (event, ctx) => {
     // Quit and /reload kill background work with no cancellable hook, so
@@ -167,6 +180,9 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     // tickets keep unwinding asynchronously and must find no cached ctx (or
     // captured pi) to touch. See the "cancelled"-at-entry guard in dispatch.
     clearDelegateStatusContext();
+    // A replacement session starts on its own leaf; stale tracking would make
+    // every ticket look cross-leaf (or, worse, look same-leaf by accident).
+    resetLeafTracking();
     // Do NOT clear the ticket registry here — completed tickets are retained
     // until their TTL cleanup. Pooled AgentSessions, however, own listeners
     // and must be disposed before the parent session exits.

package/file-tracking.ts

@@ -2,9 +2,19 @@ import { execFile } from "node:child_process";
 import * as path from "node:path";
 import type { ToolActivity } from "./types.ts";
 
-/** Return absolute paths reported as changed by Git in the task cwd.
- * Git failures degrade to an empty set because file tracking is observational. */
-export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
+/**
+ * Return absolute paths reported as changed by Git in the task cwd.
+ *
+ * Touched-file tracking is best-effort, not authoritative. On success this
+ * returns the set of changed paths (possibly empty for a clean repo). On
+ * failure (non-git directory, git unavailable, timeout) it returns `undefined`
+ * so callers can tell "git failed" from "clean repo". A failed baseline
+ * suppresses git-based attribution in the runner; only explicit edit/write tool
+ * activity is captured by {@link extractTouchedFromActivities}.
+ */
+export async function getGitChangedFiles(
+  cwd: string,
+): Promise<Set<string> | undefined> {
   try {
     const runGit = (args: string[]) =>
       new Promise<string>((resolve, reject) => {
@@ -37,11 +47,22 @@ export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
     }
     return files;
   } catch {
-    return new Set();
+    return undefined;
   }
 }
 
-/** Extract file paths mutated by edit/write from the activity log. */
+/**
+ * Extract file paths from explicit edit/write tool calls in the activity log.
+ *
+ * This is the reliable, activity-based contribution to touched-file tracking.
+ * Only completed, successful tool calls are counted: an activity must have a
+ * terminal `result` and `result.isError` must be false. Interrupted or in-flight
+ * calls (no `result`) and failed calls (`result.isError` true) are skipped,
+ * because they did not actually mutate the file. bash mutations are NOT captured
+ * here; they are only captured by git diff when the task cwd is inside a git
+ * repo with git available. The combined touchedFiles list is therefore a lower
+ * bound: absence does not mean a file was unchanged.
+ */
 export function extractTouchedFromActivities(
   activities: ToolActivity[],
   cwd: string,
@@ -49,6 +70,7 @@ export function extractTouchedFromActivities(
   const files = new Set<string>();
   for (const a of activities) {
     if (a.name !== "edit" && a.name !== "write") continue;
+    if (!a.result || a.result.isError) continue;
     const raw = a.args?.path ?? a.args?.file_path ?? a.args?.filePath;
     if (typeof raw !== "string" || !raw) continue;
     files.add(path.resolve(cwd, raw));