@senad-d/branchme 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,7 +1,10 @@
 # Changelog
 
-## 0.2.0 - Unreleased
+## 0.2.2 - Unreleased
 
+- Allowed `branch_status` ancestry endpoints to be remote-tracking refs such as `origin/main` in addition to exact local branches; local branches take precedence and remote-tracking refs stay read-only comparison targets.
+- Added optional `remote`/`branch` parameters to `fetch_branch` for a targeted fetch of one exact remote branch into its remote-tracking ref (default remote `origin`; `remote` requires `branch`) without touching local branches, the working tree, or the current branch's upstream configuration; the no-argument behavior is unchanged.
+- Added an optional read-only `baseRef` parameter to `create_worktree` for `branchMode: "new"`, starting the new branch from an exact local branch, remote-tracking ref, or full commit regardless of the current checkout's branch, dirt, or staleness; the default from-`HEAD` behavior is unchanged.
 - Implemented the `branchme` informational slash command with help aliases.
 - Added thirteen strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `integrate_branch`, `retire_branch`, `create_branch`, `push_branch`, `pull_request`, `list_worktrees`, `create_worktree`, and `remove_worktree`; merge-continuation tools are intentionally absent.
 - Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, configured-upstream fetch, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, verified local branch integration, current-branch push/publish, and bounded NUL-delimited worktree discovery.
@@ -13,6 +16,7 @@
 - Added canonical absolute-path and lossless-identity validation before worktree mutations, including existing-destination, nested-worktree, common-Git-directory, repository-membership, redaction, escaping, and truncation boundaries. BranchMe does not copy ignored/untracked files or start/switch Pi sessions.
 - Added GitHub repository resolution, environment-token and local `.env` token fallback handling, REST pull request creation, response validation, and token redaction.
 - Added opt-in `BRANCHME_PR_AUTOFILL` support for omitted PR fields, including current/default branch inference, bounded, Markdown-safe, and token-redacted title/body generation from commit subjects, and a non-draft default.
+- Allowed autonomous and delegated agents to invoke `pull_request` from user, system, or developer prompts, `AGENTS.md`, skills, automation, and subagent workflows without separate end-user confirmation.
 - Added bounded automatic Git context before each agent run with branch/upstream state, working-tree counts and unstaged paths, authenticated related-open-PR lookup, and recent commits.
 - Expanded `branch_status` into a shared, explicit, read-only context refresh for state that may change during a run.
 - Added unit tests with mocked `pi.exec` and `fetch` for Git context collection and prompt safety, git, branch-integration, branch-retirement, and worktree helpers, GitHub helpers, command behavior, strict tool schemas, prompt metadata, and extension registration, plus isolated temporary-repository worktree, merge, and leased local-ref retirement lifecycle coverage.

package/README.md

@@ -101,7 +101,7 @@ For isolated work, a specialized Git subagent can use the explicit worktree work
 
 BranchMe does not change the active Pi process's cwd, start Pi or other processes, create sessions, copy `.env` or other ignored/untracked files, or automatically retire a branch when removing its worktree. For credentials needed by agents in linked worktrees, prefer process-level environment variables rather than copying repository-root secrets.
 
-To refresh the current branch's configured remote-tracking ref without changing the local branch or working tree, use `fetch_branch`. To reconcile the clean current branch by rewriting its local commits, run `fetch_branch`, wait for it to complete, and then run `rebase_branch`. Both tools require a configured upstream; `rebase_branch` automatically attempts `git rebase --abort` if rebasing fails.
+To refresh the current branch's configured remote-tracking ref without changing the local branch or working tree, use `fetch_branch` with no arguments. To refresh another remote-tracking ref — for example `origin/main` after a pull request merged on GitHub — call `fetch_branch` with `branch` (and optional `remote`, default `origin`); the targeted fetch never touches local branches, the working tree, or the current branch's upstream configuration. To reconcile the clean current branch by rewriting its local commits, run `fetch_branch`, wait for it to complete, and then run `rebase_branch`. The no-argument `fetch_branch` and `rebase_branch` require a configured upstream; `rebase_branch` automatically attempts `git rebase --abort` if rebasing fails.
 
 BranchMe is tool-based. The slash command is informational only and never changes or updates branches, creates or removes worktrees, changes cwd, starts processes/sessions, fetches, rebases, pushes, commits, stages, edits files, or opens pull requests.
 
@@ -201,7 +201,7 @@ With autofill enabled, omitted fields are resolved as follows:
 - `body`: a bounded Markdown summary of commit subjects in `baseBranch..headBranch`.
 - `draft`: `false`.
 
-Explicit tool arguments always take precedence. Autofill does not create a PR by itself: the user must still ask the agent to create one.
+Explicit tool arguments always take precedence. Autofill does not invoke `pull_request` by itself. Agents may invoke `pull_request` without separate end-user confirmation when PR creation is appropriate for the active workflow, including directions from user prompts, system or developer instructions, `AGENTS.md`, skills, automation, or delegated/subagent prompts.
 
 If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
@@ -224,13 +224,13 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 
 | Tool | Schema | Behavior |
 | --- | --- | --- |
-| `branch_status` | `{ "ancestry"?: { "sourceBranch": string, "targetBranch": string } }` | Explicitly refreshes the same bounded context used at agent start. An optional strict ancestry query captures both exact local branch HEADs and reports whether the source commit is an ancestor of the target commit. It is read-only; automatic Git context does not run ancestry queries. |
+| `branch_status` | `{ "ancestry"?: { "sourceBranch": string, "targetBranch": string } }` | Explicitly refreshes the same bounded context used at agent start. An optional strict ancestry query captures both exact HEADs and reports whether the source commit is an ancestor of the target commit; each endpoint may be an exact local branch or a remote-tracking ref such as `origin/main` (a local branch of the same name takes precedence). It is read-only and never checks out or resets remote-tracking refs; automatic Git context does not run ancestry queries. |
 | `list_worktrees` | `{}` | Runs a bounded, read-only inventory of the current repository's main and linked worktrees, including path, branch/detached state, `HEAD`, current/main, locked, prunable, and omitted-entry details. Automatic Git context does not include this inventory. |
