@henryqw/pi-herdr-tools 1.3.3 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-herdr-tools`
 
-Clone a conversation into a Herdr tab or worktree. Ask a side question and merge its answer back into Main. Give the conversation a name, and finish the worktree safely. One package and one extension entry point supply `/clone-tab`, `/clone-worktree`, `/btw`, `/rename`, and `/done`. Herdr also shows the pane as blocked while a Pi dialog waits for your answer.
+Clone a conversation into a Herdr tab or worktree. Hand off a separate issue to a new agent in a new worktree. Ask a side question and merge its answer back into Main. Give the conversation a name, and finish the worktree safely. One package and one extension entry point supply `/clone-tab`, `/clone-worktree`, `/handoff-worktree`, `herdr_handoff`, `/btw`, `/rename`, and `/done`. Herdr also shows the pane as blocked while a Pi dialog waits for your answer.
 
 ![Architecture overview showing one Pi extension entry point registering four internal handlers, with shared Herdr CLI and task-model routing dependencies.](./docs/workflow-overview.svg)
 
@@ -43,10 +43,14 @@ The shared [`@henryqw/pi-herdr`](https://pi.henry.wang/packages/pi-herdr) CLI li
 
 Run `/clone-tab` to open a clone tab with an active-path clone. The original session stays open.
 
+Commands and prompts are for humans. Tools are for agents.
+
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `/clone-tab` | command | Clone the current conversation into a new tab of the current Herdr workspace. |
 | `/clone-worktree` | command | Clone the current conversation into a new Herdr Git worktree workspace. |
+| `/handoff-worktree <issue>` | prompt | For humans: tell the agent to write a self-contained task prompt for the issue and send it with `herdr_handoff`. |
+| `herdr_handoff` | tool | For agents inside Herdr: create a worktree from local `main`, start Pi in it, and submit a task prompt. Focus does not change. |
 | `/done [-f]` | command | Remove the current worktree and close its Herdr workspace tabs. `-f` (alias `--force`) skips confirmation. It permits forced removal and does not look for tabs in other workspaces. |
 | `/btw [<question...>]` | command | For humans in Main: open an empty side pane, or start with an editable question draft. |
 | `/btw ask <question...>` | command | For humans in Main: ask a question whose first word is `ask`, `config`, `merge`, or `help`. |
@@ -66,6 +70,19 @@ The active path goes from the session root to its current leaf at the time that
 
 Commit or discard changes in a Herdr-managed linked worktree. Then run `/done` and confirm. Normal removal does not remove dirty worktrees or worktrees that another Herdr workspace uses. **`/done -f` can irreversibly delete uncommitted work and leave other workspaces' tabs pointing at the removed checkout.**
 
+### Hand off an issue
+
+In a Herdr-managed Pi pane, run `/handoff-worktree Fix the flaky login test`. The agent collects the missing facts and writes one self-contained task prompt. It asks one question only when the repository, expected outcome, or a critical constraint is not clear. Then it calls `herdr_handoff` and reports the workspace, branch, checkout path, and agent name. It does not wait for the new agent to finish. A worktree handoff does not copy the current conversation.
+
+`herdr_handoff` requires `HERDR_ENV=1`, `HERDR_PANE_ID`, and a local `main` branch. The current directory and the Herdr workspace of the pane must be in the same Git repository. Pi registers the tool only when `HERDR_ENV=1`. It takes these parameters, and each must be a non-empty string:
+
+| Parameter | Purpose |
+| --- | --- |
+| `branch` | New Git branch. Herdr creates it from local `main`. The branch must not exist. |
+| `label` | Herdr workspace label. |
+| `agentName` | Unique Herdr agent name for the new Pi agent. It must match `^[a-z][a-z0-9_-]{0,31}$`. |
+| `prompt` | Self-contained task prompt. |
+
 ### Ask and merge side questions
 
 In a Herdr-managed Pi pane with a conversation, run `/btw Why is this test failing?`. A side pane opens with the question as an editable draft. Submit the question there. After the answer, run `/btw merge Apply the smallest safe fix`. Main receives the side-thread transcript, gets the focus again, and continues with the merge prompt.
@@ -108,6 +125,15 @@ Nested dialogs count as one block. `ask_question` from `@henryqw/pi-ask-question
 5. Start Pi in the chosen pane with `--session <absolute-clone-file>`.
 6. Focus the tab of the clone after Pi starts successfully.
 
+#### Hand off to a worktree
+
+1. Make sure that the current directory and the workspace of the pane are in the same Git repository, that the repository has a local `main` branch, and that `branch` does not exist. If not, stop before Herdr changes.
+2. Find the parent workspace of the repository, as `/clone-worktree` does.
+3. Run `herdr worktree create --workspace <parent> --branch <branch> --base main --label <label> --no-focus`.
+4. Select the root pane, or an additional tab when a worktree-layout plugin uses the root pane, as `/clone-worktree` does. Start Pi with the agent name and no session arguments.
+5. Submit the prompt with `herdr agent prompt <agentName> <prompt> --wait --until working --timeout 30000`. The prompt goes to Herdr as one argument, not through a shell or a file.
+6. Return the workspace ID, tab, pane, branch, checkout path, and agent name. Focus does not change.
+
 #### Finish a worktree
 
 ![Sequence of /done safety gates, cleanup order, and conditional parent update.](./docs/done-flow.svg)
