@herbertgao/pi-subagents 0.17.0 → 0.18.0

package/src/invocation-config.ts

@@ -113,6 +113,15 @@ export function resolveAgentInvocationConfig(
   runInBackground: boolean
   isolated: boolean
   isolation?: IsolationMode
+  /**
+   * Caller parameters an agent file's frontmatter outranked, so the surfaces can
+   * say "(asked X)" instead of presenting the effective value as the requested
+   * one (#182). Populated only where both sides named something and they
+   * disagree — a caller who asked for what they got was still honored.
+   *
+   * `max_turns` is deliberately absent: no surface renders a requested-vs-
+   * effective turn limit, so recording one would be dead data.
+   */
   overridden?: { thinking?: ThinkingLevel; model?: string }
 } {
   // Precedence first, collapse second — reversing these loses the veto, since
@@ -123,6 +132,7 @@ export function resolveAgentInvocationConfig(
     requested === "worktree" && opts?.worktreeAllowed !== false
       ? "worktree"
       : undefined
+
   const overriddenThinking =
     agentConfig?.thinking != null &&
     params.thinking != null &&
@@ -152,6 +162,9 @@ export function resolveAgentInvocationConfig(
       false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
     isolation,
+    // Undefined rather than an empty object when nothing was overridden: callers
+    // spread this into the invocation snapshot, and an always-present key would
+    // put `requestedThinking: undefined` on every record.
     overridden:
       overriddenThinking || overriddenModel
         ? { thinking: overriddenThinking, model: overriddenModel }

package/src/mention-clone.ts

@@ -0,0 +1,215 @@
+/**
+ * mention-clone.ts — start a mentioned agent through a clone of this
+ * conversation, without putting anything in the chat.
+ *
+ * Claude Code routes `@agent-<type>` through the main model: the mention
+ * becomes a `<system-reminder>` appended to the prompt and the model makes the
+ * tool call (see `agentMentionReminder`). That buys the spawned agent a prompt
+ * written with conversation context, and costs a visible turn — the model's
+ * reasoning and its tool block land in the transcript, for a decision the user
+ * already made when they typed the handle.
+ *
+ * So the turn happens somewhere else. The conversation is cloned into a
+ * throwaway in-memory session — same messages, same system prompt, same model —
+ * and that copy takes the turn off-screen. A literal clone: the session's own
+ * entries, projected by pi's own `sessionEntryToContextMessages`, not
+ * `inherit_context`'s text rendering of them.
+ *
+ * Cloned from memory rather than from the session file, which cannot be relied
+ * on: `SessionManager._persist` withholds every write until the first assistant
+ * message lands, so a fork taken before then reads an empty file and throws.
+ * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
+ * the leaf path and substitutes the summary for entries folded into it, so a
+ * long conversation clones as what the main model is actually working from. A
+ * conversation with nothing in it yet clones to nothing in it yet, which is the
+ * correct answer rather than a failure.
+ *
+ * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
+ * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
+ * arrived in 0.80.5 — where this one has been exported unchanged from before
+ * the declared peer floor, and is the same code path (`byId` is only an index
+ * cache, so passing it or not cannot change the result). Keeping the floor
+ * honest costs nothing here: see the `compat-floor-pi` job.
+ *
+ * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
+ * better. `getSessionContextSettings` starts at "off" and moves only on an
+ * explicit `thinking_level_change` entry, so a session where nobody ran
+ * `/think` reports "off" rather than the level it is really using. Omitting the
+ * field instead lets `createAgentSession` resolve it from settings, which is
+ * that real level.
+ *
+ * Three details make the spawn belong to the real session rather than the
+ * clone:
+ *
+ *   - the clone is handed the *registered* `Agent` tool, whose handler closes
+ *     over the main activation, so it spawns top-level: widget, fleet row,
+ *     handle, completion notification, all as if the main model had called it;
+ *   - that tool is re-bound to the main `ExtensionContext`, because the handler
+ *     reads `cwd`, `model` and `sessionManager.getSessionId()` off it to place
+ *     the transcript and the `rootSessionId`. The clone's own context would
+ *     file both under the throwaway fork;
+ *   - it is called with no tool-call id. The clone's turn produces one, but the
+ *     real session never issued it, and a `<tool-use-id>` pointing at nothing
+ *     is exactly the bug the mention-resume path had to fix;
+ *   - and it is forced into the background. A foreground agent returns its
+ *     answer as the tool result and is marked `resultConsumed` so no completion
+ *     notification is sent — correct when the caller is the real conversation,
+ *     silent loss when the caller is a fork about to be discarded. Background
+ *     delivery is the only route from a mention back to the main model.
+ *
+ * The clone gets one tool and one job. It cannot read, write or run anything —
+ * an invisible turn with the full toolset could do invisible work.
+ */
+
+import type { Model } from "@earendil-works/pi-ai"
+import {
+  buildSessionContext,
+  createAgentSession,
+  type ExtensionContext,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent"
+import { runInChildSessionContext } from "./child-context.js"
+import { agentMentionReminder } from "./mention.js"
+import type { SubagentType, ThinkingLevel } from "./types.js"
+
+export interface MentionCloneOptions {
+  /** The MAIN session's context — what the spawn is attributed to, and the
+   * source of both the conversation and the live system prompt. */
+  ctx: ExtensionContext
+  /** Agent type the handle resolved to. */
+  type: SubagentType
+  /** What the user typed after the handle. */
+  message: string
+  /** The registered `Agent` tool, reused so the spawn is an ordinary one. */
+  agentTool: ToolDefinition
+}
+
+export interface MentionCloneResult {
+  /** True once the clone actually called `Agent`. */
+  spawned: boolean
+  /** Why not, when it didn't. Absent on success. */
+  error?: string
+}
+
+/**
+ * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Never rejects: a clone that cannot run is reported so the caller can fall
+ * back to starting the agent directly.
+ */
+export async function runMentionClone(
+  opts: MentionCloneOptions,
+): Promise<MentionCloneResult> {
+  const { ctx, type, message, agentTool } = opts
+
+  let spawned = false
+  const cloneAgentTool: ToolDefinition = {
+    ...agentTool,
+    execute: (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
+      // One spawn per mention. The clone has a single tool and every reason to
+      // stop after using it, but a model that decides to "also" launch a second
+      // agent would do it where nobody can see and nobody asked.
+      if (spawned) {
+        return Promise.resolve({
+          content: [
+            {
+              type: "text" as const,
+              text: "Already started an agent for this mention. Stop here.",
+            },
+          ],
+          details: undefined,
+          isError: true,
+        })
+      }
+      spawned = true
+      // undefined tool-call id + the main ctx: see the header. Background is
+      // forced rather than left to the clone: `run_in_background` defaults to
+      // false, and a foreground agent answers through its TOOL RESULT — which
+      // here is delivered into a session that is disposed moments later, so the
+      // agent would run, appear in the widget and the fleet, and reach nobody.
+      return agentTool.execute(
+        undefined as never,
+        {
+          ...(params as Record<string, unknown>),
+          run_in_background: true,
+        } as typeof params,
+        signal,
+        onUpdate,
+        ctx,
+      )
+    },
+  }
+
+  let session:
+    | Awaited<ReturnType<typeof createAgentSession>>["session"]
+    | undefined
+  try {
+    // Pi 0.80.8 moved createAgentSession from modelRegistry to modelRuntime;
+    // agent-runner.ts carries the same shim for the same reason — pass both so
+    // the clone keeps the parent's providers across the supported range.
+    // SAFETY: The supported Pi versions expose runtime through this facade at
+    // runtime; the optional property keeps the pre-modelRuntime fallback safe.
+    const parentModelRuntime = (
+      ctx.modelRegistry as unknown as { runtime?: unknown }
+    ).runtime
+    // The conversation as the main session resolves it: compaction applied,
+    // branch summaries substituted.
+    const conversation = buildSessionContext(
+      ctx.sessionManager.getEntries(),
+      ctx.sessionManager.getLeafId(),
+    )
+    // Pi 0.82.0 added this; below it the field is absent and the clone takes
+    // the settings level instead, which is what a session that never ran
+    // `/think` is on anyway. Same shim shape as `modelRuntime` below.
+    const thinkingLevel = (ctx as { thinkingLevel?: ThinkingLevel })
+      .thinkingLevel
+    const created = await runInChildSessionContext(() =>
+      createAgentSession({
+        cwd: ctx.cwd,
+        // Nothing about the copy is worth persisting, and an in-memory manager
+        // is also what keeps the real session untouched.
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model: ctx.model as Model<never> | undefined,
+        ...(thinkingLevel && { thinkingLevel }),
+        modelRegistry: ctx.modelRegistry,
+        ...(parentModelRuntime !== undefined && {
+          modelRuntime: parentModelRuntime as never,
+        }),
+        // An allowlist naming exactly the clone's own tool. NOT `noTools:
+        // "all"`, whose doc comment ("start with no tools enabled") reads like
+        // it spares custom tools and does not: it resolves to an EMPTY
+        // allowlist, and `isAllowedTool` then drops every tool from the
+        // registry — the custom one included. The clone would be prompted with
+        // nothing to call, answer in prose, and every mention would fall
+        // through to the direct start with a warning. Same idiom as
+        // agent-runner's `tools: sessionTools` beside its nested `customTools`.
+        tools: [cloneAgentTool.name],
+        customTools: [cloneAgentTool],
+      } as Parameters<typeof createAgentSession>[0]),
+    )
+    session = created.session
+
+    // The clone rebuilds a system prompt from cwd and agentDir, which is close
+    // but not the live one — extensions contribute to it per turn. Copy the
+    // real thing, so the copy reasons under the instructions the user's model
+    // is actually working under.
+    const systemPrompt = ctx.getSystemPrompt?.()
+    if (systemPrompt) session.agent.state.systemPrompt = systemPrompt
+
+    // The conversation itself. Pushed rather than assigned so the array the
+    // session was built around stays the one it goes on using.
+    session.agent.state.messages.push(...conversation.messages)
+
+    // User text first, reminder after — the order Claude Code's attachment
+    // renderer produces, where the reminder trails the message it is about.
+    await session.prompt(`${message}\n\n${agentMentionReminder(type)}`)
+  } catch (err) {
+    return { spawned, error: err instanceof Error ? err.message : String(err) }
+  } finally {
+    session?.dispose?.()
+  }
+
+  return spawned
+    ? { spawned: true }
+    : { spawned: false, error: "the conversation clone did not start it" }
+}

package/src/mention.ts

@@ -0,0 +1,147 @@
+/**
+ * mention.ts — the `@handle` grammar for messaging a subagent from the prompt.
+ *
+ * Claude Code lets you type `@code-review take another look` at the prompt and
+ * routes the message to that agent instead of the main model. Its grammar is
+ * reproduced here so the two behave identically:
+ *
+ *   - suggestions fire on `@` at the start of the input or after whitespace,
+ *     followed by `[\w-]*` (so `@src/foo.ts` is a file, never an agent);
+ *   - a send is recognized only at the START of the input, and only with a
+ *     non-empty message after the handle. That is why a bare `@code-review`
+ *     goes to the main model rather than anywhere near the agent.
+ *
+ * A record's own identity is a UUID plus a deliberately non-unique description,
+ * neither of which is typeable, so the handle is derived from the agent type.
+ * Colliding handles are numbered (`explore`, `explore-2`), which is also what
+ * Claude Code's `allocateName` does — it recycles a name only once the task
+ * behind it is gone. Its SendMessage prompt describes the *registry* as
+ * latest-wins, which is a different thing and not how names are allocated.
+ */
+
+/**
+ * Suggestion trigger: `@` at a token boundary plus the partial handle typed so
+ * far. Ported from Claude Code, including the CJK sentence-ending punctuation
+ * it accepts as a boundary.
+ */
+export const MENTION_TRIGGER = /(^|[\s。、？！])@([\w-]*)$/
+
+/** Send grammar: leading `@handle`, then a non-empty message. */
+const MENTION_SEND = /^@([\w-]+)\s+([\s\S]+)$/
+
+/**
+ * Upper bound on a handle, matching Claude Code's `dSS`. Nothing here generates
+ * a name this long, but an agent type or a model-supplied name can be arbitrary
+ * text, and an unbounded handle would wrap the suggestion popup.
+ */
+const MAX_HANDLE_LENGTH = 64
+
+/**
+ * Handles that address something other than a subagent, and so can never be
+ * allocated to one. Claude Code reserves exactly this name (`Vq = "main"`),
+ * refusing it at spawn and routing it to the main conversation instead.
+ */
+const RESERVED_HANDLES: ReadonlySet<string> = new Set(["main"])
+
+/** Whether `@handle` names the main conversation rather than any subagent. */
+export function isReservedHandle(handle: string): boolean {
+  return RESERVED_HANDLES.has(handle.toLowerCase())
+}
+
+/** Slug of an agent type or name, restricted to the `[\w-]` the grammar allows. */
+export function handleBase(type: string): string {
+  const slug = type
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_HANDLE_LENGTH)
+    // The slice can land mid-run and leave the trailing hyphen back.
+    .replace(/-+$/, "")
+  return slug || "agent"
+}
+
+/**
+ * `base`, else `base-2`, `base-3`, … — the first form that is neither `taken`
+ * nor reserved. Callers pass one shared `taken` set covering type-derived
+ * handles and model-supplied aliases alike, so the two can never collide.
+ */
+export function assignHandle(base: string, taken: ReadonlySet<string>): string {
+  let candidate = base
+  let n = 1
+  while (taken.has(candidate) || RESERVED_HANDLES.has(candidate)) {
+    n++
+    candidate = `${base}-${n}`
+  }
+  return candidate
+}
+
+/**
+ * Map a typed handle back to a registered agent type, so `@explore fix it`
+ * reaches the Explore agent even when no instance has ever run. `handleBase` is
+ * the single source of truth in both directions, so a type is addressable by
+ * exactly the handle its instances would be given.
+ */
+export function resolveHandleToType(
+  handle: string,
+  types: readonly string[],
+): string | undefined {
+  const wanted = handle.toLowerCase()
+  // A type slugging to a reserved name is unaddressable rather than shadowing
+  // it — `assignHandle` refuses that name too, so its instances never hold one.
+  if (RESERVED_HANDLES.has(wanted)) return undefined
+  return types.find((type) => handleBase(type) === wanted)
+}
+
+/**
+ * Claude Code documents `@agent-<name>` as the form you type by hand when the
+ * picker isn't involved. Accepted here as an exact synonym: the caller tries the
+ * handle as written first, so an agent genuinely called `agent-foo` still wins
+ * over `@agent-` + `foo`, and only falls back to this when that finds nothing.
+ * Returns undefined when the prefix is absent or is the whole handle.
+ */
+export function stripAgentPrefix(handle: string): string | undefined {
+  const rest = /^agent-(.+)$/i.exec(handle)?.[1]
+  return rest || undefined
+}
+
+/**
+ * A spawn needs the short description every agent surface renders. A mention
+ * carries no separate label, so the message itself becomes one: first line,
+ * whitespace collapsed, clipped to roughly the 3-5 words the Agent tool asks of
+ * the model.
+ */
+export function describeMention(message: string): string {
+  const oneLine = message.split("\n", 1)[0].replace(/\s+/g, " ").trim()
+  return oneLine.length > 40 ? `${oneLine.slice(0, 39).trimEnd()}…` : oneLine
+}
+
+/**
+ * What Claude Code sends the main model when a mention names an agent it could
+ * start. Its `@agent-<type>` mention is not a spawn at all: it becomes an
+ * `agent_mention` attachment, which renders to a synthetic `isMeta` user
+ * message placed after the user's own untouched text — no tool forcing, no
+ * allowed-tools narrowing, and the Task tool is not even named. The model reads
+ * this and calls the tool itself.
+ *
+ * Ported verbatim from the 2.1.233 bundle's attachment renderer, trailing space
+ * before the closing newline included, so the wording the model was trained
+ * against is the wording it gets. The one substitution is ours: pi's equivalent
+ * of Task is the `Agent` tool, and the agent listing that teaches valid
+ * `subagent_type` values is the tool spec rather than a separate attachment.
+ */
+export function agentMentionReminder(type: string): string {
+  return `<system-reminder>\nThe user has expressed a desire to invoke the agent "${type}". Please invoke the agent appropriately, passing in the required context to it. \n</system-reminder>`
+}
+
+/**
+ * Split `@handle message` into its parts, or null when the text isn't a send —
+ * a bare handle, a leading file path, or a mention that isn't at the start.
+ */
+export function parseMention(
+  text: string,
+): { handle: string; message: string } | null {
+  const match = MENTION_SEND.exec(text)
+  if (!match) return null
+  const message = match[2].trim()
+  return message ? { handle: match[1], message } : null
+}

package/src/model-resolver.ts

@@ -14,7 +14,15 @@ export interface ModelRegistry {
   getAvailable?(): any[]
 }
 
-/** Both display forms of a resolved model. */
+/**
+ * Both display forms of a model. The short one goes on tight rows (the widget,
+ * the Agent tool result), the canonical one where there is room to disambiguate
+ * two providers serving a similarly-named model (the conversation viewer).
+ *
+ * One function, because `index.ts` labels the model it resolved before the run
+ * and `agent-manager.ts` relabels it from the live session afterwards — the two
+ * must agree or the label would visibly change the moment the session starts.
+ */
 export function describeModel(model: {
   provider: string
   id: string

package/src/nested-tools.ts

@@ -96,6 +96,8 @@ export interface NestedAgentManager {
     prompt: string,
     options: NestedSpawnOptions,
   ): string
+  /** Resolves once the spawned agent is running; rejects on a startup failure. */
+  awaitStartup(id: string): Promise<void>
   spawnAndWait(
     pi: ExtensionAPI,
     ctx: ExtensionContext,
@@ -413,38 +415,50 @@ export function createNestedSubagentTools(
       // one earlier would silently give a grandchild the wrong worktree base, the
       // wrong conversation under inherit_context, and the wrong inherited model.
       //
-      // Startup throws mean no child ran. Let them propagate so Pi marks the
-      // nested Agent tool call failed instead of presenting the message as a
-      // successful child result.
-      if (invocation.runInBackground) {
-        const id = context.manager.spawn(
+      // spawn() throws on strict worktree-isolation failure and cwd validation —
+      // report it as a tool error, like the top-level Agent tool does, instead of
+      // letting it escape into the child's turn.
+      try {
+        if (invocation.runInBackground) {
+          const id = context.manager.spawn(
+            context.pi,
+            ctx,
+            resolvedType,
+            params.prompt,
+            {
+              ...options,
+              isBackground: true,
+            },
+          )
+          // Synchronous, before the event loop yields — onSessionCreated fires
+          // asynchronously inside runAgent, so the file is attached in time.
+          attachTranscript(id)
+          // Worktree isolation starts the agent asynchronously; surface its
+          // failure as a tool error, like the synchronous throw used to.
+          await context.manager.awaitStartup(id)
+          return textResult(
+            `Nested agent started in background. Agent ID: ${id}`,
+          )
+        }
+
+        const { record } = await context.manager.spawnAndWait(
           context.pi,
           ctx,
           resolvedType,
           params.prompt,
-          {
-            ...options,
-            isBackground: true,
-          },
+          { ...options, signal },
+          attachTranscript,
+        )
+        return textResult(
+          formatRecord(record, "inline"),
+          record.status === "error",
+        )
+      } catch (err) {
+        return textResult(
+          err instanceof Error ? err.message : String(err),
+          true,
         )
-        // Synchronous, before the event loop yields — onSessionCreated fires
-        // asynchronously inside runAgent, so the file is attached in time.
-        attachTranscript(id)
-        return textResult(`Nested agent started in background. Agent ID: ${id}`)
       }
-
-      const { record } = await context.manager.spawnAndWait(
-        context.pi,
-        ctx,
-        resolvedType,
-        params.prompt,
-        { ...options, signal },
-        attachTranscript,
-      )
-      return textResult(
-        formatRecord(record, "inline"),
-        record.status === "error",
-      )
     },
   })
 

package/src/output-file.ts

@@ -44,13 +44,14 @@ export function encodeCwd(cwd: string): string {
     .replace(/^-+/, "") // strip leading dashes (POSIX root, UNC)
 }
 
-/** Create the output file path, ensuring the directory exists.
- *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
-export function createOutputFilePath(
-  cwd: string,
-  agentId: string,
-  sessionId: string,
-): string {
+/**
+ * The per-session scratch directory, created if missing.
+ * Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks
+ *
+ * Shared with the workflow tool, which persists each invocation's script here so
+ * iterating on one is edit-file-then-rerun — the same convention, one directory.
+ */
+export function sessionTaskDir(cwd: string, sessionId: string): string {
   const encoded = encodeCwd(cwd)
   const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`)
   mkdirSync(root, { recursive: true, mode: 0o700 })
@@ -63,7 +64,16 @@ export function createOutputFilePath(
   }
   const dir = join(root, encoded, sessionId, "tasks")
   mkdirSync(dir, { recursive: true })
-  return join(dir, `${agentId}.output`)
+  return dir
+}
+
+/** Create the output file path, ensuring the directory exists. */
+export function createOutputFilePath(
+  cwd: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return join(sessionTaskDir(cwd, sessionId), `${agentId}.output`)
 }
 
 /**

package/src/prompts.ts

@@ -10,8 +10,29 @@ export interface PromptExtras {
   memoryBlock?: string
   /** Preloaded skill contents to inject. */
   skillBlocks?: { name: string; content: string }[]
-  /** Original checkout path when cwd is an isolated worktree copy. */
+  /**
+   * Parent directory the worktree copy was created from. Set only for
+   * `isolation: "worktree"` spawns — triggers the block that tells the agent
+   * to stay in the copy.
+   */
   worktreeBase?: string
+  /**
+   * Set only for a workflow's own children, and only when they have no
+   * `StructuredOutput` tool to answer through.
+   *
+   * A workflow child's final text is not read by a human — it is the value
+   * `agent()` resolves to, and the script interpolates it straight into the
+   * next stage's prompt. Without this, children answer the way every other
+   * subagent does (a report addressed to a reader), and the padding becomes
+   * input tokens for the stage downstream. Claude Code's `Workflow` tool
+   * documents this contract to the script-writing model; this is the end of it
+   * that makes the documentation true.
+   *
+   * Deliberately NOT applied to every subagent. In pi an ordinary agent's
+   * output IS read by a human — through FleetView, the conversation viewer and
+   * `get_subagent_result` — so terse raw data would be the wrong answer there.
+   */
+  workflowChild?: boolean
 }
 
 /**
@@ -45,6 +66,26 @@ Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`
 
+  // A worktree agent is told its cwd twice: by the env block above (the copy)
+  // and by whatever names the main checkout — the inherited parent prompt in
+  // append mode, or the task prompt in either mode. It follows the latter and
+  // works in the shared tree (#187), so resolve the contradiction explicitly.
+  const worktreeBlock = extras?.worktreeBase
+    ? `\n\n<worktree_isolation>
+Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
+Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
+</worktree_isolation>`
+    : ""
+
+  // The script, not a person, reads what this child returns — see
+  // `PromptExtras.workflowChild` for why only workflow children get this.
+  const workflowBlock = extras?.workflowChild
+    ? `\n\n<workflow_child>
+Your final message IS the return value of this task. A workflow script captures it and passes it to the next stage; no person reads it.
+Return only the answer, in exactly the shape the prompt asks for — no preamble, no summary of what you did, no offer to continue.
+</workflow_child>`
+    : ""
+
   // Build optional extras suffix
   const extraSections: string[] = []
   if (extras?.memoryBlock) {
@@ -57,12 +98,6 @@ Platform: ${env.platform}`
   }
   const extrasSuffix =
     extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : ""
-  const worktreeSection = extras?.worktreeBase
-    ? `\n\n<worktree_isolation>
-Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
-Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
-</worktree_isolation>`
-    : ""
 
   if (config.promptMode === "append") {
     const identity = parentSystemPrompt || genericBase
@@ -96,7 +131,8 @@ You are operating as a sub-agent invoked to handle a specific task.
       "\n\n" +
       activeAgentTag +
       envBlock +
-      worktreeSection +
+      worktreeBlock +
+      workflowBlock +
       customSection +
       extrasSuffix
     )
@@ -111,7 +147,8 @@ ${envBlock}`
   return (
     activeAgentTag +
     replaceHeader +
-    worktreeSection +
+    worktreeBlock +
+    workflowBlock +
     "\n\n" +
     config.systemPrompt +
     extrasSuffix