-| `create_worktree` | `{ "worktreePath": string, "branchName": string, "branchMode": "new" \| "existing" }` | Creates and verifies a linked worktree at an explicitly approved absolute path. `new` creates a local branch from current `HEAD`; `existing` requires an existing local branch not checked out elsewhere. It returns a ready handoff with the exact canonical absolute cwd and local branch identity. |
+| `create_worktree` | `{ "worktreePath": string, "branchName": string, "branchMode": "new" \| "existing", "baseRef"?: string }` | Creates and verifies a linked worktree at an explicitly approved absolute path. `new` creates a local branch from current `HEAD`, or from the optional read-only `baseRef` (an exact local branch, remote-tracking ref such as `origin/main`, or full commit) regardless of the current checkout's branch, dirt, or staleness; `existing` requires an existing local branch not checked out elsewhere and rejects `baseRef`. It returns a ready handoff with the exact canonical absolute cwd and local branch identity. |
 | `remove_worktree` | `{ "worktreePath": string }` | Force-free removal of an explicitly selected, verified clean linked worktree. It rejects the main/current, detached, locked, prunable/missing, dirty, ignored-file-containing, or foreign worktree and verifies that the local branch remains at the same commit. |
 | `retire_branch` | `{ "branchName": string, "expectedHead": string, "targetBranch": string, "force": boolean }` | Deletes only the exact unoccupied local branch ref when its direct ref matches the supplied full commit ID and its relationship to the exact local target has been verified. Unmerged retirement requires explicit `force: true`; remote and remote-tracking refs are untouched. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
-| `fetch_branch` | `{}` | Requires a current branch with a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <upstream-remote> <upstream-branch-ref>:<remote-tracking-ref>`; only that tracking ref is refreshed without changing local branches or working-tree files. |
+| `fetch_branch` | `{ "remote"?: string, "branch"?: string }` | With no arguments it requires a current branch with a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <upstream-remote> <upstream-branch-ref>:<remote-tracking-ref>`. With `branch` (and optional `remote`, default `origin`; `remote` requires `branch`) it fetches that exact remote branch into `refs/remotes/<remote>/<branch>` instead. Either way only that tracking ref is refreshed without changing local branches, working-tree files, or upstream configuration. |
 | `pull_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git pull --ff-only --no-rebase --no-autostash <upstream-remote> <upstream-branch-ref>`; divergence fails without rebasing or creating a merge commit. |
 | `rebase_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure. |
 | `integrate_branch` | `{ "sourceBranch": string, "targetBranch": string }` | Integrates one exact existing local source branch into one distinct existing local target branch. The clean active control worktree must already have the target checked out. It returns `already_integrated`, `fast_forward`, `merge_commit`, or a `conflict` only after automatic abort and verified restoration. It never fetches or pushes. |
@@ -238,7 +238,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
 | `pull_request` | `{ "headBranch"?: string, "baseBranch"?: string, "title"?: string, "body"?: string, "draft"?: boolean }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then creates a pull request in the resolved current repository. Omitted fields require `BRANCHME_PR_AUTOFILL=true`; branch refs must be distinct, exist locally, and cannot use `owner:branch`. |
 
-All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `fetch_branch`, `pull_branch`, and `rebase_branch` have strict empty schemas and never accept a branch, remote, refspec, force, autostash, or arbitrary rebase target. `integrate_branch` requires exactly `sourceBranch` and `targetBranch`; it accepts no repository, path, remote, strategy, message, squash, signing, commit, continuation, abort, force, fetch, push, deletion, or worktree controls. `create_worktree` requires exactly `worktreePath`, `branchName`, and `branchMode`; `remove_worktree` requires exactly `worktreePath`. No worktree tool accepts force, move, prune, repair, lock, unlock, detached, orphan, remote, refspec, or arbitrary start-point controls. `retire_branch` requires exactly `branchName`, a full 40- or 64-hex-character `expectedHead`, a distinct local `targetBranch`, and the boolean `force` decision; it accepts no repository, path, remote, refspec, pattern, branch list, prune, remote-delete, worktree-removal, or inferred-target control. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`. `continue_merge` and `abort_merge` are not available.
+All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `fetch_branch` accepts only the optional `remote` and `branch` pair for a targeted remote-tracking refresh (`remote` requires `branch`) and never accepts refspec, tags, prune, or force controls. `pull_branch` and `rebase_branch` have strict empty schemas and never accept a branch, remote, refspec, force, autostash, or arbitrary rebase target. `integrate_branch` requires exactly `sourceBranch` and `targetBranch`; it accepts no repository, path, remote, strategy, message, squash, signing, commit, continuation, abort, force, fetch, push, deletion, or worktree controls. `create_worktree` requires exactly `worktreePath`, `branchName`, and `branchMode`, plus an optional read-only `baseRef` start point for `branchMode: "new"`; `remove_worktree` requires exactly `worktreePath`. No worktree tool accepts force, move, prune, repair, lock, unlock, detached, orphan, remote, or refspec controls. `retire_branch` requires exactly `branchName`, a full 40- or 64-hex-character `expectedHead`, a distinct local `targetBranch`, and the boolean `force` decision; it accepts no repository, path, remote, refspec, pattern, branch list, prune, remote-delete, worktree-removal, or inferred-target control. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`. `continue_merge` and `abort_merge` are not available.
 
 ---
 
@@ -257,7 +257,7 @@ Before each agent run, BranchMe appends an **Automatic Git Context** snapshot to
 
 Collection defaults are a 5-second timeout per local Git command, a 4-second related-PR lookup timeout, at most 512 characters per metadata value, and at most 4,000 characters for the rendered snapshot. GitHub response bodies are limited to 64 KiB. The formatter can further shorten values or omit entries to stay within the total limit.
 
