@maxiaochao/pi-worktree 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2026-10-09 - v0.3.0
+
+- automatically move Agent conversations into prepared worktrees without external Harness support
+- 修复 `enter_worktree` 只创建目录却不切换的问题；现在 Extension 会在 `agent_settled` 后自动 fork 并切换当前会话，不再依赖外部 Harness 消费协议。
+- 移除 v0.2.0 的 `pi-worktree/switch-request` 常量及 `kind/version/action/sessionFile` 输出字段；自定义 Harness 若曾消费该协议，需要改用 Extension 内置自动切换。
+
+## 2026-10-09 - v0.2.0
+
+- add current-session worktree switching for users, Agents, and SDK Harnesses
+- 新增 `/worktree start` 用户命令，在当前 Pi 界面中把持久会话 fork 并切换到 worktree。
+- 新增 `enter_worktree` Agent Tool 和 `pi-worktree/switch-request` Harness 协议。
+- 新增幂等的 `pi-worktree prepare --json` 机器接口，安全处理创建、挂载、复用、dirty 和 stale 状态。
+
 ## 2026-09-30 - v0.1.0
 
 - 将 pi-worktree CLI、bash completion 和 Pi skill 合并为可独立安装的子包。

package/README.md

@@ -1,6 +1,6 @@
 # @maxiaochao/pi-worktree
 
