@maxiaochao/pi-worktree 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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，也能让用户在当前界面切换 worktree，或让 Agent 向 SDK Harness 发出结构化切换请求。
 
 ![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
 
@@ -14,16 +14,28 @@
 
 ```bash
 pi-worktree start feature -p "implement the feature"
+pi-worktree prepare feature --json
 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。它创建或复用目标后返回 `pi-worktree/switch-request` 结构化结果，并终止当前工具轮；兼容 Harness 应在 `agent_settled` 后读取 `sessionFile` 和 `path`，执行 `SessionManager.forkFrom(sessionFile, path)`，再把返回的新 session 文件交给 `runtime.switchSession()`，最后重新绑定 `runtime.session`。这样目标 cwd 会写入新 session header，重启后仍然有效。普通 Pi 没有宿主切换钩子时，Tool 只会生成请求；用户仍可使用 `/worktree start` 完成切换。
 
 ## 安装
 
-完整工具包已经包含 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,9 @@
 
 - `--help` 输出命令说明。
 - `start` 从当前分支创建 `.worktrees/<name>` 并记录 base。
+- `prepare --json` 覆盖 created、reused、already-active、dirty 和非法名称安全失败。
+- `/worktree start` 把历史 fork 到 cwd 正确的新 session，再调用 `switchSession`。
+- `enter_worktree` 返回带 `pi-worktree/switch-request`、源 session、目标路径和 dirty 状态的 structured content，并请求终止当前工具轮。
 - 假 Pi 收到正确工作目录和参数。
 - `list` 标记主 checkout 和子 worktree。
 - `info` 报告 clean、branch、base 和 ahead。
@@ -18,4 +21,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,173 @@
+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));
+
+export const WORKTREE_SWITCH_REQUEST = "pi-worktree/switch-request";
+
+export interface WorktreePrepareResult {
+  status: "created" | "attached" | "reused" | "already-active";
+  path: string;
+  branch: string;
+  dirty: boolean;
+}
+
+export interface WorktreeSwitchRequest extends WorktreePrepareResult {
+  kind: typeof WORKTREE_SWITCH_REQUEST;
+  version: 1;
+  action: "fork-and-switch";
+  sessionFile: string;
+}
+
+const SwitchRequestSchema = Type.Object({
+  kind: Type.Literal(WORKTREE_SWITCH_REQUEST),
+  version: Type.Literal(1),
+  action: Type.Literal("fork-and-switch"),
+  sessionFile: Type.String(),
+  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,
+): Promise<WorktreePrepareResult> {
+  const args = ["prepare", "--json"];
+  if (base) args.push("--base", base);
+  args.push(name);
+  const result = await pi.exec(CLI_PATH, args, { cwd });
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `pi-worktree prepare 失败（退出码 ${result.code}）`);
+  }
+  return parsePrepareOutput(result.stdout);
+}
+
+export default function worktreeExtension(pi: ExtensionAPI) {
+  pi.registerCommand("worktree", {
+    description: "创建或复用 worktree，并在当前界面切换过去",
+    handler: async (input, ctx) => {
+      let prepared: WorktreePrepareResult;
+      let targetSessionFile: string;
+      try {
+        const { name, base } = parseCommandArgs(input);
+        const sourceSessionFile = ctx.sessionManager.getSessionFile();
+        if (!sourceSessionFile) {
+          throw new Error("当前是临时会话；请启用 session 持久化后再切换 worktree");
+        }
+
+        await ctx.waitForIdle();
+        prepared = await prepareWorktree(pi, ctx.cwd, name, base);
+        if (resolve(ctx.cwd) === resolve(prepared.path)) {
+          ctx.ui.notify(`已经位于 worktree：${prepared.path}`, "info");
+          return;
+        }
+
+        const target = SessionManager.forkFrom(sourceSessionFile, prepared.path);
+        targetSessionFile = target.getSessionFile() ?? "";
+        if (!targetSessionFile) throw new Error("无法为 worktree 创建持久会话");
+      } catch (error) {
+        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.
+      const switched = await ctx.switchSession(targetSessionFile, {
+        withSession: async (next) => {
+          const dirtyNote = prepared.dirty ? "（已有未提交改动）" : "";
+          next.ui.notify(`已切换到 ${prepared.branch}：${prepared.path}${dirtyNote}`, "success");
+        },
+      });
+      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",
+    description:
+      "Create or reuse an isolated git worktree and request that the host Harness move this current conversation into it. Call this tool alone, then stop; the Harness performs the session switch after the tool completes.",
+    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: SwitchRequestSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const sourceSessionFile = ctx.sessionManager.getSessionFile();
+      if (!sourceSessionFile) throw new Error("当前是临时会话，Harness 无法续接到 worktree");
+
+      const prepared = await prepareWorktree(pi, ctx.cwd, params.name, params.base);
+      const request: WorktreeSwitchRequest = {
+        kind: WORKTREE_SWITCH_REQUEST,
+        version: 1,
+        action: "fork-and-switch",
+        sessionFile: sourceSessionFile,
+        ...prepared,
+      };
+      const dirtyNote = prepared.dirty ? " 目标 worktree 已有未提交改动。" : "";
+      return {
+        content: [{
+          type: "text",
+          text: `Worktree ${prepared.status}: ${prepared.path}.${dirtyNote} 已请求 Harness 将当前会话切换到该目录；不要继续调用仓库工具。`,
+        }],
+        details: request,
+        structuredContent: request,
+        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.2.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 ask a compatible Harness to move this conversation there. 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 so the Harness can switch 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. Its `fork-and-switch` request requires Harness support: after `agent_settled`, the host forks the source session into the target cwd and switches to that persisted session. After the tool returns, do not read or modify repository files until the host has switched cwd.
+- `/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>`.