-The snapshot is fresh at agent start but is not live. A fetch, branch switch, pull, rebase, integration, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state. Its optional `ancestry` object requires exact `sourceBranch` and `targetBranch` fields together, captures both local branch commit IDs, and reports `isAncestor`. This targeted proof is explicit only: automatic Git context remains unchanged. Run it after `integrate_branch` completes, never in the same parallel tool batch.
+The snapshot is fresh at agent start but is not live. A fetch, branch switch, pull, rebase, integration, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state. Its optional `ancestry` object requires exact `sourceBranch` and `targetBranch` fields together, captures both commit IDs, and reports `isAncestor`. Each endpoint may be an exact local branch or a remote-tracking ref such as `origin/main` (local branches take precedence), so a fetched `origin/main` can serve as a read-only containment proof after a pull request merges. This targeted proof is explicit only: automatic Git context remains unchanged. Run it after `integrate_branch` or `fetch_branch` completes, never in the same parallel tool batch.
 
 Related-PR metadata does not come from Git alone. When repository, branch, and credentials resolve, automatic collection and explicit `branch_status` may make an authenticated `GET /repos/{owner}/{repo}/pulls?state=open&head={owner}:{branch}&per_page=1` request. Without a token there is no unauthenticated fallback or GitHub request; the PR field is reported as unavailable while local Git context remains usable.
 
@@ -310,7 +310,7 @@ with `branch_status` only after `integrate_branch` has returned. Do not batch th
 
 `create_worktree` requires a non-blank absolute path with no control characters. Its immediate parent must already be a directory. BranchMe resolves that parent to build a canonical destination, rejects any existing file, directory, or symlink there, and rejects destinations inside a registered worktree or the repository's common Git directory. Before mutation, the canonical path and local branch must be returnable without redaction, escaping, Unicode alteration, or truncation: canonical paths are limited to 4,096 characters and branch identities to 512 characters, and credential-like token text is rejected. A dirty source worktree is allowed because creation does not switch or overwrite it.
 
-For `branchMode: "new"`, BranchMe creates the requested local branch from the current `HEAD` only. For `branchMode: "existing"`, it uses only an existing local branch that is not checked out in another worktree; it never infers a local branch from a remote. After Git succeeds, BranchMe re-lists worktrees and verifies the canonical path, local branch, `HEAD`, and clean checkout. A representative structured result subset is:
+For `branchMode: "new"`, BranchMe creates the requested local branch from the current `HEAD`, or — when the optional `baseRef` is supplied — from that exact existing local branch, remote-tracking ref (for example `origin/main`), or full commit. `baseRef` is resolved to a commit before mutation and is only read: it is never checked out, reset, or given upstream configuration, and the current checkout's branch, dirt, or staleness never blocks it. For `branchMode: "existing"`, it uses only an existing local branch that is not checked out in another worktree and rejects `baseRef`; it never infers a local branch from a remote. After Git succeeds, BranchMe re-lists worktrees and verifies the canonical path, local branch, `HEAD`, and clean checkout. A representative structured result subset is:
 
 ```json
 {
@@ -378,13 +378,13 @@ BranchMe operates only on the repository where pi is running:
 - Automatic collection and `branch_status` run bounded, read-only Git commands from the verified git root.
 - Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root.
 - `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
-- `fetch_branch` requires a configured upstream, uses an explicit source-to-remote-tracking refspec with tags and submodule recursion disabled, and does not change local branches or working-tree files.
+- `fetch_branch` uses an explicit source-to-remote-tracking refspec with tags and submodule recursion disabled and does not change local branches or working-tree files. Without arguments it requires a configured upstream; with an explicit `branch` (and optional configured `remote`, default `origin`) it refreshes only `refs/remotes/<remote>/<branch>` and never touches upstream configuration.
 - `pull_branch` requires a clean worktree and configured upstream, updates only the current branch with `git pull --ff-only --no-rebase --no-autostash`, and has no branch, remote, force, or rebase input.
 - `rebase_branch` requires a clean worktree and configured upstream, rewrites only the current branch onto the locally available upstream with autostash and multi-ref updates disabled, and automatically attempts to abort on failure.
 - `integrate_branch` merges one captured local source ref into the already-current clean local target with the fixed policy documented above. It verifies repository identity, refs, ancestry, clean state, and cleanup without fetching or pushing.
 - `create_branch` creates from the current `HEAD` only and has no `baseRef` input.
 - `list_worktrees` is an explicit, read-only repository inventory; it is intentionally absent from automatic active-worktree context.