-`pi-worktree` CLI 与配套 Pi skill。CLI 创建、检查和清理 Git worktree，并在隔离目录中启动 Pi。
+`pi-worktree` CLI、Pi Extension 与配套 skill。它既能启动独立 Pi，也能让用户或 Agent 在当前 Pi 界面中切换 worktree，并保留完整对话。
 
 ![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
 
@@ -14,16 +14,28 @@
 
 ```bash
 pi-worktree start feature -p "implement the feature"
+pi-worktree prepare --json feature
 pi-worktree info feature
 pi-worktree out
 pi-worktree remove feature
 ```
 
-`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。
+`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。`prepare` 复用同一创建逻辑，但只返回目标，不启动嵌套 Pi。
+
+在交互式 Pi 中，用户可以保留当前界面和完整对话：
+
+```text
+/worktree start feature
+/worktree start feature --base main
+```
+
+命令会把当前持久会话 fork 到目标 worktree，再通过 Pi 的公开 session replacement API 切换。临时的 `--no-session` 会话无法使用此入口。
+
+Agent 使用 Extension 注册的 `enter_worktree` tool。它创建或复用目标、终止当前工具轮，并在 `agent_settled` 后自动触发内部 `/worktree` 命令。Extension 随后执行 `SessionManager.forkFrom()` 和 `switchSession()`；目标 cwd 会写入新 session header，当前界面继续显示完整对话，重启后也仍然有效。整个流程由 Extension 完成，不需要外部 Harness 适配。
 
 ## 安装
 
-完整工具包已经包含 CLI 和 skill：
+完整工具包已经包含 CLI、Extension 和 skill：
 
 ```bash
 pi install npm:@maxiaochao/pi-toolkit
@@ -50,6 +62,7 @@ pi update npm:@maxiaochao/pi-worktree # 更新独立子包
 
 ```bash
 pi-worktree start <name> [pi args...]
+pi-worktree prepare [--base <ref>] [--json] <name>
 pi-worktree list
 pi-worktree info <name>
 pi-worktree out
@@ -57,4 +70,6 @@ pi-worktree remove <name>
 pi-worktree prune
 ```
 
+`prepare --json` 是 Extension 和其他宿主使用的幂等机器接口，返回 `created`、`attached`、`reused` 或 `already-active`，以及绝对路径、分支和 dirty 状态。已有 worktree 会复用；已存在但未挂载的同名分支会挂载；stale 注册、非法名称和路径冲突会显式失败。
+
 Agent 用法见 `skills/pi-worktree/SKILL.md`。测试流程、夹具和结果见 [TESTING.md](TESTING.md)。

package/TESTING.md

@@ -2,7 +2,7 @@
 
 ## 流程
 
-1. `npm --prefix packages/worktree test`：在临时 Git 仓库中使用假的 `pi` 命令运行 CLI。
+1. `npm --prefix packages/worktree test`：在临时 Git 仓库中运行 CLI，并验证 Extension 注册、延迟命令桥接和 session 切换生命周期。
 2. `npm pack ./packages/worktree --dry-run`：确认 CLI、completion、skill 和安装脚本进入 tarball。
 3. 手工验收发布包的 `pi-worktree start` 交互流程。
 4. 确认 README 示例、真实临时 Git 仓库输出 `docs/screenshot.png` 和 `docs/demo.gif` 进入 tarball。
@@ -11,6 +11,11 @@
 
 - `--help` 输出命令说明。
 - `start` 从当前分支创建 `.worktrees/<name>` 并记录 base。
+- `prepare --json` 覆盖 created、reused、already-active、dirty 和非法名称安全失败。
+- `/worktree start` 把历史 fork 到 cwd 正确的新 session，再调用 `switchSession`。
+- `enter_worktree` 串行准备目标，在 `agent_settled` 后触发内部命令，并 fork 当前 session 后调用 `switchSession`。
+- Agent 轮被中止时不触发切换；用户取消 session replacement 时删除派生 session。
+- 自定义 session 目录在 fork 后保持不变。
 - 假 Pi 收到正确工作目录和参数。
 - `list` 标记主 checkout 和子 worktree。
 - `info` 报告 clean、branch、base 和 ahead。
@@ -18,4 +23,4 @@
 
 ## 最近验证结果
 
-迁移基线要求全部 shell 断言通过，且 `npm pack --dry-run` 包含 `bin/`、`skills/` 和 `scripts/install.mjs`。
+验收要求全部 Node/shell 断言通过，Extension 能被 Pi 单独加载，且 `npm pack --dry-run` 包含 `bin/`、`extensions/`、`skills/` 和 `scripts/install.mjs`。

package/bin/pi-worktree

@@ -4,6 +4,7 @@
 # Usage:
 #   pi-worktree start <name> [pi args...]  # enter worktree <name> and start pi
 #   pi-worktree start --base <ref> <name> [pi args...]  # branch from <ref> instead of current branch
+#   pi-worktree prepare [--base <ref>] [--json] <name>  # create/reuse without launching pi
 #   pi-worktree -l | --list                # list worktrees (main checkout marked "main checkout")
 #   pi-worktree -i <name>                  # show base commit, ahead/behind, unique commits
 #   pi-worktree -o | --out                 # cd back to the main checkout
@@ -18,7 +19,7 @@ else
   C_BOLD='' C_DIM='' C_RED='' C_GREEN='' C_YELLOW='' C_CYAN='' C_RESET=''
 fi
 
-ok()      { printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+ok()      { [[ "${QUIET:-0}" == 1 ]] || printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
 warn()    { printf '%s⚠️  %s%s\n' "$C_YELLOW" "$C_RESET" "$*"; }
 die()     { printf '%spi-worktree: %s%s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
 
@@ -40,6 +41,12 @@ in_linked_worktree() {
 
 wt_dir() { echo ".worktrees/$1"; }
 
+validate_name() {
+  local name="$1"
+  [[ "$name" != */* ]] || die "worktree name must not contain '/': $name"
+  git check-ref-format --branch "$name" >/dev/null 2>&1 || die "invalid worktree/branch name: $name"
+}
+
 # Best available base ref: current branch > HEAD (worktrees should branch
 # from where you actually are; a stale origin/main must not win)
 pick_base() {
@@ -63,12 +70,14 @@ resolve_base() {
 }
 
 ensure_gitignore() {
+  local root
+  root=$(main_checkout)
   # The trailing slash is load-bearing: `.worktrees/` is a directory-only
   # pattern, and git check-ignore cannot match it against a path that does not
   # exist yet — so `.worktrees` would look unignored on every first run and the
   # rule would be appended again.
-  if ! git check-ignore -q .worktrees/ 2>/dev/null; then
-    printf '.worktrees/\n' >> .gitignore
+  if ! git -C "$root" check-ignore -q .worktrees/ 2>/dev/null; then
+    printf '.worktrees/\n' >> "$root/.gitignore"
     ok "added .worktrees/ to .gitignore"
   fi
 }
@@ -226,55 +235,140 @@ cmd_remove() {
   fi
 }
 
-cd_wt() {
-  local name="$1"; shift
+prepare_wt() {
+  local name="$1"
   require_repo
+  validate_name "$name"
 
-  # Already isolated? Just launch pi here (superpowers Step 0).
+  # A linked checkout cannot safely create another `.worktrees/` tree relative
+  # to itself. Re-entering the active branch is nevertheless idempotent.
   if in_linked_worktree; then
-    ok "already in an isolated worktree ($(pwd)), launching pi here"
-    exec pi "$@"
+    local current_branch
+    current_branch=$(git branch --show-current)
+    [[ "$current_branch" == "$name" ]] \
+      || die "already inside linked worktree '$current_branch'; return to the main checkout first"
+    PREPARE_STATUS="already-active"
+    PREPARE_DIR=$(pwd -P)
+    PREPARE_BRANCH="$current_branch"
+    PREPARE_DIRTY=false
+    if [[ -n "$(git status --porcelain)" ]]; then PREPARE_DIRTY=true; fi
+    return 0
   fi
 
-  local dir; dir="$(wt_dir "$name")"
+  local root worktrees_dir dir
+  root=$(main_checkout)
+  worktrees_dir="$root/.worktrees"
+  dir="$worktrees_dir/$name"
+  [[ ! -L "$worktrees_dir" ]] || die "$worktrees_dir must be a real directory, not a symlink"
+  [[ ! -L "$dir" ]] || die "$dir must not be a symlink"
 
   if [[ -d "$dir" ]]; then
     # Reuse: must be a registered worktree for this repo.
     # Skip the dirty-workspace prompt — the worktree already exists, nothing new to create.
+    local registered_path
+    registered_path=$(git worktree list --porcelain | sed -n 's/^worktree //p' | grep -Fx "$dir" || true)
+    [[ -n "$registered_path" ]] || die "$dir exists but is not a registered git worktree"
     git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    [[ "$(git -C "$dir" rev-parse --path-format=absolute --git-common-dir)" == "$(git rev-parse --path-format=absolute --git-common-dir)" ]] \
+      || die "$dir belongs to a different git repository"
+    [[ "$(git -C "$dir" branch --show-current)" == "$name" ]] \
+      || die "$dir is not checked out on expected branch '$name'"
     ensure_gitignore
     ok "reusing existing worktree $dir"
+    PREPARE_STATUS="reused"
   else
-    # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
-    if ! git diff --quiet || ! git diff --cached --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; then
-      warn "Uncommitted changes stay in THIS directory; they will NOT appear in the worktree:"
-      git status --short | head -20
-      read -rp "Continue? [y/N] " ans
-      [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
-    fi
-
-    # After the check above, so the tool's own .gitignore edit is not reported
-    # as (and does not prompt about) the user's uncommitted work.
+    local target_abs registered_path
+    target_abs="$dir"
+    registered_path=$(git worktree list --porcelain | sed -n 's/^worktree //p' | grep -Fx "$target_abs" || true)
+    [[ -z "$registered_path" ]] \
+      || die "stale worktree registration for $dir; run 'pi-worktree prune' first"
     ensure_gitignore
-    mkdir -p .worktrees
+    mkdir -p "$worktrees_dir"
     # Reuse branch if it exists, else create it
     if git show-ref --verify --quiet "refs/heads/$name"; then
-      git worktree add "$dir" "$name"
+      if [[ "${QUIET:-0}" == 1 ]]; then
+        git worktree add "$dir" "$name" >/dev/null
+      else
+        git worktree add "$dir" "$name"
+      fi
       ok "checked out existing branch '$name'"
+      PREPARE_STATUS="attached"
       # record a best-effort base for -i display
       local mb; mb=$(git merge-base main "$name" 2>/dev/null || true)
       [[ -n "$mb" ]] && git config "branch.$name.base" "$(git rev-parse --short "$mb")" \
         && git config "branch.$name.baseRef" main
     else
       local base; base=$(resolve_base)
-      git worktree add "$dir" -b "$name" "$base"
+      if [[ "${QUIET:-0}" == 1 ]]; then
+        git worktree add "$dir" -b "$name" "$base" >/dev/null
+      else
+        git worktree add "$dir" -b "$name" "$base"
+      fi
       git config "branch.$name.base" "$(git rev-parse --short "$base")"
       git config "branch.$name.baseRef" "$base"
       ok "created branch '$name' from $base @ $(git rev-parse --short "$base")"
+      PREPARE_STATUS="created"
     fi
   fi
 
-  cd "$dir"
+  PREPARE_DIR=$(cd "$dir" && pwd -P)
+  PREPARE_BRANCH=$(git -C "$dir" branch --show-current)
+  PREPARE_DIRTY=false
+  if [[ -n "$(git -C "$dir" status --porcelain)" ]]; then PREPARE_DIRTY=true; fi
+}
+
+print_prepare_json() {
+  PI_WORKTREE_STATUS="$PREPARE_STATUS" \
+  PI_WORKTREE_PATH="$PREPARE_DIR" \
+  PI_WORKTREE_BRANCH="$PREPARE_BRANCH" \
+  PI_WORKTREE_DIRTY="$PREPARE_DIRTY" \
+    node -e 'process.stdout.write(JSON.stringify({status:process.env.PI_WORKTREE_STATUS,path:process.env.PI_WORKTREE_PATH,branch:process.env.PI_WORKTREE_BRANCH,dirty:process.env.PI_WORKTREE_DIRTY==="true"})+"\n")'
+}
+
+cmd_prepare() {
+  BASE_OVERRIDE=""
+  local json=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --base)
+        shift; [[ $# -ge 1 ]] || die "usage: pi-worktree prepare [--base <ref>] [--json] <name>"
+        BASE_OVERRIDE="$1"; shift ;;
+      --json) json=1; QUIET=1; shift ;;
+      --*) die "unknown prepare option: $1" ;;
+      *) break ;;
+    esac
+  done
+  [[ $# -eq 1 ]] || die "usage: pi-worktree prepare [--base <ref>] [--json] <name>"
+  prepare_wt "$1"
+  if [[ "$json" == 1 ]]; then
+    print_prepare_json
+  else
+    ok "$PREPARE_STATUS worktree: $PREPARE_DIR ($PREPARE_BRANCH)"
+  fi
+}
+
+cd_wt() {
+  local name="$1"; shift
+  require_repo
+
+  # Already isolated? Preserve the original start behavior and launch Pi here.
+  if in_linked_worktree; then
+    ok "already in an isolated worktree ($(pwd)), launching pi here"
+    exec pi "$@"
+  fi
+
+  # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
+  local dir; dir="$(main_checkout)/.worktrees/$name"
+  if [[ ! -d "$dir" ]] && { ! git diff --quiet || ! git diff --cached --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; }; then
+    warn "Uncommitted changes stay in THIS directory; they will NOT appear in the worktree:"
+    git status --short | head -20
+    read -rp "Continue? [y/N] " ans
+    [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
+  fi
+
+  prepare_wt "$name"
+
+  cd "$PREPARE_DIR"
   exec pi "$@"
 }
 
@@ -285,6 +379,7 @@ case "${1:-}" in
   -r|--remove|rm|remove) shift; cmd_remove "$@" ;;
   -p|--prune|prune) shift; subcmd_prune ;;
   -h|--help|help) sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//' ;;
+  prepare) shift; cmd_prepare "$@" ;;
   start) shift
     BASE_OVERRIDE=""
     if [[ "${1:-}" == "--base" ]]; then

package/bin/pi-worktree-completion.bash

@@ -4,7 +4,7 @@ _pi_worktree() {
   cur="${COMP_WORDS[COMP_CWORD]}"
   first="${COMP_WORDS[1]}"
 
-  local SUBS="start list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
+  local SUBS="start prepare list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
 
   # existing worktree names (only linked worktrees, i.e. under .worktrees/)
   local wts=""
@@ -23,7 +23,7 @@ _pi_worktree() {
   fi
 
   case "$first" in
-    -i|--info|info|-r|--remove|remove|rm|start)
+    -i|--info|info|-r|--remove|remove|rm|start|prepare)
       # only the second word of info/remove completes worktree names;
       # later words offer nothing (info/remove take no further args)
       if (( COMP_CWORD == 2 )); then

package/extensions/worktree.ts

@@ -0,0 +1,241 @@
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { unlinkSync } from "node:fs";
+import { SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const CLI_PATH = fileURLToPath(new URL("../bin/pi-worktree", import.meta.url));
+const PENDING_SWITCH_ARGUMENT = "__enter_worktree_pending__";
+
+export interface WorktreePrepareResult {
+  status: "created" | "attached" | "reused" | "already-active";
+  path: string;
+  branch: string;
+  dirty: boolean;
+}
+
+export interface EnterWorktreeResult extends WorktreePrepareResult {
+  switch: "scheduled" | "already-active";
+}
+
+const EnterWorktreeResultSchema = Type.Object({
+  switch: Type.Union([Type.Literal("scheduled"), Type.Literal("already-active")]),
+  status: Type.Union([
+    Type.Literal("created"),
+    Type.Literal("attached"),
+    Type.Literal("reused"),
+    Type.Literal("already-active"),
+  ]),
+  path: Type.String(),
+  branch: Type.String(),
+  dirty: Type.Boolean(),
+});
+
+function parseCommandArgs(input: string): { name: string; base?: string } {
+  const tokens = input.trim().split(/\s+/).filter(Boolean);
+  if (tokens[0] !== "start" || tokens.length < 2) {
+    throw new Error("用法：/worktree start <name> [--base <ref>]");
+  }
+
+  const name = tokens[1];
+  let base: string | undefined;
+  for (let index = 2; index < tokens.length; index += 1) {
+    if (tokens[index] !== "--base" || !tokens[index + 1] || base !== undefined) {
+      throw new Error("用法：/worktree start <name> [--base <ref>]");
+    }
+    base = tokens[index + 1];
+    index += 1;
+  }
+  return { name, base };
+}
+
+function parsePrepareOutput(stdout: string): WorktreePrepareResult {
+  const line = stdout.trim().split("\n").filter(Boolean).at(-1);
+  if (!line) throw new Error("pi-worktree prepare 没有返回结果");
+  const result = JSON.parse(line) as Partial<WorktreePrepareResult>;
+  if (
+    !["created", "attached", "reused", "already-active"].includes(String(result.status))
+    || typeof result.path !== "string"
+    || typeof result.branch !== "string"
+    || typeof result.dirty !== "boolean"
+  ) {
+    throw new Error("pi-worktree prepare 返回了无效结果");
+  }
+  return result as WorktreePrepareResult;
+}
+
+async function prepareWorktree(
+  pi: ExtensionAPI,
+  cwd: string,
+  name: string,
+  base?: string,
+  signal?: AbortSignal,
+): Promise<WorktreePrepareResult> {
+  const args = ["prepare", "--json"];
+  if (base) args.push("--base", base);
+  args.push(name);
+  const result = await pi.exec(CLI_PATH, args, { cwd, signal });
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `pi-worktree prepare 失败（退出码 ${result.code}）`);
+  }
+  if (signal?.aborted) throw new Error("worktree 创建已取消");
+  return parsePrepareOutput(result.stdout);
+}
+
+export default function worktreeExtension(pi: ExtensionAPI) {
+  let pendingSwitch: WorktreePrepareResult | undefined;
+  let pendingDispatchScheduled = false;
+  let transitionReserved = false;
+
+  pi.on("agent_settled", event => {
+    if (!pendingSwitch || pendingDispatchScheduled) return;
+    if (event.aborted) {
+      pendingSwitch = undefined;
+      pendingDispatchScheduled = false;
+      transitionReserved = false;
+      return;
+    }
+    pendingDispatchScheduled = true;
+    // AgentSession defers prompts submitted from agent_settled until the event
+    // finishes. Command expansion then supplies a safe command context with
+    // switchSession(), after the tool result is persisted and the run is idle.
+    pi.sendUserMessage(`/worktree ${PENDING_SWITCH_ARGUMENT}`, {
+      expandPromptTemplates: true,
+    });
+  });
+
+  pi.registerCommand("worktree", {
+    description: "创建或复用 worktree，并在当前界面切换过去",
+    handler: async (input, ctx) => {
+      const isPendingSwitch = input.trim() === PENDING_SWITCH_ARGUMENT;
+      let prepared: WorktreePrepareResult;
+      let targetSessionFile: string;
+      try {
+        if (!isPendingSwitch && transitionReserved) {
+          ctx.ui.notify("Agent 正在切换 worktree，请等待切换完成后再执行 /worktree。", "warning");
+          return;
+        }
+        if (!isPendingSwitch) transitionReserved = true;
+        const requestedSwitch = isPendingSwitch ? pendingSwitch : undefined;
+        if (isPendingSwitch && !requestedSwitch) {
+          throw new Error("没有待处理的 Agent worktree 切换");
+        }
+        const sourceSessionFile = ctx.sessionManager.getSessionFile();
+        if (!sourceSessionFile) {
+          throw new Error("当前是临时会话；请启用 session 持久化后再切换 worktree");
+        }
+
+        await ctx.waitForIdle();
+        if (requestedSwitch) {
+          prepared = requestedSwitch;
+        } else {
+          const { name, base } = parseCommandArgs(input);
+          prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+        }
+        if (resolve(ctx.cwd) === resolve(prepared.path)) {
+          if (isPendingSwitch) {
+            pendingSwitch = undefined;
+            pendingDispatchScheduled = false;
+          }
+          transitionReserved = false;
+          ctx.ui.notify(`已经位于 worktree：${prepared.path}`, "info");
+          return;
+        }
+
+        const sessionDir = ctx.sessionManager.usesDefaultSessionDir()
+          ? undefined
+          : ctx.sessionManager.getSessionDir();
+        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path, sessionDir);
+        targetSessionFile = target.getSessionFile() ?? "";
+        if (!targetSessionFile) throw new Error("无法为 worktree 创建持久会话");
+      } catch (error) {
+        if (isPendingSwitch) pendingSwitch = undefined;
+        pendingDispatchScheduled = false;
+        transitionReserved = false;
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+        return;
+      }
+
+      // Do not catch replacement errors here: switchSession may already have
+      // invalidated this command context, so Pi must report such failures.
+      let switched: { cancelled: boolean };
+      try {
+        switched = await ctx.switchSession(targetSessionFile, {
+          withSession: async (next) => {
+            const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
+            next.ui.notify(`已切换到 ${prepared.branch}：${prepared.path}${dirtyNote}`, "info");
+          },
+        });
+      } catch (error) {
+        pendingSwitch = undefined;
+        pendingDispatchScheduled = false;
+        transitionReserved = false;
+        throw error;
+      }
+      pendingSwitch = undefined;
+      pendingDispatchScheduled = false;
+      transitionReserved = false;
+      if (switched.cancelled) {
+        try {
+          unlinkSync(targetSessionFile);
+        } catch (error) {
+          ctx.ui.notify(`worktree 会话切换已取消，但无法清理派生会话：${error instanceof Error ? error.message : String(error)}`, "warning");
+          return;
+        }
+        ctx.ui.notify("worktree 会话切换已取消", "warning");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "enter_worktree",
+    label: "Enter Worktree",
+    exposure: "model-only",
+    executionMode: "sequential",
+    description:
+      "Create or reuse an isolated git worktree, then automatically move this current conversation into it after the current Agent run settles. Call this tool alone and do not call repository tools afterward.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Single-segment worktree and branch name" }),
+      base: Type.Optional(Type.String({ description: "Optional git ref used only when creating a new branch" })),
+    }),
+    outputSchema: EnterWorktreeResultSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!ctx.sessionManager.getSessionFile()) {
+        throw new Error("当前是临时会话，无法续接到 worktree");
+      }
+      if (transitionReserved) {
+        const target = pendingSwitch ? `：${pendingSwitch.path}` : "";
+        throw new Error(`已有 worktree 切换正在处理${target}`);
+      }
+      transitionReserved = true;
+
+      let prepared: WorktreePrepareResult;
+      try {
+        prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base, signal);
+        if (signal.aborted) throw new Error("worktree 创建已取消");
+      } catch (error) {
+        transitionReserved = false;
+        throw error;
+      }
+      const alreadyActive = resolve(ctx.cwd) === resolve(prepared.path);
+      const result: EnterWorktreeResult = {
+        switch: alreadyActive ? "already-active" : "scheduled",
+        ...prepared,
+      };
+      if (alreadyActive) transitionReserved = false;
+      else pendingSwitch = prepared;
+      const dirtyNote = prepared.dirty ? " 目标 worktree 已有未提交改动。" : "";
+      return {
+        content: [{
+          type: "text",
+          text: alreadyActive
+            ? `已经位于 worktree：${prepared.path}.${dirtyNote}`
+            : `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 当前 Agent run 结束后会自动切换到该目录；不要继续调用仓库工具。`,
+        }],
+        details: result,
+        structuredContent: result,
+        terminate: true,
+      };
+    },
+  });
+}

package/package.json

@@ -1,20 +1,49 @@
 {
   "name": "@maxiaochao/pi-worktree",
-  "version": "0.1.0",
-  "description": "Git worktree CLI and Pi skill for isolated coding tasks.",
+  "version": "0.3.0",
+  "description": "Git worktree CLI, Pi extension, and skill for isolated coding tasks.",
   "type": "module",
-  "keywords": ["pi-package", "pi-skill", "git", "worktree"],
-  "files": ["bin", "skills", "scripts", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "git",
+    "worktree"
+  ],
+  "files": [
+    "bin",
+    "extensions",
+    "skills",
+    "scripts",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
     "directory": "packages/worktree"
   },
-  "bin": { "pi-worktree": "bin/pi-worktree" },
-  "pi": { "skills": ["./skills"] },
+  "bin": {
+    "pi-worktree": "bin/pi-worktree"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/worktree.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
   "scripts": {
-    "test": "node --test tests/install.test.mjs && bash tests/run-tests.sh",
+    "test": "node --test tests/install.test.mjs && node --experimental-strip-types --test tests/extension.test.mjs && bash tests/run-tests.sh",
     "postinstall": "node scripts/install.mjs"
   },
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/skills/pi-worktree/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-worktree
-description: Create, inspect, and clean up git worktrees with the pi-worktree CLI (start/list/info/remove/prune), which also launches Pi inside the worktree. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
+description: Create, enter, inspect, and clean up git worktrees through the enter_worktree tool, /worktree command, or pi-worktree CLI. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
 ---
 
 # pi-worktree
 
-`pi-worktree` wraps git worktree creation and Pi launch into one command. Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the branch you are on now (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can always report where the branch came from.
+Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the current branch (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can report where the branch came from.
 
 Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with bash completion for subcommands and existing worktree names.
 
@@ -13,6 +13,9 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 
 | Command | Effect |
 |---|---|
+| `enter_worktree({ name, base? })` | Agent entrypoint: create/reuse a worktree and automatically move this conversation there after the run settles. Call it alone and stop after it returns. |
+| `/worktree start <name> [--base <ref>]` | User entrypoint: fork the current persistent session into the worktree and switch the current Pi UI. |
+| `pi-worktree prepare [--base <ref>] [--json] <name>` | Create/reuse without launching Pi; `--json` is the machine interface. |
 | `pi-worktree start <name> [pi args...]` | Create or reuse `.worktrees/<name>`, then launch Pi inside it. Already inside a linked worktree, it just launches Pi there. |
 | `pi-worktree start --base <ref> <name> [pi args...]` | Same, but branch from `<ref>` instead of the current branch. |
 | `pi-worktree list` | All worktrees; the main checkout is marked `(main checkout)`, stale registrations are flagged. |
@@ -24,13 +27,15 @@ Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with ba
 ## Isolating a task
 
 1. **Survey** — `pi-worktree list`, plus `pi-worktree info <name>` when the name you want is already taken. Reuse is free; a removed worktree is gone for good, because `remove` deletes its branch.
-2. **Start** — `pi-worktree start <name>` (with `--base <ref>` when the work must not start from the current branch). Done when `list` shows the new worktree on its own branch.
+2. **Enter** — as an Agent, call `enter_worktree` once and stop; the Extension switches automatically after settlement. A user can instead run `/worktree start <name>`. Use the CLI `start` only when a separate Pi process is wanted.
 3. **Work** — inside the worktree: commit there, and check `pi-worktree info <name>` before claiming progress. `ahead: N commits since base` is the evidence.
 4. **Land** — `pi-worktree out`, then `git merge <name>` in the main checkout. Done when the worktree's unique commits are in the target branch.
 5. **Clean up** — `pi-worktree remove <name>`. A merged branch goes without prompting; anything unmerged asks once.
 
-## Driving it from an agent
+## Entry-point rules
 
-- `start` **execs `pi`** in the worktree, and `out` execs a shell. With no trailing Pi args both want an interactive terminal, so either run `start <name> -p "<task>"` for a headless nested run, or hand the bare `start <name>` to the user to run themselves.
+- Prefer `enter_worktree` when it is available. After the tool returns, do not read or modify repository files; the Extension waits for `agent_settled`, then forks the session into the target cwd and switches automatically.
+- `/worktree` is user-facing and cannot be invoked by the model. It requires a persisted session because it forks history into a session whose header owns the worktree cwd.
+- `pi-worktree start` **execs a new `pi`** in the worktree, and `out` execs a shell. Use this only for an intentionally separate process/session.
+- `prepare` is idempotent. It reports whether the target was created, attached, reused, or already active, and reports dirty reuse rather than discarding anything.
 - `remove` asks before discarding dirty files or unmerged commits, and a non-interactive stdin (EOF) aborts safely. Answer explicitly when the removal is intended: `printf 'y\ny\n' | pi-worktree remove <name>`.
-- Your own working directory cannot change. "Isolate this in a worktree" therefore means launching a nested headless Pi in the worktree, or telling the user to run `pi-worktree start <name>`.