@@ -198,6 +224,18 @@ The Pi session stores each generated display title and semantic branch in a `pi-
 | Agent start attempted | The launch outcome can be unknown. Keep the target tab, panes, and session file. The error reports known IDs for recovery. |
 | Focus failed after Pi started | Show a warning, but do not report the clone that already started as failed. If necessary, focus the clone tab in Herdr. |
 
+### Worktree handoff
+
+| Outcome | What remains and how to recover |
+| --- | --- |
+| No local `main`, an existing branch, a different repository, missing Herdr environment, or failed worktree creation | Nothing. The tool stops before it creates a worktree. |
+| Tool call cancelled | Before worktree creation, nothing remains. After it, the tool does not start the agent or submit the prompt, and the error names the resources that remain. |
+| Killed or incomplete worktree creation | Herdr can keep partial workspace state. The error reports all returned IDs and tells you to examine `herdr workspace list`. |
+| Agent start or prompt delivery failed | The worktree, branch, workspace, tab, and pane remain. The error names each of them and the agent. The tool does no cleanup. A stalled or timed-out prompt can still be delivered. Before you send it again, examine the agent with `herdr agent get` and `herdr agent read`. Send the prompt again with `herdr agent prompt` only when the agent did not get it. Or run `/done` in the new worktree. |
+| Agent was already blocked, or did not start to work | Herdr reports `agent_blocked` or `agent_prompt_stalled`. The tool reports this as a prompt delivery failure. |
+
+If you also keep a personal prompt template with the name `handoff-worktree.md`, Pi loads only one of the two and reports a name collision. Remove the personal copy to use the package prompt.
+
 ### Worktree completion
 
 - `/done` does not remove a dirty worktree. Commit or discard changes first. `/done -f` passes `--force` to Git and can irreversibly delete uncommitted work.

package/docs/workflow-overview.html

@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Herdr tools: one extension, four workflows</title>
+  <title>Herdr tools: one extension, five workflows</title>
   <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
   <style>
     * { box-sizing: border-box; }
@@ -18,8 +18,8 @@
 <main>
   <div class="diagram-container">
     <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="workflow-overview-title workflow-overview-desc">
-      <title id="workflow-overview-title">Herdr tools: one extension, four workflows</title>
-      <desc id="workflow-overview-desc">One Pi extension registers clone, side-question, title, and completion handlers that share the Herdr CLI library, with task-model routing used only for side questions and titles.</desc>
+      <title id="workflow-overview-title">Herdr tools: one extension, five workflows</title>
+      <desc id="workflow-overview-desc">One Pi extension registers clone, handoff, side-question, title, and completion handlers that share the Herdr CLI library, with task-model routing used only for side questions and titles.</desc>
       <defs>
         <style>
           .title { fill: #101828; font: 400 28px 'Instrument Serif', Georgia, serif; }
@@ -36,15 +36,16 @@
         <marker id="arrow-accent" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><path d="M0 0 L8 3 L0 6 Z" fill="#1d4ed8"/></marker>
       </defs>
       <rect width="1280" height="720" fill="#f0eee9"/>
-      <text class="title" x="40" y="56">One extension, four workflows</text>
+      <text class="title" x="40" y="56">One extension, five workflows</text>
       <text class="technical" x="1240" y="56" text-anchor="end">@henryqw/pi-herdr-tools</text>
       <rect x="552" y="76" width="288" height="540" rx="8" fill="#e6e4de" stroke="#101828" stroke-opacity=".12"/>
       <text class="tag" x="568" y="92">INTERNAL HANDLERS</text>
       <path class="primary" d="M208 336 H248"/>
-      <path class="edge" d="M464 288 H488 Q496 288 496 280 V168 Q496 160 504 160 H568"/>
-      <path class="edge" d="M464 320 H500 Q508 320 508 312 V296 Q508 288 516 288 H568"/>
-      <path class="edge" d="M464 352 H524 Q532 352 532 360 V408 Q532 416 540 416 H568"/>
-      <path class="edge" d="M464 384 H512 Q520 384 520 392 V536 Q520 544 528 544 H568"/>
+      <path class="edge" d="M464 272 H488 Q496 272 496 264 V156 Q496 148 504 148 H568"/>
+      <path class="edge" d="M464 304 H500 Q508 304 508 296 V260 Q508 252 516 252 H568"/>
+      <path class="edge" d="M464 336 H512 Q520 336 520 344 V348 Q520 356 528 356 H568"/>
+      <path class="edge" d="M464 368 H536 Q544 368 544 376 V452 Q544 460 552 460 H568"/>
+      <path class="edge" d="M464 400 H524 Q532 400 532 408 V556 Q532 564 540 564 H568"/>
       <path class="edge" d="M840 256 H1040"/>
       <path class="edge" d="M840 436 H1040"/>
       <rect x="896" y="232" width="88" height="14" rx="2" fill="#f0eee9"/>
@@ -62,38 +63,44 @@
         <text class="tag" x="264" y="280">ONE LOADED EXTENSION</text>
         <text class="name" x="264" y="316">Herdr tools</text>
         <text class="technical" x="264" y="340">extensions/index.ts</text>
-        <text class="body" x="264" y="372">Registers all four handlers.</text>
+        <text class="body" x="264" y="372">Registers all five handlers.</text>
         <text class="body" x="264" y="392">Not separate resources.</text>
       </g>
       <g>
-        <rect class="node" x="568" y="112" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="136">internal/clone-tab.ts</text>
-        <text class="name" x="584" y="160">Clone conversations</text>
-        <text class="technical" x="584" y="184">/clone-tab · /clone-worktree</text>
+        <rect class="node" x="568" y="104" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="128">internal/clone-tab.ts</text>
+        <text class="name" x="584" y="152">Clone conversations</text>
+        <text class="technical" x="584" y="176">/clone-tab · /clone-worktree</text>
       </g>
       <g>
-        <rect class="node" x="568" y="240" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="264">internal/btw.ts</text>
-        <text class="name" x="584" y="288">Ask and merge side questions</text>
-        <text class="technical" x="584" y="312">/btw · /btw merge</text>
+        <rect class="node" x="568" y="208" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="232">internal/handoff.ts</text>
+        <text class="name" x="584" y="256">Hand off issues</text>
+        <text class="technical" x="584" y="280">/handoff-worktree · herdr_handoff</text>
       </g>
       <g>
-        <rect class="node" x="568" y="368" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="392">internal/rename.ts</text>
-        <text class="name" x="584" y="416">Name conversations</text>
-        <text class="technical" x="584" y="440">/rename · automatic titles</text>
+        <rect class="node" x="568" y="312" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="336">internal/btw.ts</text>
+        <text class="name" x="584" y="360">Ask and merge side questions</text>
+        <text class="technical" x="584" y="384">/btw · /btw merge</text>
       </g>
       <g>
-        <rect class="node" x="568" y="496" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="520">internal/done.ts</text>
-        <text class="name" x="584" y="544">Finish worktrees</text>
-        <text class="technical" x="584" y="568">/done [--force]</text>
+        <rect class="node" x="568" y="416" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="440">internal/rename.ts</text>
+        <text class="name" x="584" y="464">Name conversations</text>
+        <text class="technical" x="584" y="488">/rename · automatic titles</text>
+      </g>
+      <g>
+        <rect class="node" x="568" y="520" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="544">internal/done.ts</text>
+        <text class="name" x="584" y="568">Finish worktrees</text>
+        <text class="technical" x="584" y="592">/done [--force]</text>
       </g>
       <g>
         <rect class="node" x="1040" y="208" width="200" height="96" rx="6"/>
         <text class="technical" x="1056" y="232">@henryqw/pi-herdr</text>
         <text class="name" x="1056" y="256">Shared Herdr CLI library</text>
-        <text class="body" x="1056" y="280">Used by all four handlers.</text>
+        <text class="body" x="1056" y="280">Used by all five handlers.</text>
       </g>
       <g>
         <rect class="node" x="1040" y="388" width="200" height="96" rx="6"/>

package/docs/workflow-overview.svg

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="workflow-overview-title workflow-overview-desc" id="workflow-overview-root">
-      <title id="workflow-overview-title">Herdr tools: one extension, four workflows</title>
-      <desc id="workflow-overview-desc">One Pi extension registers clone, side-question, title, and completion handlers that share the Herdr CLI library, with task-model routing used only for side questions and titles.</desc>
+      <title id="workflow-overview-title">Herdr tools: one extension, five workflows</title>
+      <desc id="workflow-overview-desc">One Pi extension registers clone, handoff, side-question, title, and completion handlers that share the Herdr CLI library, with task-model routing used only for side questions and titles.</desc>
       <defs>
       <style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;family=Noto+Serif:ital@0;1&amp;family=Noto+Sans+KR:wght@400;500;600&amp;family=Noto+Serif+KR:wght@400&amp;family=Noto+Sans+TC:wght@400;500;600&amp;family=Noto+Serif+TC:wght@400&amp;display=swap');
       #workflow-overview-root { color: #101828; }
@@ -31,15 +31,16 @@
         <marker id="workflow-overview-arrow-accent" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><path d="M0 0 L8 3 L0 6 Z" fill="#1d4ed8"/></marker>
       </defs>
       <rect width="1280" height="720" fill="#f0eee9"/>
-      <text class="title" x="40" y="56">One extension, four workflows</text>
+      <text class="title" x="40" y="56">One extension, five workflows</text>
       <text class="technical" x="1240" y="56" text-anchor="end">@henryqw/pi-herdr-tools</text>
       <rect x="552" y="76" width="288" height="540" rx="8" fill="#e6e4de" stroke="#101828" stroke-opacity=".12"/>
       <text class="tag" x="568" y="92">INTERNAL HANDLERS</text>
       <path class="primary" d="M208 336 H248"/>
-      <path class="edge" d="M464 288 H488 Q496 288 496 280 V168 Q496 160 504 160 H568"/>
-      <path class="edge" d="M464 320 H500 Q508 320 508 312 V296 Q508 288 516 288 H568"/>
-      <path class="edge" d="M464 352 H524 Q532 352 532 360 V408 Q532 416 540 416 H568"/>
-      <path class="edge" d="M464 384 H512 Q520 384 520 392 V536 Q520 544 528 544 H568"/>
+      <path class="edge" d="M464 272 H488 Q496 272 496 264 V156 Q496 148 504 148 H568"/>
+      <path class="edge" d="M464 304 H500 Q508 304 508 296 V260 Q508 252 516 252 H568"/>
+      <path class="edge" d="M464 336 H512 Q520 336 520 344 V348 Q520 356 528 356 H568"/>
+      <path class="edge" d="M464 368 H536 Q544 368 544 376 V452 Q544 460 552 460 H568"/>
+      <path class="edge" d="M464 400 H524 Q532 400 532 408 V556 Q532 564 540 564 H568"/>
       <path class="edge" d="M840 256 H1040"/>
       <path class="edge" d="M840 436 H1040"/>
       <rect x="896" y="232" width="88" height="14" rx="2" fill="#f0eee9"/>
@@ -57,38 +58,44 @@
         <text class="tag" x="264" y="280">ONE LOADED EXTENSION</text>
         <text class="name" x="264" y="316">Herdr tools</text>
         <text class="technical" x="264" y="340">extensions/index.ts</text>
-        <text class="body" x="264" y="372">Registers all four handlers.</text>
+        <text class="body" x="264" y="372">Registers all five handlers.</text>
         <text class="body" x="264" y="392">Not separate resources.</text>
       </g>
       <g>
-        <rect class="node" x="568" y="112" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="136">internal/clone-tab.ts</text>
-        <text class="name" x="584" y="160">Clone conversations</text>
-        <text class="technical" x="584" y="184">/clone-tab · /clone-worktree</text>
+        <rect class="node" x="568" y="104" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="128">internal/clone-tab.ts</text>
+        <text class="name" x="584" y="152">Clone conversations</text>
+        <text class="technical" x="584" y="176">/clone-tab · /clone-worktree</text>
       </g>
       <g>
-        <rect class="node" x="568" y="240" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="264">internal/btw.ts</text>
-        <text class="name" x="584" y="288">Ask and merge side questions</text>
-        <text class="technical" x="584" y="312">/btw · /btw merge</text>
+        <rect class="node" x="568" y="208" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="232">internal/handoff.ts</text>
+        <text class="name" x="584" y="256">Hand off issues</text>
+        <text class="technical" x="584" y="280">/handoff-worktree · herdr_handoff</text>
       </g>
       <g>
-        <rect class="node" x="568" y="368" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="392">internal/rename.ts</text>
-        <text class="name" x="584" y="416">Name conversations</text>
-        <text class="technical" x="584" y="440">/rename · automatic titles</text>
+        <rect class="node" x="568" y="312" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="336">internal/btw.ts</text>
+        <text class="name" x="584" y="360">Ask and merge side questions</text>
+        <text class="technical" x="584" y="384">/btw · /btw merge</text>
       </g>
       <g>
-        <rect class="node" x="568" y="496" width="240" height="96" rx="6"/>
-        <text class="technical" x="584" y="520">internal/done.ts</text>
-        <text class="name" x="584" y="544">Finish worktrees</text>
-        <text class="technical" x="584" y="568">/done [--force]</text>
+        <rect class="node" x="568" y="416" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="440">internal/rename.ts</text>
+        <text class="name" x="584" y="464">Name conversations</text>
+        <text class="technical" x="584" y="488">/rename · automatic titles</text>
+      </g>
+      <g>
+        <rect class="node" x="568" y="520" width="240" height="88" rx="6"/>
+        <text class="technical" x="584" y="544">internal/done.ts</text>
+        <text class="name" x="584" y="568">Finish worktrees</text>
+        <text class="technical" x="584" y="592">/done [--force]</text>
       </g>
       <g>
         <rect class="node" x="1040" y="208" width="200" height="96" rx="6"/>
         <text class="technical" x="1056" y="232">@henryqw/pi-herdr</text>
         <text class="name" x="1056" y="256">Shared Herdr CLI library</text>
-        <text class="body" x="1056" y="280">Used by all four handlers.</text>
+        <text class="body" x="1056" y="280">Used by all five handlers.</text>
       </g>
       <g>
         <rect class="node" x="1040" y="388" width="200" height="96" rx="6"/>

package/extensions/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import registerBtwExtension from "../internal/btw.ts";
 import herdrCloneExtension from "../internal/clone-tab.ts";
 import herdrDoneExtension from "../internal/done.ts";
+import herdrHandoffExtension from "../internal/handoff.ts";
 import herdrRenameExtension from "../internal/rename.ts";
 
 export default async function herdrToolsExtension(pi: ExtensionAPI): Promise<void> {
@@ -9,6 +10,7 @@ export default async function herdrToolsExtension(pi: ExtensionAPI): Promise<voi
 	await registerBtwExtension(pi);
 	herdrCloneExtension(pi);
 	herdrDoneExtension(pi);
+	herdrHandoffExtension(pi);
 	registerDialogStatus(pi);
 }
 

package/internal/clone-tab.ts

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { stat, unlink, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
 import {
 	CURRENT_SESSION_VERSION,
 	SessionManager,
@@ -12,35 +11,25 @@ import {
 import {
 	createHerdrClient,
 	herdrCommandFailure,
-	startPiAgent,
 	withWorktreeLock,
 	type HerdrClient,
 	type HerdrExecResult,
 } from "@henryqw/pi-herdr";
-
-type WorkspaceInfo = {
-	workspace_id?: unknown;
-	worktree?: {
-		checkout_path?: unknown;
-		repo_root?: unknown;
-		is_linked_worktree?: unknown;
-	} | null;
-};
-
-const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
-
-function requiredString(value: unknown, label: string): string {
-	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is missing.`);
-	return value;
-}
-
-type SourceContext = {
+import {
+	createWorktree,
+	errorMessage,
+	launchPiAgent,
+	parseCreatedTab,
+	prepareWorktreeLaunch,
+	requiredString,
+	resolveWorkspace,
+	worktreeParentWorkspace,
+	type HerdrWorkspace,
+} from "./worktree.ts";
+
+type SourceContext = HerdrWorkspace & {
 	sessionFile: string;
 	leafId: string;
-	workspaceId: string;
-	checkout: string | undefined;
-	repoRoot: string | undefined;
-	isLinkedWorktree: boolean;
 	/** False while Pi has not flushed the session yet (no conversation message on disk). */
 	persisted: boolean;
 };
@@ -71,26 +60,7 @@ async function resolveSource(
 		persisted = false;
 	}
 
-	const paneResponse = await herdr.json(["pane", "get", requestedPaneId], { cwd: ctx.cwd });
-	const pane = (paneResponse as { result?: { pane?: { pane_id?: unknown; workspace_id?: unknown } } }).result?.pane;
-	requiredString(pane?.pane_id, "Herdr pane response pane_id");
-	const workspaceId = requiredString(pane?.workspace_id, "Herdr pane response workspace_id");
-	const workspaceResponse = await herdr.json(["workspace", "get", workspaceId], { cwd: ctx.cwd });
-	const workspace = (workspaceResponse as { result?: { workspace?: WorkspaceInfo } }).result?.workspace;
-	if (requiredString(workspace?.workspace_id, "Herdr workspace response workspace_id") !== workspaceId) {
-		throw new Error(`Herdr workspace response did not match ${workspaceId}.`);
-	}
-	const checkout = workspace?.worktree == null
-		? undefined
-		: requiredString(workspace.worktree.checkout_path, "Herdr workspace response checkout_path");
-	const repoRoot = typeof workspace?.worktree?.repo_root === "string" && workspace.worktree.repo_root.trim()
-		? workspace.worktree.repo_root
-		: undefined;
-	const isLinkedWorktree = workspace?.worktree?.is_linked_worktree === true;
-	if (isLinkedWorktree && !repoRoot) {
-		throw new Error("Herdr workspace response is missing worktree.repo_root for a linked worktree.");
-	}
-	return { sessionFile, leafId, workspaceId, checkout, repoRoot, isLinkedWorktree, persisted };
+	return { sessionFile, leafId, persisted, ...await resolveWorkspace(herdr, ctx.cwd, requestedPaneId) };
 }
 
 // Mirror of SessionManager.createBranchedSession for sessions Pi has not