-- `create_worktree` may create a linked checkout outside the active checkout only after canonical path and current-repository boundary checks; dependent worktree calls must wait for its verified handoff.
+- `create_worktree` may create a linked checkout outside the active checkout only after canonical path and current-repository boundary checks; its optional `baseRef` is resolved read-only to a commit and never checked out or reset, and dependent worktree calls must wait for its verified handoff.
 - `remove_worktree` passes Git only a freshly verified canonical linked-worktree path, never uses force, and retains the branch.
 - `retire_branch` deletes only one exact unoccupied direct local ref with the supplied expected-`HEAD` lease after captured target ancestry verification; it leaves remote refs, remote-tracking refs, worktrees, and branch configuration untouched.
 - `push_branch` pushes only the current branch, uses no bare upstream `git push`, and has no `branchName` input.

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -181,3 +181,4 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.2.0` p
 - `push_branch` uses `origin` only when the current branch has no configured upstream.
 - `pull_request` infers owner/repository from the current checkout or matching `GITHUB_REPOSITORY`, never accepts owner/repository tool inputs, and requires local branch refs with the head matching GitHub.
 - Pull request fields remain explicit unless `BRANCHME_PR_AUTOFILL=true`; explicit values always take precedence.
+- `pull_request` is available to autonomous and delegated workflows without separate end-user confirmation. PR creation may be directed by user, system, or developer prompts, `AGENTS.md`, skills, automation, or delegated/subagent prompts.

package/docs/STRUCTURE.md

@@ -54,9 +54,9 @@ src/
 - Automatic context and `branch_status` share bounded, read-only collection. They run no mutations and capture repository metadata only—never diffs or file contents.
 - Repository-controlled paths, branch names, commit subjects, and PR fields are escaped, quoted, redacted, bounded, and labeled untrusted before system-prompt insertion.
 - Related-PR lookup may issue an authenticated `GET /pulls` before every agent run and on explicit refresh. It has a 4-second timeout and 64 KiB response limit, and makes no unauthenticated fallback request.
-- The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh. Its optional targeted ancestry proof must run after `integrate_branch`, not in the same parallel tool batch.
+- The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh. Its optional targeted ancestry proof accepts exact local branches or remote-tracking refs such as `origin/main` as read-only endpoints and must run after `integrate_branch` or `fetch_branch`, not in the same parallel tool batch.
 - `change_branch` mutates local HEAD and working-tree files only through `git switch <branchName>` for existing local branches after a clean-worktree preflight.
-- `fetch_branch` requires a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <remote> <remote-ref>:<remote-tracking-ref>`; its explicit refspec updates only that tracking ref without changing local branches or working-tree files.
+- `fetch_branch` runs `git fetch --no-tags --no-recurse-submodules <remote> <remote-ref>:<remote-tracking-ref>`; its explicit refspec updates only that tracking ref without changing local branches or working-tree files. Without arguments it requires a configured upstream; with an explicit `branch` (and optional configured `remote`, default `origin`) it refreshes only `refs/remotes/<remote>/<branch>` and never touches upstream configuration.
 - `pull_branch` requires a clean worktree and configured upstream, then updates only the current branch with an explicit `git pull --ff-only --no-rebase --no-autostash <remote> <remote-ref>` command; divergence fails without a rebase or merge commit.
 - `rebase_branch` requires a clean worktree and configured upstream, then rebases only the current branch with `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure.
 - `integrate_branch` requires distinct existing local refs and a clean control worktree already on the target. It rejects non-empty target-branch `mergeOptions`, runs `git -c rerere.enabled=false merge --ff --no-edit --no-autostash --no-rerere-autoupdate --no-overwrite-ignore refs/heads/<sourceBranch>`, verifies before/after refs and ancestry, and classifies already-integrated, fast-forward, exact two-parent merge-commit, or conflict.
@@ -67,7 +67,7 @@ src/
 - Git hooks, custom merge drivers, clean/smudge filters, signing policy, and `reference-transaction` hooks stay active where Git invokes them and may execute commands or network operations outside BranchMe's direct argv boundary.
 - `create_branch` mutates local branch/HEAD only with `git switch -c`.
 - `list_worktrees` reads a bounded `git worktree list --porcelain -z` inventory and remains explicit rather than expanding automatic active-worktree context.
-- `create_worktree` requires an explicitly approved absolute destination, canonicalizes its existing parent, rejects existing or nested/common-Git-directory destinations, and creates only from current `HEAD` or an unoccupied existing local branch. It verifies canonical path, branch, `HEAD`, and cleanliness before returning a ready handoff.
+- `create_worktree` requires an explicitly approved absolute destination, canonicalizes its existing parent, rejects existing or nested/common-Git-directory destinations, and creates from current `HEAD`, from an explicit read-only `baseRef` (exact local branch, remote-tracking ref, or full commit resolved to a commit before mutation and never checked out or reset), or from an unoccupied existing local branch. It verifies canonical path, branch, `HEAD`, and cleanliness before returning a ready handoff.
 - `remove_worktree` resolves an exact fresh current-repository inventory match, rejects main/current/dirty/ignored-entry-containing/detached/locked/prunable/missing/bare entries, runs a bounded removal-specific ignored-entry scan, performs force-free removal with the verified path, and confirms that the local branch remains at the same commit.
 - `push_branch` mutates remote refs only for the current branch and uses an explicit upstream remote/refspec instead of bare `git push` when an upstream exists.
 - `pull_request` requires resolved `headBranch` and `baseBranch` values to be distinct and exist locally, requires `headBranch` to match the GitHub-visible branch commit, queues behind already-started same-repository git mutation windows, makes GitHub REST API calls for the resolved current repository only, and rejects owner-prefixed or unsafe branch refs before the request. Omitted fields require configured autofill.

package/docs/TUI_CAPTURE.md

@@ -24,7 +24,7 @@ Commands only show info; BranchMe tools perform actions.
 
 1. `branch_status` — inspect repo and branch state.
 2. `change_branch` — switch to a clean existing local branch.
-3. `fetch_branch` — fetch its configured upstream remote without changing local files.
+3. `fetch_branch` — fetch its configured upstream remote (or an explicit `remote`/`branch`) without changing local files.
 4. `pull_branch` — fast-forward from upstream, or `rebase_branch` — rebase local commits onto upstream.
 5. `create_branch` — create a new branch from the updated `HEAD`.
 6. Commit outside BranchMe.
@@ -58,7 +58,7 @@ Commands only show info; BranchMe tools perform actions.
 - Run inside a Git repo with `git` available.
 - For PRs: GitHub `origin` and `GITHUB_TOKEN` or `GH_TOKEN` (environment or `.env`).
 - Optional: set `BRANCHME_PR_AUTOFILL=true` in the environment or `.env` to generate omitted PR fields.
-- `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.
+- `fetch_branch` without `branch`, `pull_branch`, and `rebase_branch` require a configured upstream.
 - `pull_branch` and `rebase_branch` require a clean working tree.
 - `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.
 - BranchMe never stages, creates user-authored commits, or force-pushes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Pi extension for verified current-repository Git branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/commands/branchme-command.ts

@@ -33,7 +33,7 @@ export function getBranchMeHelpText(): string {
     "",
     "1. `branch_status` — inspect repo and branch state.",
     "2. `change_branch` — switch to a clean existing local branch.",
-    "3. `fetch_branch` — fetch its configured upstream remote without changing local files.",
+    "3. `fetch_branch` — fetch its configured upstream remote (or an explicit `remote`/`branch`) without changing local files.",
     "4. `pull_branch` — fast-forward from upstream, or `rebase_branch` — rebase local commits onto upstream.",
     "5. `create_branch` — create a new branch from the updated `HEAD`.",
     "6. Commit outside BranchMe.",
@@ -67,7 +67,7 @@ export function getBranchMeHelpText(): string {
     "- Run inside a Git repo with `git` available.",
     "- For PRs: GitHub `origin` and `GITHUB_TOKEN` or `GH_TOKEN` (environment or `.env`).",
     "- Optional: set `BRANCHME_PR_AUTOFILL=true` in the environment or `.env` to generate omitted PR fields.",
-    "- `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.",
+    "- `fetch_branch` without `branch`, `pull_branch`, and `rebase_branch` require a configured upstream.",
     "- `pull_branch` and `rebase_branch` require a clean working tree.",
     "- `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.",
     "- BranchMe never stages, creates user-authored commits, or force-pushes.",

package/src/git.ts

@@ -33,6 +33,7 @@ import type {
   CreateWorktreeMode,
   CurrentBranchInfo,
   FetchBranchDetails,
+  FetchRemoteBranchDetails,
   GitExecResult,
   GitFileChange,
   GitFileChangeSummary,
@@ -1185,6 +1186,39 @@ function worktreeCreationFailure(
   );
 }
 
+async function resolveWorktreeBaseCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  baseRef: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  // baseRef is a read-only start point: it is resolved to a commit before mutation and
+  // is never checked out, reset, or otherwise modified.
+  if (/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(baseRef)) {
+    const result = await runGit(pi, ctx, ["rev-parse", "--verify", `${baseRef}^{commit}`], {
+      signal,
+      timeout: GIT_STATUS_TIMEOUT_MS,
+      allowFailure: true,
+    });
+    const commit = trimOutput(result.stdout);
+    if (result.code !== 0 || !/^[0-9a-f]{40,64}$/iu.test(commit)) {
+      throw new Error(`baseRef ${safeWorktreeBranchLabel(baseRef)} does not resolve to an existing commit.`);
+    }
+    return commit;
+  }
+
+  await validateBranchName(pi, ctx, baseRef, signal);
+  if (await localBranchExists(pi, ctx, baseRef, signal)) {
+    return getLocalBranchCommit(pi, ctx, baseRef, signal);
+  }
+  if (await remoteTrackingRefExists(pi, ctx, baseRef, signal)) {
+    return getRemoteTrackingRefCommit(pi, ctx, baseRef, signal);
+  }
+  throw new Error(
+    `baseRef ${safeWorktreeBranchLabel(baseRef)} does not name an existing local branch, remote-tracking ref, or full commit.`,
+  );
+}
+
 export async function createWorktree(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -1192,8 +1226,15 @@ export async function createWorktree(
   branchName: string,
   branchMode: CreateWorktreeMode,
   signal?: AbortSignal,
+  baseRef?: string,
 ): Promise<CreateWorktreeDetails> {
   validateCreateWorktreeMode(branchMode);
+  if (baseRef !== undefined) {
+    if (branchMode !== "new") {
+      throw new Error("baseRef is only supported with branchMode 'new'; an existing local branch keeps its own commit.");
+    }
+    validateBranchNameInput(baseRef, "baseRef");
+  }
   const requestedWorktreePath = validateWorktreePathInput(worktreePath);
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
@@ -1222,11 +1263,14 @@ export async function createWorktree(
       throw new Error(`Local branch ${safeWorktreeBranchLabel(branchName)} is already checked out in a worktree.`);
     }
 
+    const baseCommit = baseRef === undefined
+      ? null
+      : await resolveWorktreeBaseCommit(pi, rootCtx, baseRef, signal);
     const expectedHead = branchMode === "new"
-      ? sourceHead
+      ? baseCommit ?? sourceHead
       : await getLocalBranchCommit(pi, rootCtx, branchName, signal);
     const args = branchMode === "new"
-      ? ["worktree", "add", "-b", branchName, prepared.canonicalPath, "HEAD"]
+      ? ["worktree", "add", "-b", branchName, prepared.canonicalPath, baseCommit ?? "HEAD"]
       : ["worktree", "add", prepared.canonicalPath, branchName];
 
     try {
@@ -1263,6 +1307,9 @@ export async function createWorktree(
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
           branchName: handoffBranch,
           branchMode,
+          ...(baseRef === undefined
+            ? {}
+            : { baseRef: safeWorktreeValue(baseRef, GIT_CONTEXT_VALUE_LIMIT_CHARS) }),
         },
         verified: {
           before: {
@@ -1994,24 +2041,58 @@ export async function inspectDirectLocalBranchRef(
   };
 }
 
-export async function getLocalBranchCommit(
+async function getVerifiedRefCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
-  branchName: string,
+  revision: string,
+  describedRef: string,
   signal?: AbortSignal,
 ): Promise<string> {
-  validateBranchNameInput(branchName);
-  const result = await runGit(pi, ctx, ["rev-parse", "--verify", `refs/heads/${branchName}^{commit}`], {
+  const result = await runGit(pi, ctx, ["rev-parse", "--verify", `${revision}^{commit}`], {
     signal,
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
   const commit = trimOutput(result.stdout);
   if (!/^[0-9a-f]{40,64}$/iu.test(commit)) {
-    throw new Error(`Unable to resolve local branch '${safeGitContextValue(branchName)}' to a commit: ${safeOutput(result.stdout) || "empty output"}`);
+    throw new Error(`Unable to resolve ${describedRef} to a commit: ${safeOutput(result.stdout) || "empty output"}`);
   }
   return commit;
 }
 
+export async function getLocalBranchCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  branchName: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  validateBranchNameInput(branchName);
+  return getVerifiedRefCommit(pi, ctx, `refs/heads/${branchName}`, `local branch '${safeGitContextValue(branchName)}'`, signal);
+}
+
+export async function remoteTrackingRefExists(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const result = await runGit(pi, ctx, ["show-ref", "--verify", "--quiet", `refs/remotes/${refName}`], {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  return result.code === 0;
+}
+
+export async function getRemoteTrackingRefCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  validateBranchNameInput(refName, "Remote-tracking ref");
+  return getVerifiedRefCommit(pi, ctx, `refs/remotes/${refName}`, `remote-tracking ref '${safeGitContextValue(refName)}'`, signal);
+}
+
 export async function requireExistingLocalBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -2044,6 +2125,24 @@ export async function isCommitAncestor(
   return result.code === 0;
 }
 
+async function resolveAncestryRefCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  refName: string,
+  label: "Source" | "Target",
+  signal?: AbortSignal,
+): Promise<string> {
+  // Read-only comparison endpoints: local branches keep precedence, remote-tracking refs
+  // (for example origin/main) are accepted as read baselines and are never mutated.
+  if (await localBranchExists(pi, ctx, refName, signal)) {
+    return getLocalBranchCommit(pi, ctx, refName, signal);
+  }
+  if (await remoteTrackingRefExists(pi, ctx, refName, signal)) {
+    return getRemoteTrackingRefCommit(pi, ctx, refName, signal);
+  }
+  throw new Error(`${label} local branch or remote-tracking ref '${safeGitContextValue(refName)}' does not exist.`);
+}
+
 export async function getLocalBranchAncestry(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -2054,11 +2153,9 @@ export async function getLocalBranchAncestry(
   validateBranchNameInput(query.targetBranch, "Target branch");
   await validateBranchName(pi, ctx, query.sourceBranch, signal);
   await validateBranchName(pi, ctx, query.targetBranch, signal);
-  await requireExistingLocalBranch(pi, ctx, query.sourceBranch, "Source", signal);
-  await requireExistingLocalBranch(pi, ctx, query.targetBranch, "Target", signal);
 
-  const sourceHead = await getLocalBranchCommit(pi, ctx, query.sourceBranch, signal);
-  const targetHead = await getLocalBranchCommit(pi, ctx, query.targetBranch, signal);
+  const sourceHead = await resolveAncestryRefCommit(pi, ctx, query.sourceBranch, "Source", signal);
+  const targetHead = await resolveAncestryRefCommit(pi, ctx, query.targetBranch, "Target", signal);
   const isAncestor = await isCommitAncestor(pi, ctx, sourceHead, targetHead, signal);
 
   return {
@@ -2181,6 +2278,74 @@ export async function fetchCurrentBranch(
   });
 }
 
+function validateRequestedRemoteName(remote: string): void {
+  if (!remote || /[\u0000-\u001f\u007f]/u.test(remote) || /\s/u.test(remote)) {
+    throw new Error("Unable to fetch: remote cannot be blank or contain whitespace or control characters.");
+  }
+  if (remote === ".") throw new Error("Unable to fetch: remote must name a configured Git remote, not '.'.");
+  if (remote.startsWith("-")) throw new Error("Unable to fetch: remote cannot start with '-'.");
+  if (remote.includes(":") || remote.includes("@")) {
+    throw new Error("Unable to fetch: remote cannot be a URL or user-prefixed target.");
+  }
+}
+
+async function requireConfiguredRemote(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  remote: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const result = await runGit(pi, ctx, ["remote", "get-url", remote], {
+    signal,
+    timeout: GIT_STATUS_TIMEOUT_MS,
+    allowFailure: true,
+  });
+  if (result.code !== 0) {
+    throw new Error(`Unable to fetch: remote '${safeGitContextValue(remote)}' is not a configured Git remote.`);
+  }
+}
+
+export async function fetchRemoteBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  remote: string,
+  branch: string,
+  signal?: AbortSignal,
+): Promise<FetchRemoteBranchDetails> {
+  validateRequestedRemoteName(remote);
+  validateBranchNameInput(branch, "branch");
+  const repoRoot = await getGitRoot(pi, ctx, signal);
+  const rootCtx = { cwd: repoRoot };
+
+  return withRepositoryMutationQueue(repoRoot, async () => {
+    await validateBranchName(pi, rootCtx, branch, signal);
+    await requireConfiguredRemote(pi, rootCtx, remote, signal);
+
+    const remoteRef = `refs/heads/${branch}`;
+    const trackingRef = `refs/remotes/${remote}/${branch}`;
+    const refspec = `${remoteRef}:${trackingRef}`;
+    const result = await runGit(
+      pi,
+      rootCtx,
+      ["fetch", "--no-tags", "--no-recurse-submodules", remote, refspec],
+      {
+        signal,
+        timeout: GIT_FETCH_TIMEOUT_MS,
+      },
+    );
+
+    return {
+      repoRoot,
+      remote: safeDetail(remote),
+      branch: safeDetail(branch),
+      remoteRef: safeDetail(remoteRef),
+      remoteTrackingRef: safeDetail(trackingRef),
+      refspec: safeDetail(refspec),
+      output: safeOutput(result.stdout || result.stderr),
+    };
+  });
+}
+
 export async function pullCurrentBranch(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,

package/src/tools/branchme-tools.ts

@@ -24,6 +24,7 @@ import {
   createLocalBranch,
   createWorktree,
   fetchCurrentBranch,
+  fetchRemoteBranch,
   getGitRoot,
   getLocalBranchCommit,
   getPullRequestCommitSubjects,
@@ -74,8 +75,8 @@ const BranchStatusParametersSchema = Type.Object(
     ancestry: Type.Optional(
       Type.Object(
         {
-          sourceBranch: Type.String({ minLength: 1, description: "Exact existing local source branch to verify." }),
-          targetBranch: Type.String({ minLength: 1, description: "Exact existing local target branch to verify." }),
+          sourceBranch: Type.String({ minLength: 1, description: "Exact existing local branch or remote-tracking ref (for example origin/main) whose commit is verified as the ancestor." }),
+          targetBranch: Type.String({ minLength: 1, description: "Exact existing local branch or remote-tracking ref (for example origin/main) whose commit is verified as the descendant." }),
         },
         { additionalProperties: false },
       ),
@@ -124,8 +125,26 @@ const CreateWorktreeParametersSchema = Type.Object(
     worktreePath: Type.String({ minLength: 1, description: "Explicit absolute destination path for the linked worktree." }),
     branchName: Type.String({ minLength: 1, description: "New or existing local branch name for the linked worktree." }),
     branchMode: StringEnum(["new", "existing"] as const, {
-      description: "Whether create_worktree creates a new local branch from current HEAD or uses an existing local branch.",
+      description: "Whether create_worktree creates a new local branch (from current HEAD, or from baseRef when provided) or uses an existing local branch.",
     }),
+    baseRef: Type.Optional(Type.String({
+      minLength: 1,
+      description: "Optional read-only start point for branchMode 'new': an exact existing local branch, remote-tracking ref (for example origin/main), or full commit that the new branch starts from instead of current HEAD. Never checked out or mutated.",
+    })),
+  },
+  { additionalProperties: false },
+);
+
+const FetchBranchParametersSchema = Type.Object(
+  {
+    remote: Type.Optional(Type.String({
+      minLength: 1,
+      description: "Configured remote name for a targeted fetch; defaults to origin and requires branch. Omit together with branch to fetch the current branch's configured upstream.",
+    })),
+    branch: Type.Optional(Type.String({
+      minLength: 1,
+      description: "Exact branch name on the remote (for example main) to fetch into its remote-tracking ref without touching local branches or the current branch's upstream. Omit to fetch the current branch's configured upstream.",
+    })),
   },
   { additionalProperties: false },
 );
@@ -256,7 +275,10 @@ export function formatCreateWorktree(details: CreateWorktreeDetails): string {
   const cwd = safeWorktreeFormatValue(details.handoff.cwd, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
   const branch = safeWorktreeFormatValue(details.handoff.branch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
   const mode = details.request.branchMode === "new" ? "new local branch" : "existing local branch";
-  return `Created linked worktree ${cwd} for ${mode} ${branch}. Verified its canonical path, local branch, HEAD ${shortCommit(details.handoff.head)}, clean working tree, and ready handoff.`;
+  const base = details.request.baseRef === undefined
+    ? ""
+    : ` from base ${safeWorktreeFormatValue(details.request.baseRef, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS)}`;
+  return `Created linked worktree ${cwd} for ${mode} ${branch}${base}. Verified its canonical path, local branch, HEAD ${shortCommit(details.handoff.head)}, clean working tree, and ready handoff.`;
 }
 
 export function formatRemoveWorktree(details: RemoveWorktreeDetails): string {
@@ -487,12 +509,13 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: BRANCH_STATUS_TOOL_NAME,
     label: "Branch Status",
-    description: "branch_status explicitly refreshes the current Git repository snapshot and can optionally verify whether one captured local branch commit is an ancestor of another. branch_status is read-only and never mutates files, Git state, or GitHub state.",
-    promptSnippet: "branch_status: explicitly refresh current-repository Git state and optionally verify targeted local-branch ancestry without mutation",
+    description: "branch_status explicitly refreshes the current Git repository snapshot and can optionally verify whether one captured branch commit is an ancestor of another; ancestry endpoints may be exact local branches or remote-tracking refs such as origin/main. branch_status is read-only and never mutates files, Git state, or GitHub state.",
+    promptSnippet: "branch_status: explicitly refresh current-repository Git state and optionally verify targeted local-branch or remote-tracking ancestry without mutation",
     promptGuidelines: [
       "Use the automatic Git context for start-of-run questions; call branch_status only for an explicit refresh or after Git state changes during the current run.",
       "Use branch_status as a read-only refresh; branch_status never mutates files, Git state, or GitHub state.",
       "Use targeted branch_status ancestry verification only after integrate_branch completes; do not issue branch_status in the same parallel tool batch as integrate_branch.",
+      "Use branch_status ancestry with a remote-tracking target such as origin/main after fetch_branch completes to prove a branch is contained in the fetched baseline; branch_status never checks out or resets remote-tracking refs.",
     ],
     parameters: BranchStatusParametersSchema,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -564,18 +587,29 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: FETCH_BRANCH_TOOL_NAME,
     label: "Fetch Branch",
-    description: "fetch_branch fetches the current branch's configured upstream branch into its remote-tracking ref with an explicit git fetch --no-tags --no-recurse-submodules refspec. fetch_branch does not change local branches or working-tree files and never prunes, rebases, merges, stashes, stages, commits, or pushes.",
-    promptSnippet: "fetch_branch: fetch the current branch's configured upstream into its remote-tracking ref without changing local branches or files",
+    description: "fetch_branch fetches one branch into its remote-tracking ref with an explicit git fetch --no-tags --no-recurse-submodules refspec. Without arguments fetch_branch fetches the current branch's configured upstream; with branch (and optional remote, default origin) it fetches that exact remote branch without touching local branches, the working tree, or the current branch's upstream configuration. fetch_branch never prunes, rebases, merges, stashes, stages, commits, or pushes.",
+    promptSnippet: "fetch_branch: fetch the current branch's configured upstream, or an explicit remote branch, into its remote-tracking ref without changing local branches or files",
     promptGuidelines: [
-      "Use fetch_branch only when the user explicitly wants to fetch the configured upstream branch for the current branch.",
-      "Use fetch_branch only on a current branch with an upstream; fetch_branch has no branchName, remote, tags, prune, force, or refspec parameters.",
-      "Call fetch_branch and wait for it to complete before rebase_branch when the user wants the latest upstream state; do not batch fetch_branch with rebase_branch.",
+      "Use fetch_branch without arguments to fetch the configured upstream branch for the current branch; that default requires a current branch with an upstream.",
+      "Use fetch_branch with branch (and optional remote, default origin) to refresh another remote-tracking ref such as origin/main; fetch_branch never changes local branches, working-tree files, or upstream configuration, and remote requires branch.",
+      "Call fetch_branch and wait for it to complete before rebase_branch or a targeted branch_status ancestry proof against the fetched remote-tracking ref; do not batch fetch_branch with dependent calls.",
     ],
-    parameters: EmptyParametersSchema,
-    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
-      const details = await fetchCurrentBranch(pi, ctx, signal);
+    parameters: FetchBranchParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (params.branch === undefined) {
+        if (params.remote !== undefined) {
+          throw new Error("fetch_branch remote requires branch; omit both to fetch the current branch's configured upstream.");
+        }
+        const details = await fetchCurrentBranch(pi, ctx, signal);
+        return {
+          content: [{ type: "text", text: `Fetched configured upstream remote ${details.remote} for current branch ${details.currentBranch}.` }],
+          details,
+        };
+      }
+
+      const details = await fetchRemoteBranch(pi, ctx, params.remote ?? "origin", params.branch, signal);
       return {
-        content: [{ type: "text", text: `Fetched configured upstream remote ${details.remote} for current branch ${details.currentBranch}.` }],
+        content: [{ type: "text", text: `Fetched ${details.remote}/${details.branch} into remote-tracking ref ${details.remoteTrackingRef} without changing local branches.` }],
         details,
       };
     },
@@ -696,7 +730,8 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     description: "pull_request creates a GitHub pull request in the resolved current repository. PR fields are optional only when BRANCHME_PR_AUTOFILL=true; pull_request then infers branches, derives title/body from commit subjects, and defaults draft to false. Branches must exist locally and on GitHub, and headBranch must match the GitHub-visible commit. Owner-prefixed refs, owner, and repo are never accepted as inputs.",
     promptSnippet: "pull_request: create a GitHub pull request with explicit fields or optional configured PR field autofill",
     promptGuidelines: [
-      "Use pull_request only when the user explicitly asks to create a pull request; pull_request must not create one merely because a branch was pushed.",
+      "Use pull_request whenever creating a pull request is appropriate for the active workflow; authorization may come from user prompts, system or developer instructions, AGENTS.md, skills, automation, or delegated/subagent prompts.",
+      "Agents may invoke pull_request without a separate end-user confirmation when the active workflow makes pull request creation appropriate.",
       "When automatic Git context reports pull request field autofill disabled, use pull_request only with explicit headBranch, baseBranch, title, body, and draft values.",
       "When automatic Git context reports pull request field autofill enabled, pull_request may omit fields the user did not provide; prefer the user's explicit values whenever present.",
       "Use pull_request only with existing local branches for headBranch and baseBranch; headBranch must match the GitHub-visible branch commit.",
@@ -766,11 +801,12 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: CREATE_WORKTREE_TOOL_NAME,
     label: "Create Worktree",
-    description: "create_worktree creates and verifies one linked worktree at an explicit absolute worktreePath for either a new local branch from current HEAD or an existing unoccupied local branch. create_worktree returns exact lossless handoff identity fields and never infers paths, remotes, base refs, detached or orphan modes, or force behavior.",
-    promptSnippet: "create_worktree: create and verify a linked worktree at an explicit absolute path with a ready handoff cwd",
+    description: "create_worktree creates and verifies one linked worktree at an explicit absolute worktreePath for either a new local branch (from current HEAD, or from an explicit read-only baseRef such as origin/main or a full commit) or an existing unoccupied local branch. create_worktree returns exact lossless handoff identity fields and never infers paths, remotes, base refs, detached or orphan modes, or force behavior.",
+    promptSnippet: "create_worktree: create and verify a linked worktree at an explicit absolute path, optionally starting its new branch from an explicit read-only baseRef, with a ready handoff cwd",
     promptGuidelines: [
       "Use create_worktree only when the user explicitly requests worktree creation and provides or approves the exact absolute worktreePath; create_worktree must never infer a filesystem path silently.",
-      "Use create_worktree with exactly worktreePath, branchName, and branchMode; create_worktree never accepts force, baseRef, remote, detach, orphan, move, prune, repair, lock, or unlock parameters.",
+      "Use create_worktree with worktreePath, branchName, branchMode, and optionally baseRef for branchMode 'new'; create_worktree never accepts force, remote, detach, orphan, move, prune, repair, lock, or unlock parameters.",
+      "Use create_worktree with an explicit baseRef such as origin/main to start a new branch from a fetched remote baseline regardless of the current checkout's branch, dirt, or staleness; create_worktree only reads baseRef and never checks out or resets it.",
       "Do not batch create_worktree with dependent worktree mutations; wait for create_worktree to complete and verify its ready exact handoff.cwd before passing that cwd to another agent or session.",
     ],
     parameters: CreateWorktreeParametersSchema,
@@ -782,6 +818,7 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
         params.branchName,
         params.branchMode,
         signal,
+        params.baseRef,
       );
       return {
         content: [{ type: "text", text: formatCreateWorktree(details) }],

package/src/types.ts

@@ -49,6 +49,8 @@ export interface CreateWorktreeToolInput {
   worktreePath: string;
   branchName: string;
   branchMode: CreateWorktreeMode;
+  /** Optional read-only start point for branchMode "new": local branch, remote-tracking ref, or full commit. */
+  baseRef?: string;
 }
 
 export interface RemoveWorktreeToolInput {
@@ -238,6 +240,16 @@ export interface FetchBranchDetails {
   output: string;
 }
 
+export interface FetchRemoteBranchDetails {
+  repoRoot: string;
+  remote: string;
+  branch: string;
+  remoteRef: string;
+  remoteTrackingRef: string;
+  refspec: string;
+  output: string;
+}
+
 export interface PullBranchDetails {
   repoRoot: string;
   currentBranch: string;