@@ -138,46 +108,6 @@ async function createBranchedClone(
 	throw new Error(`Pi clone session path is not a file: ${cloneFile}`);
 }
 
-// A worktree layout plugin (e.g. herdr-plus) can start its own agent in a new
-// worktree's root pane right after creation. Give it a moment to appear so the
-// clone can move to its own tab instead of failing with agent_pane_busy.
-async function waitForRootPaneAgent(
-	herdr: HerdrClient<{ cwd: string }>,
-	ctx: ExtensionCommandContext,
-	paneId: string,
-): Promise<string | undefined> {
-	for (let attempt = 0; attempt < 12; attempt += 1) {
-		const response = await herdr.json(["pane", "get", paneId], { cwd: ctx.cwd });
-		const agent = (response as { result?: { pane?: { agent?: unknown } } }).result?.pane?.agent;
-		if (typeof agent === "string" && agent.trim()) return agent;
-		await delay(250);
-	}
-	return undefined;
-}
-
-function parseCreatedTab(createdTab: HerdrExecResult, workspaceId: string): { tabId: string; rootPaneId: string } {
-	let tabId: string | undefined;
-	let rootPaneId: string | undefined;
-	try {
-		const response: unknown = JSON.parse(createdTab.stdout);
-		if (!response || typeof response !== "object" || Array.isArray(response)) {
-			throw new Error("Herdr tab create returned invalid JSON");
-		}
-		const result = (response as { result?: { tab?: { tab_id?: unknown }; root_pane?: { pane_id?: unknown } } }).result;
-		tabId = typeof result?.tab?.tab_id === "string" && result.tab.tab_id.trim() ? result.tab.tab_id : undefined;
-		rootPaneId = typeof result?.root_pane?.pane_id === "string" && result.root_pane.pane_id.trim()
-			? result.root_pane.pane_id
-			: undefined;
-		const missing = [!tabId && "tab_id", !rootPaneId && "root_pane.pane_id"].filter(Boolean).join(", ");
-		if (missing) throw new Error(`Herdr tab create response is missing ${missing}.`);
-		return { tabId: tabId!, rootPaneId: rootPaneId! };
-	} catch (error) {
-		const retained = [`workspace ${workspaceId}`, tabId && `tab ${tabId}`, rootPaneId && `root pane ${rootPaneId}`]
-			.filter(Boolean).join(", ");
-		throw new Error(`Herdr tab create response could not be parsed; retained ${retained}: ${errorMessage(error)}`, { cause: error });
-	}
-}
-
 async function discardCloneOrAggregate(cloneFile: string, error: Error): Promise<never> {
 	try {
 		await unlink(cloneFile);
@@ -190,42 +120,7 @@ async function discardCloneOrAggregate(cloneFile: string, error: Error): Promise
 	throw error;
 }
 
-async function launchCloneAgent(
-	herdr: HerdrClient<{ cwd: string }>,
-	ctx: ExtensionCommandContext,
-	rootPaneId: string,
-	cloneFile: string,
-	retained: string,
-	onPaneBusy?: () => Promise<{ rootPaneId: string; retained: string }>,
-): Promise<string> {
-	const agentName = `clone-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
-	try {
-		const result = await startPiAgent(herdr, {
-			name: agentName,
-			pane: rootPaneId,
-			args: ["--session", cloneFile],
-			options: { cwd: ctx.cwd },
-			onPaneBusy: onPaneBusy
-				? async () => {
-					const next = await onPaneBusy!();
-					rootPaneId = next.rootPaneId;
-					retained = next.retained;
-					return rootPaneId;
-				}
-				: undefined,
-		});
-		if (result.code === 0 && !result.killed) return agentName;
-		const startArgs = [
-			"agent", "start", agentName, "--kind", "pi", "--pane", rootPaneId, "--", "--session", cloneFile,
-		];
-		throw new Error(herdrCommandFailure(startArgs, result));
-	} catch (error) {
-		throw new Error(
-			`Clone launch could not be confirmed after starting agent ${agentName}; retained ${retained}: ${errorMessage(error)}`,
-			{ cause: error },
-		);
-	}
-}
+const cloneAgentName = () => `clone-${randomUUID().replaceAll("-", "").slice(0, 24)}`;
 
 export default function herdrCloneExtension(pi: ExtensionAPI): void {
 	const herdr = createHerdrClient<{ cwd: string }>(pi.exec.bind(pi));
@@ -254,7 +149,14 @@ export default function herdrCloneExtension(pi: ExtensionAPI): void {
 				);
 			}
 			const { tabId, rootPaneId } = tab;
-			const agentName = await launchCloneAgent(herdr, ctx, rootPaneId, cloneFile, `Herdr tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}`);
+			const agentName = cloneAgentName();
+			await launchPiAgent(herdr, ctx.cwd, {
+				action: "Clone",
+				name: agentName,
+				pane: rootPaneId,
+				args: ["--session", cloneFile],
+				retained: () => `Herdr tab ${tabId}, root pane ${rootPaneId}, and session ${cloneFile}`,
+			});
 
 			try {
 				await herdr.run(["tab", "focus", tabId], { cwd: ctx.cwd });
@@ -277,115 +179,36 @@ export default function herdrCloneExtension(pi: ExtensionAPI): void {
 		handler: async (_args, ctx) => {
 			const source = await resolveSource("clone-worktree", herdr, ctx);
 
-			// Herdr only creates worktrees from the repo parent workspace; running
-			// /clone-worktree inside a linked worktree must retarget the parent.
-			let targetWorkspaceId = source.workspaceId;
-			if (source.isLinkedWorktree) {
-				const listing = await herdr.json(["workspace", "list"], { cwd: ctx.cwd });
-				const result = (listing as { result?: { workspaces?: WorkspaceInfo[] } }).result;
-				const parent = (Array.isArray(result?.workspaces) ? result.workspaces : []).find((entry) =>
-					entry.worktree != null && !entry.worktree.is_linked_worktree &&
-					entry.worktree.checkout_path === source.repoRoot);
-				targetWorkspaceId = typeof parent?.workspace_id === "string"
-					? parent.workspace_id
-					: requiredString(undefined, `Repo parent workspace for ${source.repoRoot} in herdr workspace list`);
-			}
 			// Create the worktree before the clone so the session header can be
-			// stamped with the fresh checkout cwd. A killed or incomplete create is
-			// ambiguous: Herdr may have retained partial worktree state.
-			const worktreeCreateArgs = ["worktree", "create", "--workspace", targetWorkspaceId, "--no-focus"] as const;
-			const createdWorktree = await herdr.exec(worktreeCreateArgs, { cwd: ctx.cwd });
-			if (createdWorktree.code !== 0 && !createdWorktree.killed) {
-				throw new Error(herdrCommandFailure(worktreeCreateArgs, createdWorktree));
-			}
-
-			let workspaceId: string | undefined;
-			let tabId: string | undefined;
-			let rootPaneId: string | undefined;
-			let checkoutPath: string | undefined;
-			try {
-				const response: unknown = JSON.parse(createdWorktree.stdout);
-				if (!response || typeof response !== "object" || Array.isArray(response)) {
-					throw new Error("Herdr worktree create returned invalid JSON");
-				}
-				// Herdr nests checkout_path under workspace.worktree; the top-level
-				// result.worktree uses `path` instead.
-				const result = (response as {
-					result?: {
-						workspace?: { workspace_id?: unknown; worktree?: { checkout_path?: unknown } };
-						tab?: { tab_id?: unknown };
-						root_pane?: { pane_id?: unknown };
-					};
-				}).result;
-				// Collect every returned identifier before validating so recovery
-				// keeps all known IDs even when an earlier field is missing.
-				workspaceId = typeof result?.workspace?.workspace_id === "string" ? result.workspace.workspace_id : undefined;
-				tabId = typeof result?.tab?.tab_id === "string" ? result.tab.tab_id : undefined;
-				rootPaneId = typeof result?.root_pane?.pane_id === "string" ? result.root_pane.pane_id : undefined;
-				checkoutPath = typeof result?.workspace?.worktree?.checkout_path === "string" && result.workspace.worktree.checkout_path.trim()
-					? result.workspace.worktree.checkout_path
-					: undefined;
-				if (createdWorktree.killed) {
-					throw new Error("Herdr worktree create was killed before completion.");
-				}
-				const missing = [
-					[workspaceId, "workspace_id"],
-					[tabId, "tab_id"],
-					[rootPaneId, "root_pane.pane_id"],
-					[checkoutPath, "workspace.worktree.checkout_path"],
-				].filter(([value]) => !value).map(([, label]) => label);
-				if (missing.length > 0) {
-					throw new Error(`Herdr worktree create response is missing ${missing.join(", ")}.`);
-				}
-			} catch (error) {
-				const known = [
-					workspaceId && `workspace ${workspaceId}`,
-					tabId && `tab ${tabId}`,
-					rootPaneId && `root pane ${rootPaneId}`,
-					checkoutPath && `checkout ${checkoutPath}`,
-				].filter(Boolean).join(", ");
-				throw new Error(
-					`Clone could not be confirmed after creating a Herdr worktree${known ? ` (${known})` : ""}; Herdr may have retained a partial worktree workspace, inspect herdr workspace list: ${errorMessage(error)}`,
-					{ cause: error },
-				);
-			}
-
-			// A layout plugin may have claimed the root pane; park the clone in its
-			// own tab so both agents coexist.
-			let targetTabId = tabId!;
-			let targetPaneId = rootPaneId!;
-			const createCloneTab = async (): Promise<void> => {
-				const cloneTabArgs = ["tab", "create", "--workspace", workspaceId!, "--cwd", checkoutPath!, "--no-focus"] as const;
-				const createdTab = await herdr.exec(cloneTabArgs, { cwd: ctx.cwd });
-				if (createdTab.code !== 0 || createdTab.killed) {
-					throw new Error(herdrCommandFailure(cloneTabArgs, createdTab));
-				}
-				({ tabId: targetTabId, rootPaneId: targetPaneId } = parseCreatedTab(createdTab, workspaceId!));
-			};
-			if (await waitForRootPaneAgent(herdr, ctx, rootPaneId!)) await createCloneTab();
+			// stamped with the fresh checkout cwd.
+			const worktreeCreateArgs = [
+				"worktree", "create", "--workspace", await worktreeParentWorkspace(herdr, ctx.cwd, source), "--no-focus",
+			];
+			const worktree = await createWorktree(herdr, ctx.cwd, worktreeCreateArgs, "Clone");
+			const { workspaceId, tabId, checkoutPath } = worktree;
+			const { target, onPaneBusy } = await prepareWorktreeLaunch(herdr, ctx.cwd, worktree);
 
 			let cloneFile: string;
 			try {
 				cloneFile = source.checkout
-					? await withWorktreeLock(source.checkout, () => createBranchedClone(ctx, source, checkoutPath!))
-					: await createBranchedClone(ctx, source, checkoutPath!);
+					? await withWorktreeLock(source.checkout, () => createBranchedClone(ctx, source, checkoutPath))
+					: await createBranchedClone(ctx, source, checkoutPath);
 			} catch (error) {
 				throw new Error(
 					`Clone session could not be created for Herdr worktree workspace ${workspaceId} (tab ${tabId}, checkout ${checkoutPath}); retained worktree without a clone session: ${errorMessage(error)}`,
 					{ cause: error },
 				);
 			}
-			const agentName = await launchCloneAgent(
-				herdr, ctx, targetPaneId, cloneFile,
-				`Herdr workspace ${workspaceId}, tab ${targetTabId}, root pane ${targetPaneId}, and session ${cloneFile}`,
-				targetPaneId === rootPaneId ? async () => {
-					await createCloneTab();
-					return {
-						rootPaneId: targetPaneId,
-						retained: `Herdr workspace ${workspaceId}, tab ${targetTabId}, root pane ${targetPaneId}, and session ${cloneFile}`,
-					};
-				} : undefined,
-			);
+			const agentName = cloneAgentName();
+			await launchPiAgent(herdr, ctx.cwd, {
+				action: "Clone",
+				name: agentName,
+				pane: target.paneId,
+				args: ["--session", cloneFile],
+				retained: () => `Herdr workspace ${workspaceId}, tab ${target.tabId}, root pane ${target.paneId}, and session ${cloneFile}`,
+				onPaneBusy,
+			});
+			const targetTabId = target.tabId;
 
 			try {
 				await herdr.run(["tab", "focus", targetTabId], { cwd: ctx.cwd });

package/internal/handoff.ts

@@ -0,0 +1,108 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createHerdrClient, herdrCommandFailure } from "@henryqw/pi-herdr";
+import { Type } from "typebox";
+import {
+	createWorktree,
+	errorMessage,
+	launchPiAgent,
+	prepareWorktreeLaunch,
+	requiredString,
+	resolveWorkspace,
+	worktreeParentWorkspace,
+} from "./worktree.ts";
+
+const PROMPT_TIMEOUT_MS = 30_000;
+
+const nonEmpty = (description: string) => Type.String({ description, minLength: 1, pattern: "\\S" });
+
+const HandoffParams = Type.Object({
+	branch: nonEmpty("New Git branch for the worktree, created from local main"),
+	label: nonEmpty("Short Herdr workspace label"),
+	// Herdr agent names must match this pattern; checking it here fails before any mutation.
+	agentName: Type.String({
+		description: "Unique Herdr agent name for the new Pi agent: lowercase letter, then up to 31 of a-z, 0-9, _ or -",
+		pattern: "^[a-z][a-z0-9_-]{0,31}$",
+	}),
+	prompt: nonEmpty("Self-contained task prompt for the new agent"),
+});
+
+/** Register `herdr_handoff` only inside Herdr, where it can run. */
+export default function herdrHandoffExtension(pi: ExtensionAPI): void {
+	if (process.env.HERDR_ENV !== "1") return;
+	const herdr = createHerdrClient<{ cwd: string }>(pi.exec.bind(pi));
+
+	pi.registerTool({
+		name: "herdr_handoff",
+		label: "Herdr Handoff",
+		description: "Create a Herdr worktree from local main, start Pi in it, and submit a self-contained task prompt. Focus does not change.",
+		promptSnippet: "Hand off a separate task to a new Pi agent in a new Herdr worktree from local main",
+		promptGuidelines: [
+			"Use herdr_handoff only when the user asks to hand off a task to a new worktree, for example through /handoff-worktree.",
+		],
+		parameters: HandoffParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, { branch, label, agentName, prompt }, signal, _onUpdate, ctx) {
+			const paneId = requiredString(process.env.HERDR_PANE_ID, "HERDR_PANE_ID");
+			const workspace = await resolveWorkspace(herdr, ctx.cwd, paneId);
+			const checkout = requiredString(workspace.checkout, `Git checkout of Herdr workspace ${workspace.workspaceId}`);
+			const git = (cwd: string, args: string[]) => pi.exec("git", args, { cwd });
+			const repository = async (cwd: string) => {
+				const result = await git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+				if (result.code !== 0 || result.killed) throw new Error(`herdr_handoff: ${cwd} is not in a Git repository; nothing was created.`);
+				return result.stdout.trim();
+			};
+			// The worktree comes from the pane's workspace, so it must be the repository checked here.
+			if (await repository(ctx.cwd) !== await repository(checkout)) {
+				throw new Error(`herdr_handoff: ${ctx.cwd} and Herdr workspace ${workspace.workspaceId} (${checkout}) are different Git repositories; nothing was created.`);
+			}
+			const main = await git(ctx.cwd, ["rev-parse", "--verify", "--quiet", "refs/heads/main"]);
+			if (main.code !== 0 || main.killed) {
+				throw new Error(`herdr_handoff requires a local main branch in ${ctx.cwd}; nothing was created.`);
+			}
+			// Herdr checks out an existing branch instead of creating it from --base.
+			const existing = await git(ctx.cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+			if (existing.code !== 1 || existing.killed) {
+				throw new Error(`herdr_handoff: branch ${branch} already exists or could not be checked; choose a new branch. Nothing was created.`);
+			}
+			const parentId = await worktreeParentWorkspace(herdr, ctx.cwd, workspace);
+
+			signal?.throwIfAborted();
+			const worktree = await createWorktree(herdr, ctx.cwd, [
+				"worktree", "create", "--workspace", parentId,
+				"--branch", branch, "--base", "main", "--label", label, "--no-focus",
+			], "Handoff");
+			const { workspaceId, checkoutPath } = worktree;
+			const { target, onPaneBusy } = await prepareWorktreeLaunch(herdr, ctx.cwd, worktree).catch((error: unknown) => {
+				throw new Error(
+					`Handoff launch preparation failed; retained Herdr workspace ${workspaceId}, tab ${worktree.tabId}, root pane ${worktree.rootPaneId}, branch ${branch}, checkout ${checkoutPath}: ${errorMessage(error)}`,
+					{ cause: error },
+				);
+			});
+			const retained = () =>
+				`Herdr workspace ${workspaceId}, tab ${target.tabId}, pane ${target.paneId}, branch ${branch}, checkout ${checkoutPath}`;
+			if (signal?.aborted) throw new Error(`Handoff was cancelled before agent start; retained ${retained()}.`);
+			await launchPiAgent(herdr, ctx.cwd, { action: "Handoff", name: agentName, pane: target.paneId, args: [], retained, onPaneBusy });
+
+			const promptArgs = [
+				"agent", "prompt", agentName, prompt, "--wait", "--until", "working", "--timeout", String(PROMPT_TIMEOUT_MS),
+			];
+			if (signal?.aborted) throw new Error(`Handoff was cancelled before prompt delivery; retained ${retained()}, and agent ${agentName}.`);
+			const delivered = await herdr.exec(promptArgs, { cwd: ctx.cwd });
+			if (delivered.code !== 0 || delivered.killed) {
+				throw new Error(
+					`Handoff prompt was not confirmed for agent ${agentName}; retained ${retained()}, and agent ${agentName}: ${herdrCommandFailure(promptArgs, delivered)}`,
+				);
+			}
+
+			const details = { workspaceId, tabId: target.tabId, paneId: target.paneId, branch, checkoutPath, agentName };
+			return {
+				content: [{
+					type: "text" as const,
+					text: `Handed off to agent ${agentName}, which is working in Herdr workspace ${workspaceId} (tab ${target.tabId}, pane ${target.paneId}, branch ${branch}, checkout ${checkoutPath}). Focus did not change.`,
+				}],
+				details,
+			};
+		},
+	});
+}

package/internal/worktree.ts

@@ -0,0 +1,244 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { herdrCommandFailure, startPiAgent, type HerdrClient, type HerdrExecResult } from "@henryqw/pi-herdr";
+
+type Herdr = HerdrClient<{ cwd: string }>;
+
+type WorkspaceInfo = {
+	workspace_id?: unknown;
+	worktree?: {
+		checkout_path?: unknown;
+		repo_root?: unknown;
+		is_linked_worktree?: unknown;
+	} | null;
+};
+
+export type HerdrWorkspace = {
+	workspaceId: string;
+	checkout: string | undefined;
+	repoRoot: string | undefined;
+	isLinkedWorktree: boolean;
+};
+
+export type CreatedWorktree = {
+	workspaceId: string;
+	tabId: string;
+	rootPaneId: string;
+	checkoutPath: string;
+};
+
+export type LaunchTarget = { tabId: string; paneId: string };
+
+export const errorMessage = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+export function requiredString(value: unknown, label: string): string {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is missing.`);
+	return value;
+}
+
+/** Resolve the Herdr workspace that owns `paneId`, with its Git worktree identity. */
+export async function resolveWorkspace(herdr: Herdr, cwd: string, paneId: string): Promise<HerdrWorkspace> {
+	const paneResponse = await herdr.json(["pane", "get", paneId], { cwd });
+	const pane = (paneResponse as { result?: { pane?: { pane_id?: unknown; workspace_id?: unknown } } }).result?.pane;
+	requiredString(pane?.pane_id, "Herdr pane response pane_id");
+	const workspaceId = requiredString(pane?.workspace_id, "Herdr pane response workspace_id");
+	const workspaceResponse = await herdr.json(["workspace", "get", workspaceId], { cwd });
+	const workspace = (workspaceResponse as { result?: { workspace?: WorkspaceInfo } }).result?.workspace;
+	if (requiredString(workspace?.workspace_id, "Herdr workspace response workspace_id") !== workspaceId) {
+		throw new Error(`Herdr workspace response did not match ${workspaceId}.`);
+	}
+	const checkout = workspace?.worktree == null
+		? undefined
+		: requiredString(workspace.worktree.checkout_path, "Herdr workspace response checkout_path");
+	const repoRoot = typeof workspace?.worktree?.repo_root === "string" && workspace.worktree.repo_root.trim()
+		? workspace.worktree.repo_root
+		: undefined;
+	const isLinkedWorktree = workspace?.worktree?.is_linked_worktree === true;
+	if (isLinkedWorktree && !repoRoot) {
+		throw new Error("Herdr workspace response is missing worktree.repo_root for a linked worktree.");
+	}
+	return { workspaceId, checkout, repoRoot, isLinkedWorktree };
+}
+
+/**
+ * Herdr only creates worktrees from the repo parent workspace; a linked
+ * worktree must retarget the parent.
+ */
+export async function worktreeParentWorkspace(herdr: Herdr, cwd: string, workspace: HerdrWorkspace): Promise<string> {
+	if (!workspace.isLinkedWorktree) return workspace.workspaceId;
+	const listing = await herdr.json(["workspace", "list"], { cwd });
+	const result = (listing as { result?: { workspaces?: WorkspaceInfo[] } }).result;
+	const parent = (Array.isArray(result?.workspaces) ? result.workspaces : []).find((entry) =>
+		entry.worktree != null && !entry.worktree.is_linked_worktree &&
+		entry.worktree.checkout_path === workspace.repoRoot);
+	return typeof parent?.workspace_id === "string"
+		? parent.workspace_id
+		: requiredString(undefined, `Repo parent workspace for ${workspace.repoRoot} in herdr workspace list`);
+}
+
+/**
+ * Run `herdr worktree create` and parse its response. A killed or incomplete
+ * create is ambiguous: Herdr may have retained partial worktree state, so the
+ * error names every returned identifier. `action` prefixes that error.
+ */
+export async function createWorktree(
+	herdr: Herdr,
+	cwd: string,
+	args: readonly string[],
+	action: string,
+): Promise<CreatedWorktree> {
+	const createdWorktree = await herdr.exec(args, { cwd });
+	if (createdWorktree.code !== 0 && !createdWorktree.killed) {
+		throw new Error(herdrCommandFailure(args, createdWorktree));
+	}
+
+	let workspaceId: string | undefined;
+	let tabId: string | undefined;
+	let rootPaneId: string | undefined;
+	let checkoutPath: string | undefined;
+	try {
+		const response: unknown = JSON.parse(createdWorktree.stdout);
+		if (!response || typeof response !== "object" || Array.isArray(response)) {
+			throw new Error("Herdr worktree create returned invalid JSON");
+		}
+		// Herdr nests checkout_path under workspace.worktree; the top-level
+		// result.worktree uses `path` instead.
+		const result = (response as {
+			result?: {
+				workspace?: { workspace_id?: unknown; worktree?: { checkout_path?: unknown } };
+				tab?: { tab_id?: unknown };
+				root_pane?: { pane_id?: unknown };
+			};
+		}).result;
+		// Collect every returned identifier before validating so recovery
+		// keeps all known IDs even when an earlier field is missing.
+		workspaceId = typeof result?.workspace?.workspace_id === "string" ? result.workspace.workspace_id : undefined;
+		tabId = typeof result?.tab?.tab_id === "string" ? result.tab.tab_id : undefined;
+		rootPaneId = typeof result?.root_pane?.pane_id === "string" ? result.root_pane.pane_id : undefined;
+		checkoutPath = typeof result?.workspace?.worktree?.checkout_path === "string" && result.workspace.worktree.checkout_path.trim()
+			? result.workspace.worktree.checkout_path
+			: undefined;
+		if (createdWorktree.killed) {
+			throw new Error("Herdr worktree create was killed before completion.");
+		}
+		const missing = [
+			[workspaceId, "workspace_id"],
+			[tabId, "tab_id"],
+			[rootPaneId, "root_pane.pane_id"],
+			[checkoutPath, "workspace.worktree.checkout_path"],
+		].filter(([value]) => !value).map(([, label]) => label);
+		if (missing.length > 0) {
+			throw new Error(`Herdr worktree create response is missing ${missing.join(", ")}.`);
+		}
+	} catch (error) {
+		const known = [
+			workspaceId && `workspace ${workspaceId}`,
+			tabId && `tab ${tabId}`,
+			rootPaneId && `root pane ${rootPaneId}`,
+			checkoutPath && `checkout ${checkoutPath}`,
+		].filter(Boolean).join(", ");
+		throw new Error(
+			`${action} could not be confirmed after creating a Herdr worktree${known ? ` (${known})` : ""}; Herdr may have retained a partial worktree workspace, inspect herdr workspace list: ${errorMessage(error)}`,
+			{ cause: error },
+		);
+	}
+	return { workspaceId: workspaceId!, tabId: tabId!, rootPaneId: rootPaneId!, checkoutPath: checkoutPath! };
+}
+
+export function parseCreatedTab(createdTab: HerdrExecResult, workspaceId: string): { tabId: string; rootPaneId: string } {
+	let tabId: string | undefined;
+	let rootPaneId: string | undefined;
+	try {
+		const response: unknown = JSON.parse(createdTab.stdout);
+		if (!response || typeof response !== "object" || Array.isArray(response)) {
+			throw new Error("Herdr tab create returned invalid JSON");
+		}
+		const result = (response as { result?: { tab?: { tab_id?: unknown }; root_pane?: { pane_id?: unknown } } }).result;
+		tabId = typeof result?.tab?.tab_id === "string" && result.tab.tab_id.trim() ? result.tab.tab_id : undefined;
+		rootPaneId = typeof result?.root_pane?.pane_id === "string" && result.root_pane.pane_id.trim()
+			? result.root_pane.pane_id
+			: undefined;
+		const missing = [!tabId && "tab_id", !rootPaneId && "root_pane.pane_id"].filter(Boolean).join(", ");
+		if (missing) throw new Error(`Herdr tab create response is missing ${missing}.`);
+		return { tabId: tabId!, rootPaneId: rootPaneId! };
+	} catch (error) {
+		const retained = [`workspace ${workspaceId}`, tabId && `tab ${tabId}`, rootPaneId && `root pane ${rootPaneId}`]
+			.filter(Boolean).join(", ");
+		throw new Error(`Herdr tab create response could not be parsed; retained ${retained}: ${errorMessage(error)}`, { cause: error });
+	}
+}
+
+// A worktree layout plugin (e.g. herdr-plus) can start its own agent in a new
+// worktree's root pane right after creation. Give it a moment to appear so the
+// new agent can move to its own tab instead of failing with agent_pane_busy.
+async function waitForRootPaneAgent(herdr: Herdr, cwd: string, paneId: string): Promise<string | undefined> {
+	for (let attempt = 0; attempt < 12; attempt += 1) {
+		const response = await herdr.json(["pane", "get", paneId], { cwd });
+		const agent = (response as { result?: { pane?: { agent?: unknown } } }).result?.pane?.agent;
+		if (typeof agent === "string" && agent.trim()) return agent;
+		await delay(250);
+	}
+	return undefined;
+}
+
+/**
+ * Choose the pane for a new agent in a created worktree. A layout plugin may
+ * claim the root pane; park the agent in its own tab so both coexist. The
+ * returned target updates in place when `onPaneBusy` creates that tab later.
+ */
+export async function prepareWorktreeLaunch(
+	herdr: Herdr,
+	cwd: string,
+	worktree: CreatedWorktree,
+): Promise<{ target: LaunchTarget; onPaneBusy?: () => Promise<string> }> {
+	const target: LaunchTarget = { tabId: worktree.tabId, paneId: worktree.rootPaneId };
+	const createTab = async (): Promise<string> => {
+		const tabArgs = ["tab", "create", "--workspace", worktree.workspaceId, "--cwd", worktree.checkoutPath, "--no-focus"] as const;
+		const createdTab = await herdr.exec(tabArgs, { cwd });
+		if (createdTab.code !== 0 || createdTab.killed) {
+			throw new Error(herdrCommandFailure(tabArgs, createdTab));
+		}
+		({ tabId: target.tabId, rootPaneId: target.paneId } = parseCreatedTab(createdTab, worktree.workspaceId));
+		return target.paneId;
+	};
+	if (await waitForRootPaneAgent(herdr, cwd, worktree.rootPaneId)) await createTab();
+	return { target, onPaneBusy: target.paneId === worktree.rootPaneId ? createTab : undefined };
+}
+
+/**
+ * Start a Pi agent and wrap every failure as an ambiguous launch that names the
+ * retained resources. `retained` is read at failure time so a busy-pane move
+ * reports the final target.
+ */
+export async function launchPiAgent(
+	herdr: Herdr,
+	cwd: string,
+	input: {
+		action: string;
+		name: string;
+		pane: string;
+		args: readonly string[];
+		retained: () => string;
+		onPaneBusy?: () => Promise<string>;
+	},
+): Promise<void> {
+	let pane = input.pane;
+	try {
+		const result = await startPiAgent(herdr, {
+			name: input.name,
+			pane,
+			args: input.args,
+			options: { cwd },
+			onPaneBusy: input.onPaneBusy
+				? async () => (pane = await input.onPaneBusy!())
+				: undefined,
+		});
+		if (result.code === 0 && !result.killed) return;
+		const startArgs = ["agent", "start", input.name, "--kind", "pi", "--pane", pane, "--", ...input.args];
+		throw new Error(herdrCommandFailure(startArgs, result));
+	} catch (error) {
+		throw new Error(
+			`${input.action} launch could not be confirmed after starting agent ${input.name}; retained ${input.retained()}: ${errorMessage(error)}`,
+			{ cause: error },
+		);
+	}
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@henryqw/pi-herdr-tools",
-  "version": "1.3.3",
-  "description": "Clone, name, and finish Pi conversations in Herdr, with mergeable side questions.",
+  "version": "1.4.0",
+  "description": "Clone, hand off, name, and finish Pi conversations in Herdr, with mergeable side questions.",
   "keywords": ["pi-package", "pi", "herdr", "session", "clone", "side-thread", "title"],
   "type": "module",
   "engines": { "node": ">=22.19.0" },
   "license": "MIT",
-  "files": ["LICENSE", "extensions", "internal", "docs", "README.md"],
+  "files": ["LICENSE", "extensions", "internal", "prompts", "docs", "README.md"],
   "scripts": {
     "test": "node --test test/*.test.ts",
     "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts internal/*.ts test/*.test.ts",
@@ -14,7 +14,8 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "^1.1.0",
-    "@earendil-works/pi-coding-agent": "^1.1.0"
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "typebox": "^1.3.15"
   },
   "dependencies": {
     "@henryqw/pi-config-store": "^3.0.0",
@@ -32,5 +33,5 @@
   },
   "bugs": { "url": "https://github.com/HenryQW/pi-harness/issues" },
   "publishConfig": { "access": "public" },
-  "pi": { "extensions": ["./extensions/index.ts"] }
+  "pi": { "extensions": ["./extensions/index.ts"], "prompts": ["./prompts"] }
 }

package/prompts/handoff-worktree.md

@@ -0,0 +1,13 @@
+---
+description: Hand off a separate issue to a new Herdr worktree from main.
+argument-hint: "<issue>"
+---
+
+Hand off this separate issue to a new Herdr worktree: $ARGUMENTS
+
+If the issue is empty, stop and ask the user to run `/handoff-worktree <issue>`. Do not modify the current worktree.
+
+1. Gather only the missing facts from the conversation and the repository. Ask one focused question only if the repository, expected outcome, or a critical constraint is unclear.
+2. Write one self-contained prompt: problem, evidence, expected outcome, constraints, starting files, validation, and requested delivery. Exclude unrelated context, secrets, and stale runtime IDs.
+3. Choose a concise branch, a short label, and a unique agent name.
+4. Call `herdr_handoff` with them. Report its result. Do not wait for the new agent to finish.