@senad-d/branchme 0.3.15 → 0.3.17

package/CHANGELOG.md

@@ -1,7 +1,22 @@
 # Changelog
 
+## 0.3.17 - Unreleased
+
+- `revert_changes` refuses only ignored files at the paths the reverted commit touches, which Git could overwrite. Before, any ignored file in the checkout (`.env`, `.pi/`, `node_modules`) refused the revert, and in a repository with installed dependencies the whole-checkout listing passed the 4 MiB read cap first ("Local Git inspection exceeded the 4 MiB safety limit"), so the tool could not run in a working project.
+
+## 0.3.16 - Unreleased
+
+- Added `commit_changes`, ported from CommitMe with the same behavior: `action: "gather"` returns read-only bounded commit context; `action: "commit"` commits an explicit subject or drafts one with the active model; `paths`, `steeringPrompt`, `confirm`, and unsafe-file approval work as before. The tool uses BranchMe's Git runner, lock retry, redacted Git errors, 30-second mutation timeout, worktree routing, tool mutation coordinator, and blocker guidance. Commits now stage and commit from the repository root, fixing CommitMe's failure when Pi runs in a subdirectory. The `/commitme` command is not included. Uninstall `@senad-d/commitme` to avoid two commit tools.
+- Resolved Sonar findings in Git inspection, guarded index/restoration/revert operations, remote configuration, and GitHub PR workflows: extracted focused helpers, parallelized independent bounded reads, retained bounded filesystem concurrency, made alphabetical sorting explicit, and simplified validation and error formatting. Preserved strict rejection of null diff modes and added mixed-case remote sorting regression coverage.
+
 ## 0.3.15 - Unreleased
 
+- Simplified LLM-facing descriptions, snippets, and guidelines without renaming tools or changing schemas or execution. Descriptions omit repeated names and parameter manuals; schemas explain arguments, with optional rules for essential safety and sequencing. Prose shrank from 4,170 to 1,287 words (about 69%); this is a text measurement, not a model-token count. Added scope/safety and prose-budget regressions, removed mandatory name repetition and nonempty-guideline tests, and verified single-prefix rendering in real Pi smoke.
+- Removed fixed tool-count assertions, prose-total tests, and duplicate name-only inventories in favor of canonical names and exact registration/documentation/schema coverage. Agents never need to estimate an output length; `git_diff({})` uses shared defaults and reports comparison, scope, bounded filter previews, and completeness before the diff body. Added actionable local errors, neutral Git-timeout guidance, corrected guarded-switch metadata for `land_branch`, and a real Pi model-loop smoke for default diff inspection.
+- Completed the shell-free workflow expansion: bounded `git_log`/`git_show`, `git_conflicts` index-stage inspection, consistent same-repository worktree routing and cross-worktree tool mutation coordination, explicit branch/rebase bases, `list_remotes`/`add_remote`/`set_upstream`, guarded `stage_changes`/`unstage_changes`, previewed `restore_paths`, and verified no-commit `revert_changes`. Ordinary commits and CommitMe remain independent. Guarded file/index operations use fresh expectations and conservative unsupported-index boundaries; explicit-base rebases/reverts protect ignored local-only residue by refusing it.
+- Added `pull_request_checks`, explicit PR metadata editing, and guarded host `merge_pull_request`: complete state distinctions, expected-head leases, enabled merge methods, host-readiness checks, read-only reconciliation of uncertain writes, and no bypass/auto-cleanup/remote deletion. Expanded isolated Git/GitHub/schema/runtime tests and documented all safety boundaries in `docs/SHELL_FREE_WORKFLOWS.md`.
+- Added independent read-only `git_status` for complete paginated staged/unstaged/untracked/conflicted/renamed/deleted file discovery, literal filters, verified worktree targeting, current operations, logical index and snapshot expectations, and optional filtered-file content fingerprints without exposing contents. Stale continuation and collection-time changes fail; unsafe displayed paths are explicitly non-reusable. Automatic context and CommitMe remain unchanged.
+- Added read-only `git_diff`: unstaged/staged changes, captured ref comparisons with optional unique merge base, literal root-relative filters, linked-worktree targeting, and patch/stat/name-status output. Redacted/control-escaped display and details are capped at 1,000 lines / 32 KiB with explicit truncation. External diff/textconv, fsmonitor, optional locks, and lazy fetching are disabled; no diff artifact or automatic diff collection is added. Requires Git with `--no-lazy-fetch` support.
 - `integrate_branch`, `conclude_merge` and `branch_status` accept optional `worktreePath`, so one git agent session can act on several worktrees of the same repository. It must be the absolute root of the primary checkout or a registered linked worktree with the same Git common directory; relative, missing, subdirectory, bare and foreign paths are refused. The tool then runs as if the session cwd were that worktree (control worktree, clean checks, `keepConflicts`, and the per-worktree mutation queue). A `conflict_kept` result now names its `worktreeRoot`.
 
 ## 0.3.14 - Unreleased

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and twenty-five agent-callable tools that initialize a repository, refresh state, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, read and answer PR feedback, and list and label a PR's changed files.
+BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and agent-callable tools that initialize a repository, refresh state, inspect local diffs, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, read and answer PR feedback, and list and label a PR's changed files.
 
 <table align="center">
   <tr>
@@ -31,10 +31,10 @@ BranchMe is a Pi extension for safe Git repository, branch, and worktree workflo
 
 - **Context-aware:** every agent run starts with bounded branch, working-tree, related-PR, and recent-commit metadata; repository metadata is untrusted data, not instructions.
 - **Repository-scoped:** `init_repository` can initialize only pi's exact current working directory when it is not already inside a repository. Other Git and GitHub operations resolve from the checkout where pi is running. Linked worktree directories may be outside that checkout, but must be verified members of the same repository.
-- **Explicit history rewrites:** `rebase_branch` runs only when explicitly requested, requires a clean current branch with an upstream, disables autostash and multi-ref updates, and automatically attempts to abort on failure.
+- **Explicit history rewrites:** `rebase_branch` runs only when explicitly requested, requires a clean current branch and either an upstream or explicit `baseRef`, disables autostash and multi-ref updates, and automatically attempts to abort on failure.
 - **Verified worktree handoff:** `create_worktree` verifies path, branch, `HEAD`, and cleanliness before returning an absolute `handoff.cwd`; starting another Pi session or subagent there remains the caller's responsibility.
-- **Commit-safe:** context collection is read-only, and BranchMe never creates user-authored commits, accepts or generates commit messages, force-pushes, resets, or edits files directly. Explicit `integrate_branch` and `update_from_base` calls may let Git create a standard merge commit for divergent histories; `conclude_merge` stages only the formerly unmerged paths of a kept merge and commits them with Git's prepared merge message.
-- **Strict tools:** tool schemas reject undocumented properties such as `stash`, `discard`, `owner`, `repo`, or `path`; `baseRef` is supported only by `create_worktree` in new-branch mode; the only force decision is the required boolean on `retire_branch`, and every tool accepts only its documented fields.
+- **Commit-safe:** context collection is read-only, and BranchMe never force-pushes or resets. Ordinary commits happen only through `commit_changes`, which validates a one-line Conventional Commit subject and never push. Guarded index operations and explicitly authorized selected-file restoration are supported without ordinary commits. Explicit `integrate_branch` and `update_from_base` calls may let Git create a standard merge commit for divergent histories; `conclude_merge` stages only the formerly unmerged paths of a kept merge and commits them with Git's prepared merge message.
+- **Strict tools:** tool schemas reject undocumented properties such as `stash`, `discard`, `owner`, `repo`, or `path`; `baseRef` is supported by `create_branch`, `rebase_branch`, and `create_worktree` in new-branch mode; the only force decision is the required boolean on `retire_branch`, and every tool accepts only its documented fields.
 - **PR-ready:** create GitHub pull requests from existing local branches after verifying the `headBranch` matches GitHub and the base is visible. PR fields can stay explicit, or configured autofill can derive omitted fields from the current branch, default branch, and commit subjects.
 
 > **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may initialize `.git` metadata in the current directory, may create or remove verified linked-worktree directories outside the active checkout, may integrate local history or retire one exact local branch ref, may make an automatic authenticated GitHub request to find a related open pull request, can update branches and remotes, and can create GitHub pull requests. Repository-configured hooks—including `reference-transaction` hooks invoked by retirement—merge drivers, filters, and signing policy may run commands or contact networks outside BranchMe's direct argv guarantees. Read [`SECURITY.md`](SECURITY.md).
@@ -103,7 +103,7 @@ A typical BranchMe flow is:
 7. While working, use `update_from_base({ baseBranch: "main" })` to fetch and merge the remote base into the clean feature branch without rewriting published history or changing its upstream. A conflict is aborted and its paths listed; with `keepConflicts: true` the conflicted merge stays in progress so a file-editing step can remove the markers, after which `conclude_merge({ action: "conclude" })` commits it or `conclude_merge({ action: "abort" })` restores the branch.
 8. Push the current branch with `push_branch`.
 9. After `push_branch` completes and GitHub can see the branches, create or reuse a matching open pull request with `pull_request`.
-10. Inspect the PR with `pull_request_status({ number: 123 })`. Merge it on GitHub outside BranchMe, then use `land_branch` from the primary checkout. Supply `pullRequestNumber: 123` for squash/rebase merge evidence.
+10. Inspect the PR with `pull_request_status({ number: 123 })` and `pull_request_checks`. When explicitly authorized, use `merge_pull_request` (or merge on GitHub), then use `land_branch` from the primary checkout. Supply `pullRequestNumber: 123` for squash/rebase merge evidence.
 
 For isolated work, a specialized Git subagent can use the explicit worktree workflow:
 
@@ -202,7 +202,7 @@ $EDITOR .env
 pi
 ```
 
-`fetch_remote`, `fetch_branch`, `pull_branch`, `push_branch`, and `land_branch` run git with terminal prompts disabled, so missing credentials fail at once instead of hanging. Your normal Git credentials are tried first; for `https://github.com` remotes the same `GITHUB_TOKEN`/`GH_TOKEN` (process environment or repository `.env`) then answers as a credential helper, passed to git through its environment and never on the command line. A token alone is enough. `rebase_branch` operates on the locally available configured upstream ref and makes no network request itself.
+`fetch_remote`, `fetch_branch`, `pull_branch`, `push_branch`, and `land_branch` run git with terminal prompts disabled, so missing credentials fail at once instead of hanging. Your normal Git credentials are tried first; for `https://github.com` remotes the same `GITHUB_TOKEN`/`GH_TOKEN` (process environment or repository `.env`) then answers as a credential helper, passed to git through its environment and never on the command line. A token alone is enough. `rebase_branch` operates on a locally available configured upstream or explicit base and makes no network request itself.
 When the current branch already has an upstream, BranchMe pushes an explicit `HEAD:<upstream-branch-ref>` refspec to the configured upstream remote instead of relying on a bare `git push`.
 Run `pull_request` only after `push_branch` has completed; `pull_request` preflights the GitHub `headBranch` and `baseBranch` before creating the PR and fails with retry guidance if a branch is not visible yet or the GitHub `headBranch` commit does not match the local branch.
 
@@ -252,45 +252,141 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 
 | Tool | Schema | Behavior |
 | --- | --- | --- |
+| `git_log` | `{ "ref"?: string, "excludeRef"?: string, "paths"?: string[], "after"?: string, "worktreePath"?: string }` | Read 25 locally available commits per page, pinned to captured start/exclusion commits. Reports shallow/unborn history; never fetches. |
+| `git_show` | `{ "ref"?: string, "output"?: "summary" \| "patch" \| "file", "path"?: string, "parent"?: integer, "worktreePath"?: string }` | Inspect a commit or historical blob without checkout; file mode requires a literal path and merge comparisons require an explicit parent. Bounded text, safe binary/oversized summaries. |
+| `git_conflicts` | `{ "path"?: string, "stage"?: integer, "expectedIndex"?: string, "after"?: string, "worktreePath"?: string }` | List conflicts or inspect available base/ours/theirs index versions. Missing stages are explicit; never resolves or stages. |
+| `list_remotes` | `{}` | Inspect configured/effective destinations and a configuration fingerprint without network access. Bounded previews with omissions and unsupported settings reported. |
+| `add_remote` | `{ "name": string, "url": string, "expectedConfig": string }` | Add an unused non-overlapping remote using credential-free HTTPS/SSH; no fetch, overwrite, URL rewrite, or global config change. |
+| `set_upstream` | `{ "branchName": string, "upstream"?: string, "unset"?: boolean, "expectedConfig": string }` | Set one existing remote-tracking upstream or explicitly unset it, preserving refs/files and other branch configuration. |
+| `commit_changes` | `{ "action"?: "gather" \| "commit", "message"?: string, "steeringPrompt"?: string, "paths"?: string[], "confirm"?: boolean, "worktreePath"?: string }` | `gather` (default) is read-only and returns bounded commit context for drafting one subject. `commit` with `message` commits that validated subject; without `message` it drafts one with the active model. `paths` limits staging and committing to exact repo-relative paths. Unsafe files require UI approval or block the commit. Never pushes. |
+| `stage_changes` | `{ "paths": string[], "expectedHead": string \| null, "expectedIndex": string, "worktreePath"?: string }` | Stage exact approved files with fresh inspection expectations. Preserves working files/unrelated index entries; never commits. |
+| `unstage_changes` | `{ "paths": string[], "expectedHead": string \| null, "expectedIndex": string, "worktreePath"?: string }` | Return selected index entries to captured HEAD (or unstage unborn additions), preserving working bytes. Never discards edits or commits. |
+| `restore_paths` | `{ "paths": string[], "expectedHead": string \| null, "expectedIndex": string, "preview"?: boolean, "sourceRef"?: string, "discardChanges"?: boolean, "expectedFiles"?: { "path": string, "fingerprint": string }[], "worktreePath"?: string }` | Preview, then explicitly authorize replacement/deletion of selected tracked working files with fresh per-file expectations. Preserves logical index entries; protects untracked/ignored files. |
+| `revert_changes` | `{ "commit": string, "expectedHead": string, "expectedIndex": string, "worktreePath"?: string }` | Stage one non-merge commit's inverse without committing. Requires clean idle state; conflicts attempt verified abort/restoration. |
+| `pull_request_checks` | `{ "number": integer, "after"?: string }` | Read all run/status states and available host readiness for a captured head, distinguishing partial/unknown/pending/no-check states from success. |
+| `edit_pull_request` | `{ "number": integer, "title"?: string, "body"?: string, "draft"?: boolean }` | Change only explicit metadata fields on an open PR, with verified results and conservative uncertain-outcome handling. |
+| `merge_pull_request` | `{ "number": integer, "expectedHead": string, "mergeMethod": "merge" \| "squash" \| "rebase" }` | Perform an explicitly authorized ready host merge with an expected-head lease; no bypass, automatic cleanup, or remote branch deletion. |
+| `git_status` | `{ "paths"?: string[], "worktreePath"?: string, "after"?: string }` | Enumerate staged, unstaged, untracked, renamed/deleted, and conflicted paths with separate index/worktree states. Up to 50 entries / 24 KiB per page; follow `next` with identical filters/worktree until `complete`. Literal root-relative filters and verified same-repository worktree targeting; no network or mutation. See below. |
+| `git_diff` | `{ "mode"?: "unstaged" \| "staged" \| "range", "baseRef"?: string, "targetRef"?: string, "mergeBase"?: boolean, "output"?: "patch" \| "stat" \| "name-status", "paths"?: string[], "contextLines"?: integer, "worktreePath"?: string }` | Read local diffs without staging or changing files/refs. Defaults to unstaged patch output. Range mode requires `baseRef`, defaults `targetRef` to `HEAD`, and optionally compares from the unique merge base. Only range mode accepts ref/merge-base fields. Literal root-relative paths, 0–20 context lines (default 3), same-repository worktree targeting, and bounded redacted display. See below. |
 | `list_branches` | `{ "kind"?: "local" \| "remote-tracking", "patterns"?: string[] }` | Read up to 200 matching local/cached remote-tracking refs with commits, upstream counts, symbolic refs, and occupancy. Patterns use Git branch-list globs on names (`origin/topic` for remote refs), match any supplied pattern, and filter before limits. Omit filters for the original full inventory. Accepts 1–25 nonblank patterns of at most 512 characters. No fetch. Raw refs are limited to 128 KiB and text to 4,000 characters; omitted entries are reported. Names/paths are display metadata, not guaranteed executable identities. |
 | `fetch_remote` | `{ "remote"?: string, "prune"?: boolean }` | Refresh all heads for one configured remote (default `origin`) into its remote-tracking namespace. Prune defaults to false; true deletes only that remote's stale cached branch refs. Atomic ref updates, no configured refmap, tags, tag pruning, or submodules. Never changes local refs, checkout, upstream settings, or working-tree files. Files ref backend required for dangling-alias safety. |
-| `track_branch` | `{ "branchName": string, "remote"?: string, "remoteBranch"?: string }` | Fetch one exact remote branch and create/check out a new local tracking branch. Remote defaults to `origin`; remoteBranch defaults to branchName. Requires a clean idle checkout; verifies HEAD and upstream. |
-| `update_from_base` | `{ "baseBranch": string, "remote"?: string, "keepConflicts"?: boolean }` | Fetch the exact remote base (remote defaults to `origin`) and merge its captured commit into the clean current feature. Uses verified normal-merge policy; a `conflict` is automatically aborted with its paths listed, or with `keepConflicts: true` reported as `conflict_kept` and left in progress (MERGE_HEAD set, conflicted paths unmerged) for `conclude_merge`. Never rebases, pushes, or changes upstream configuration. |
+| `track_branch` | `{ "branchName": string, "remote"?: string, "remoteBranch"?: string, "worktreePath"?: string }` | Fetch one exact remote branch and create/check out a new local tracking branch. Remote defaults to `origin`; remoteBranch defaults to branchName. Requires a clean idle checkout; verifies HEAD and upstream. |
+| `update_from_base` | `{ "baseBranch": string, "remote"?: string, "keepConflicts"?: boolean, "worktreePath"?: string }` | Fetch the exact remote base (remote defaults to `origin`) and merge its captured commit into the clean current feature. Uses verified normal-merge policy; a `conflict` is automatically aborted with its paths listed, or with `keepConflicts: true` reported as `conflict_kept` and left in progress (MERGE_HEAD set, conflicted paths unmerged) for `conclude_merge`. Never rebases, pushes, or changes upstream configuration. |
 | `conclude_merge` | `{ "action": "conclude" \| "abort", "worktreePath"?: string }` | Finish or abandon the in-progress merge on the current checkout. `conclude` refuses default/custom-sized `<<<<<<<`, `|||||||`, `=======`, or `>>>>>>>` marker lines in unmerged working-tree paths and staged blobs (including CRLF and binary content, naming the paths), stages only the currently unmerged paths, rechecks the candidate index, commits with `git commit --no-edit`, and verifies MERGE_HEAD is gone and HEAD is a two-parent merge of the previous HEAD and MERGE_HEAD; unrelated unstaged changes stay unstaged. `abort` runs `git merge --abort` and verifies the restored HEAD, cleared operation state, and clean tree. Refuses when no merge is in progress. `worktreePath` (an absolute worktree root of the same repository) lets one session act on another worktree; omit it for the current one. |
 | `pull_request_files` | `{ "number": integer }` | List a pull request's first 100 changed files (path, change type, additions, deletions; the rest counted) and its current labels. Read-only. |
 | `label_pull_request` | `{ "number": integer, "labels": string[] }` | Add 1 to 5 labels that already exist in the repository to a pull request; an unknown label is refused before anything changes, existing labels stay. |
 | `reply_pull_request_feedback` | `{ "number": integer, "body": string, "threadId"?: string, "resolve"?: boolean }` | Answer PR feedback on an open, merged or closed PR of this repository (forks included). With `threadId` (from `pull_request_feedback`) it replies in that review thread after verifying the thread belongs to the PR, and `resolve: true` then resolves it; without `threadId` it posts one conversation comment after confirming the number is a pull request, not an issue. Body is Markdown, at most 4,000 characters. Never edits, deletes, approves, merges, or closes. |
-| `pull_request_feedback` | `{ "number"?: integer, "headBranch"?: string }` | Read what a same-repository PR asks to be fixed in one GraphQL request: unresolved, current review threads with their comments (resolved and outdated threads are counted only), review summaries with a body or requested changes, the latest 50 conversation comments, and the head commit's failing checks with up to 20 failure and warning annotations each (`path:line LEVEL: message`). Threads and conversation comments carry their GraphQL ids, every comment its author and time, and comments by the token's own user are marked `(you)`, so a caller can reply to a thread and tell new comments from its own replies. For up to three failing GitHub Actions jobs it adds the log lines leading to the last `##[error]`. A job log that cannot be read is reported per check. No mutations. |
-| `pull_request_status` | `{ "number"?: integer, "headBranch"?: string }` | Read exact same-repository PR lifecycle and head/base/merge identities. Number and headBranch are mutually exclusive. Without number, returns the most recently updated PR for headBranch or the current branch. Does not certify CI checks or review approvals. |
+| `pull_request_feedback` | `{ "number"?: integer, "headBranch"?: string, "worktreePath"?: string }` | Read what a same-repository PR asks to be fixed in one GraphQL request: unresolved, current review threads with their comments (resolved and outdated threads are counted only), review summaries with a body or requested changes, the latest 50 conversation comments, and the head commit's failing checks with up to 20 failure and warning annotations each (`path:line LEVEL: message`). Threads and conversation comments carry their GraphQL ids, every comment its author and time, and comments by the token's own user are marked `(you)`, so a caller can reply to a thread and tell new comments from its own replies. For up to three failing GitHub Actions jobs it adds the log lines leading to the last `##[error]`. A job log that cannot be read is reported per check. No mutations. |
+| `pull_request_status` | `{ "number"?: integer, "headBranch"?: string, "worktreePath"?: string }` | Read exact same-repository PR lifecycle and head/base/merge identities. Number and headBranch are mutually exclusive. Without number, returns the most recently updated PR for headBranch or the current branch. Does not certify CI checks or review approvals. |
 | `init_repository` | `{ "initialBranch"?: string }` | Initializes only pi's exact current working directory as a verified non-bare Git repository with an unborn branch (default `main`). Rejects existing or nested repositories and accepts no path, bare, template, shared, remote, commit, or project-file controls. |
 | `branch_status` | `{ "ancestry"?: { "sourceBranch": string, "targetBranch": string }, "worktreePath"?: 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. `worktreePath` (an absolute worktree root of the same repository) lets one session act on another worktree; omit it for the current one. |
 | `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", "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, "deleteIgnored"?: boolean, "discardChanges"?: boolean }` | Force-free removal of an explicitly selected, verified clean linked worktree. Ignored residue is refused by default; `deleteIgnored: true` explicitly deletes it and reports its top-level paths. The local branch remains at the same commit. `discardChanges: true` explicitly discards uncommitted changes and lists them in `discardedPaths`; a dirty worktree is refused without it. |
+| `remove_worktree` | `{ "worktreePath": string, "deleteIgnored"?: boolean, "discardChanges"?: boolean }` | Deletes an explicitly selected linked checkout directory but keeps its local branch at the same commit. Uncommitted changes and ignored files are refused by default. `deleteIgnored: true` permits deleting all ignored entries, including possible `.env` and `.pi/`, and reports their top-level paths; `discardChanges: true` permits discarding uncommitted changes and lists them in `discardedPaths`. Each destructive option requires explicit user authorization. |
 | `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. |
-| `land_branch` | `{ "sourceBranch": string, "targetBranch": string, "remote"?: string, "worktreePath"?: string, "pullRequestNumber"?: integer }` | Post-merge fetch, ancestry or exact merged-PR proof, linked-worktree removal including ignored residue, leased local source deletion, and independent fast-forward target sync. Default remote `origin`; omitted path finds the source's linked worktree. Returns per-step receipts. |
-| `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects staged, unstaged, or unmerged tracked changes (naming the paths), and runs `git switch <branchName>`. Untracked files such as `.env` do not block; git itself refuses a switch that would overwrite one. |
-| `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. |
+| `land_branch` | `{ "sourceBranch": string, "targetBranch": string, "remote"?: string, "worktreePath"?: string, "pullRequestNumber"?: integer }` | Cleanup after a verified merge, not a PR merge operation: fetch the target, verify ancestry or exact merged-PR evidence, remove a clean linked worktree including ignored files, delete the local source at its expected commit, and independently attempt fast-forward target sync. Never deletes remote branches. Default remote `origin`; omitted path finds the source's linked worktree. Inspect each receipt because cleanup and sync can have different outcomes. |
+| `change_branch` | `{ "branchName": string, "worktreePath"?: string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects staged, unstaged, or unmerged tracked changes (naming the paths), and runs `git switch <branchName>`. Untracked files such as `.env` do not block; git itself refuses a switch that would overwrite one. |
+| `fetch_branch` | `{ "remote"?: string, "branch"?: string, "worktreePath"?: 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` | `{ "worktreePath"?: string }` | 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` | `{ "baseRef"?: string, "worktreePath"?: string }` | Replays local commits onto cached upstream by default, or an explicitly captured local/remote-tracking/full-commit base without changing upstream. Requires history-rewrite authorization; no fetch/force-push. Explicit-base mode verifies restoration and refuses local-only ignored residue. |
 | `integrate_branch` | `{ "sourceBranch": string, "targetBranch": string, "keepConflicts"?: boolean, "worktreePath"?: 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; with `keepConflicts: true` a conflict is reported as `conflict_kept` and left in progress (MERGE_HEAD set, conflicted paths unmerged) for `conclude_merge`. It never fetches or pushes. `worktreePath` (an absolute worktree root of the same repository) lets one session act on another worktree; omit it for the current one. |
-| `create_branch` | `{ "branchName": string }` | Validates `branchName`, rejects existing local branches, and runs `git switch -c <branchName>` from current `HEAD`. |
-| `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. A branch whose upstream is a differently named `main`, `master`, `trunk`, `develop`, or origin default branch is published to its own name instead and tracks it. |
-| `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 reuses an exact matching open PR or creates one in the resolved current repository. Existing PR metadata is preserved. Omitted fields require `BRANCHME_PR_AUTOFILL=true`; branch refs must be distinct, exist locally, and cannot use `owner:branch`. |
+| `create_branch` | `{ "branchName": string, "baseRef"?: string, "worktreePath"?: string }` | Creates at current HEAD by default or an explicitly captured local/remote-tracking/full-commit base. Explicit bases require tracked-clean idle state; no fetch or inferred upstream. |
+| `push_branch` | `{ "worktreePath"?: string }` | 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. A branch whose upstream is a differently named `main`, `master`, `trunk`, `develop`, or origin default branch is published to its own name instead and tracks it. |
+| `pull_request` | `{ "headBranch"?: string, "baseBranch"?: string, "title"?: string, "body"?: string, "draft"?: boolean, "worktreePath"?: string }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then reuses an exact matching open PR or creates one in the resolved current repository. Existing PR metadata is preserved. Omitted fields require `BRANCHME_PR_AUTOFILL=true`; branch refs must be distinct, exist locally, and cannot use `owner:branch`. |
 
 `conclude_merge` supports only single-head merges and refuses multi-head merges before mutation. Its marker check also covers manually staged resolutions and clean-filter output. Marker-like lines (including Markdown setext underlines) are conservatively refused; configured marker sizes above 4,096 are refused. Git commits the **entire index**, including already-staged merge entries: do not stage unrelated edits during the merge. Unrelated unstaged edits remain outside the commit. A failed/lost commit response reports uncertain postconditions; inspect `HEAD`, `MERGE_HEAD`, and the index before retrying.
 
-All schemas reject additional properties. `fetch_remote` accepts only optional `remote` and `prune`, never arbitrary refspecs or tag/force/checkout controls. `list_branches` accepts only optional `kind` and bounded `patterns`; it remains read-only. `init_repository` accepts only optional `initialBranch`, never a path or repository-mode controls. `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` plus optional boolean `keepConflicts`; it accepts no repository, path, remote, strategy, message, squash, signing, commit, continuation, abort, force, fetch, push, deletion, or worktree controls. `conclude_merge` requires exactly `action` (`conclude` or `abort`) and accepts no path list, commit message, strategy, `--ours`/`--theirs`, or force controls. `create_worktree` requires exactly `worktreePath`, `branchName`, and `branchMode`, plus an optional read-only `baseRef` start point for `branchMode: "new"`; `remove_worktree` requires `worktreePath` and accepts optional boolean `deleteIgnored`. 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`. Generic `continue_merge` and `abort_merge` tools are not available; `conclude_merge` is the only merge-continuation surface and only commits paths whose markers are already gone.
+All schemas reject additional properties. `fetch_remote` accepts only optional `remote` and `prune`, never arbitrary refspecs or tag/force/checkout controls. `list_branches` accepts only optional `kind` and bounded `patterns`; it remains read-only. `init_repository` accepts only optional `initialBranch`, never a path or repository-mode controls. `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` accepts only an optional worktree selector; `rebase_branch` additionally accepts an explicit read-only `baseRef`. Neither accepts force, refspec, autostash, or interactive rebase controls. `integrate_branch` requires exactly `sourceBranch` and `targetBranch` plus optional boolean `keepConflicts`; it accepts no repository, path, remote, strategy, message, squash, signing, commit, continuation, abort, force, fetch, push, deletion, or worktree controls. `conclude_merge` requires exactly `action` (`conclude` or `abort`) and accepts no path list, commit message, strategy, `--ours`/`--theirs`, or force controls. `create_worktree` requires exactly `worktreePath`, `branchName`, and `branchMode`, plus an optional read-only `baseRef` start point for `branchMode: "new"`; `remove_worktree` requires `worktreePath` and accepts optional boolean `deleteIgnored`. 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`. Generic `continue_merge` and `abort_merge` tools are not available; `conclude_merge` is the only merge-continuation surface and only commits paths whose markers are already gone.
 
 ---
 
+See [shell-free workflows](docs/SHELL_FREE_WORKFLOWS.md) for history/conflict inspection, cross-worktree coordination, remote/tracking setup, index control, guarded restore/revert, and PR checks/edit/merge. Ordinary commits are never created automatically; only an explicit `commit_changes` call commits.
+
+`worktreePath` selects a verified live checkout of the same repository without changing Pi's cwd. Branch-inferred PR status/feedback reject a selector with an exact `number`. Mutating tool calls share an outer process-wide coordinator before helper root/common-directory queues; external Git processes/extensions are not locked out.
+
+### Complete file status without Bash
+
+```text
+git_status({})
+git_status({ after: "<next from the previous page>" }) // repeat filters/worktreePath if supplied
+git_status({ paths: ["src", "README.md"] })
+```
+
+`git_status` is separate from the bounded `branch_status`/automatic summary and from content-reading `git_diff`. It lists all Git-reported changed paths across pages, including staged-only paths. `total` counts matching records; `hasChanges` describes the whole checkout within scope. An empty filtered result is not a cleanliness claim. Ignored files and submodule working-tree contents are excluded; recorded gitlink changes remain visible. Git's assume-unchanged/skip-worktree policies still apply.
+
+Continuation is bound to the canonical checkout, normalized filters, HEAD, logical index entries/flags, operation state, status records, and available changed-path filesystem metadata. A stale cursor requires restarting without `after`; a checkout changing during inspection fails instead of returning a misleading page. This is observation, not a lock against external Git or file writers. Each Git response is capped at 4 MiB; exceeding that limit fails rather than claiming partial status is complete.
+
+Results include `head`, a SHA-256 logical `index` expectation, and `snapshot`. Explicit `paths` additionally request content/mode fingerprints for reusable returned files (up to 8 MiB each; no content is returned); missing files and symlinks have distinct fingerprints, while unsupported/oversized objects report no fingerprint. These identities describe observed state for guarded operations; they do not authorize mutations. Redacted, abbreviated, control-containing, invalid-encoding, or symlink-ancestor paths have `reusablePath: false` and must never be copied into mutation calls. New Git support for `--no-lazy-fetch` is required. Automatic context is unchanged.
+
 ## Workflow and Boundaries
 
+### Choosing between similar tools
+
+Tool names and parameter contracts remain stable. Short descriptions state the operation and important effects without repeating tool names or schema details. Schemas explain arguments; optional guidelines cover essential safety and sequencing. Brief prompt snippets omit the name prefix Pi adds automatically. Standalone guidelines name their tool because Pi renders them ungrouped.
+
+| Intent | Choose | Important distinction |
+| --- | --- | --- |
+| Enumerate every changed path | `git_status` | Follow `next` until complete; summary context omits paths. |
+| Show changed file contents | `git_diff` | Status metadata is not a diff; untracked file contents are excluded. |
+| Refresh observed repository status or check ancestry | `branch_status` | Reads local/cached Git state and related PR metadata; never fetches Git refs. Ancestry checks may be independent. |
+| Find branch names | `list_branches` | Cached inventory; run `fetch_remote` first when fresh remote discovery is needed. |
+| Fetch one known remote branch | `fetch_branch` | Updates its tracking ref, not the local branch or checkout. |
+| Fetch all remote branch names and heads | `fetch_remote` | Refreshes one remote's tracking namespace; pruning is opt-in and local-cache-only. |
+| Switch to an existing local branch | `change_branch` | Does not create a branch or fetch one. |
+| Create and switch to a new branch | `create_branch` | Defaults to current HEAD; optional explicit base never fetches or moves that base. |
+| Join an existing remote branch | `track_branch` | Fetches, creates a new local tracking branch, and switches; cannot configure an existing local branch. |
+| Update the current branch from its own upstream | `pull_branch` | Fetches and fast-forwards only; divergence fails. |
+| Merge a fresh remote main into the current feature | `update_from_base` | Fetches and merges; may create a merge commit, never rebases or changes upstream configuration. |
+| Merge a local source into a local target | `integrate_branch` | Target must already be checked out; never fetches. |
+| Rebase onto upstream or a chosen local base | `rebase_branch` | Rewrites local commits; no fetch or force-push, and does not change upstream. |
+| Finish or abandon an existing merge | `conclude_merge` | Resolve conflicts by editing first to conclude; commits the entire index or aborts the merge. |
+| Push existing commits on the current branch | `push_branch` | Accepts an optional worktree selector, not a caller-supplied push target; never commits. |
+| Create or reuse a matching GitHub PR | `pull_request` | Push first; does not push, merge, or edit an existing PR. |
+| Verify a PR was merged | `pull_request_status` | Lifecycle evidence, not proof that CI or review requirements passed. |
+| Read review requests and failing CI | `pull_request_feedback` | Read-only; use `reply_pull_request_feedback` to post a reply or comment. |
+| Clean up after a verified merge | `land_branch` | Deletes the local source and clean linked worktree, including ignored files; does not merge the PR. |
+| Remove only a linked checkout | `remove_worktree` | Retains its branch; destructive options require explicit authorization. |
+| Delete only a local branch | `retire_branch` | Requires an unoccupied branch and expected commit; does not remove its checkout or remote branch. |
+
+Wait for dependent calls to finish: fetch before inspecting fresh remote refs, switch before pulling, push before creating a PR, and integrate before checking its result. Independent ancestry checks do not require a preceding merge. A kept conflict must be resolved and concluded or aborted before another Git mutation.
+
+### Inspect local diffs
+
+```javascript
+git_diff({}) // unstaged: index -> working tree
+git_diff({ mode: "staged", paths: ["src", "README.md"] }) // HEAD -> index
+git_diff({ mode: "range", baseRef: "main", targetRef: "HEAD" }) // main -> HEAD
+git_diff({ mode: "range", baseRef: "origin/main", mergeBase: true, output: "stat" }) // origin/main...HEAD
+git_diff({ output: "name-status", worktreePath: "/absolute/path/to/linked-worktree" })
+```
+
+`git_diff` requires Git with `--no-lazy-fetch` support and fails closed on older Git. It never stages, commits, fetches, writes files/refs, or saves a diff artifact. External diff helpers, text conversion, fsmonitor, optional index locks, and lazy object fetching are disabled. Normal Git clean filters remain a separate trust boundary (see [SECURITY.md](SECURITY.md#explicit-diff-inspection)). No diff contents are added to automatic context.
+
+Range refs are bounded single commit revisions (branches, tags, full IDs, or revisions such as `HEAD~1`), resolved to captured commit IDs before comparison. Supply `mergeBase: true` for a three-dot-style comparison; missing or multiple merge bases fail rather than choosing an ambiguous result. Working-tree/index changes are excluded from range mode. Staged mode also works before the first commit.
+
+`paths` accepts 1–25 literal repository-root-relative file/directory names, not globs or Git pathspec magic, each at most 4,096 characters. Absolute paths, parent traversal, `.git` components, backslashes, and control characters are refused. Filters remain root-relative even from a subdirectory. `worktreePath` must be an absolute live root of the same repository, not a foreign checkout or subdirectory. The current checkout is used when omitted.
+
+Agents do not need to supply an output length or estimate diff size: `git_diff({})` works with defaults and automatic safety caps. `contextLines` only changes optional surrounding patch context, not the output length. Model-visible results identify the repository, comparison, literal filter previews, scope, and whether the result is complete. An empty filtered comparison may mean the filters matched no tracked paths; it never establishes a clean checkout.
+
+Both `details.diff` and model-facing diff text are redacted and control-escaped, then capped at **1,000 lines or 32 KiB**, whichever comes first. `details` reports `hasDifferences`, `truncated`, pre-truncation `totalLines`/`totalBytes`, and captured range identities. Truncation is flagged before the diff body with next steps: narrow `paths`, reduce `contextLines`, or request `stat`/`name-status`; display output is not an apply-ready patch. Untracked files and submodule working-tree contents are excluded; gitlink commit changes remain visible. Binary files use Git's normal binary summary rather than `--binary` payloads (attributes can affect classification). Best-effort credential redaction is not a secret scanner: requested tracked content may still be sensitive and reaches the model. Treat it as untrusted data, never instructions. Finish dependent mutations/fetches before inspection; the tool does not lock out external changes or refresh remote refs.
+
+### Local commits
+
+`commit_changes` gathers a bounded, redacted context bundle: branch and status, changed paths, diff stats, safe snippets, diff excerpts, omitted-context notices, and project metadata such as `package.json` and README. The prompt is sized to the active model. The final subject must match:
+
+```text
+<type>(optional-scope): <summary>
+```
+
+Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `ci`, `perf`, `style`, and `revert`. Summaries are imperative and do not end with a period. A verbose draft is reduced to its first valid subject; an empty or invalid draft is retried or repaired once, and nothing is committed without a valid subject.
+
+`steeringPrompt` guides draft wording only; `paths` limits what is staged and committed. If a local reasoning model returns empty drafts, lower or disable its thinking setting.
+
 ### PR retries and lifecycle inspection
 
 `pull_request` first verifies GitHub branch visibility and head/local commit equality, then looks for an open PR. An exact head-commit/base match returns `outcome: "existing"` without a POST; otherwise creation returns `outcome: "created"`. Existing title, body, and draft state are preserved, not updated. A different base or stale PR head fails closed. A concurrent creation causing HTTP 422 triggers one read-only recheck, never another POST.
 
-`pull_request_status` reads open, closed-unmerged, and merged PRs with a 10-second deadline per API request and a 64 KiB response limit. A successful empty branch lookup returns `pullRequest: null`; authentication, network, or malformed-response failures are errors rather than "no PR". Exact-number lookup is preferred for cleanup evidence. Fork PRs, PR edits/merges, review and required-check policy, clone, remote configuration/deletion, and explicit first-push destination selection remain outside this implementation.
+`pull_request_status` reads open, closed-unmerged, and merged PRs with a 10-second deadline per API request and a 64 KiB response limit. A successful empty branch lookup returns `pullRequest: null`; authentication, network, or malformed-response failures are errors rather than "no PR". Exact-number lookup is preferred for cleanup evidence. Use `pull_request_checks`, `edit_pull_request`, and `merge_pull_request` for explicit checks/metadata/host merging. Readiness does not authorize merging. Clone, fork PR creation, remote URL replacement/deletion, and caller-selected push refspecs remain outside this implementation.
 
 ### Automatic context and freshness
 
@@ -309,7 +405,7 @@ The snapshot is fresh at agent start but is not live. A fetch, branch switch, pu
 
 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.
 
-Repository paths, commit subjects, branch names, and PR titles are treated as untrusted metadata. BranchMe redacts token values, escapes control characters, quotes and bounds values before prompt insertion, and never captures diffs or file contents. Staged files contribute only to the staged count; the path list is limited to unstaged and untracked entries.
+Repository paths, commit subjects, branch names, and PR titles are treated as untrusted metadata. Automatic context redacts token values, escapes control characters, quotes and bounds values before prompt insertion, and never captures diffs or file contents. Explicit `git_diff` is the separate opt-in content inspection surface. Staged files contribute only to the staged count; the path list is limited to unstaged and untracked entries.
 
 Use BranchMe from pi prompts or automation that drives pi with explicit tool calls:
 
@@ -333,7 +429,7 @@ For a source not already reachable from the target, BranchMe runs this fixed nor
 git -c rerere.enabled=false merge --ff --no-edit --no-autostash --no-rerere-autoupdate --no-overwrite-ignore refs/heads/<sourceBranch>
 ```
 
-This policy permits a fast-forward or lets Git create a standard two-parent merge commit for divergent histories. BranchMe does not create user-authored commits, accept a merge message, or expose strategy, squash, unrelated-history, signing, force, or commit controls. Before mutation, it rejects a non-empty `branch.<targetBranch>.mergeOptions` setting because those branch-specific defaults could silently change the fixed policy. Autostash is disabled, rerere is disabled so recorded resolutions are not applied or updated, and ignored files may not be overwritten. Repository-configured hooks, custom merge drivers, clean/smudge filters, and signing policy remain active; those Git extension points may execute arbitrary local commands or network operations under the user's identity.
+This policy permits a fast-forward or lets Git create a standard two-parent merge commit for divergent histories. Integration does not create user-authored commits, accept a merge message, or expose strategy, squash, unrelated-history, signing, force, or commit controls. Before mutation, it rejects a non-empty `branch.<targetBranch>.mergeOptions` setting because those branch-specific defaults could silently change the fixed policy. Autostash is disabled, rerere is disabled so recorded resolutions are not applied or updated, and ignored files may not be overwritten. Repository-configured hooks, custom merge drivers, clean/smudge filters, and signing policy remain active; those Git extension points may execute arbitrary local commands or network operations under the user's identity.
 
 The structured status is one of:
 
@@ -470,9 +566,9 @@ BranchMe operates only on the repository where pi is running:
 - `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
 - `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.
+- `rebase_branch` requires clean state and an upstream or explicit base, disables autostash/multi-ref updates, and attempts abort on failure. Explicit-base mode verifies restoration and leaves publication outside BranchMe's force-push-free surface.
 - `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.
+- `create_branch` defaults to current `HEAD` and supports an explicit captured read-only base; it never fetches, resets that base, or infers tracking.
 - `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; 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.
@@ -481,7 +577,7 @@ BranchMe operates only on the repository where pi is running:
 - `pull_request` creates PRs only for the resolved current GitHub repository, requires resolved `headBranch` and `baseBranch` values to be distinct and exist locally, requires the GitHub `headBranch` commit to match the local branch, queues behind in-flight same-repository git mutation windows when possible, and rejects `owner:branch` head refs. Missing PR fields fail unless `BRANCHME_PR_AUTOFILL=true`.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
-BranchMe intentionally does **not** create user-authored commits, accept or generate commit messages, force checkout, stash changes, discard changes, force-push, reset, edit files directly, copy ignored/untracked files between worktrees, or delete branches during standalone `remove_worktree`. The only staging it performs is `conclude_merge` adding exactly the formerly unmerged paths of an in-progress merge. Rebase-driven rewriting occurs only through explicit `rebase_branch`; a Git-generated standard merge commit is possible through explicit `integrate_branch` or `update_from_base` for divergent histories; one exact local ref can be deleted only through explicit `retire_branch` or merged-only `land_branch` under the leased boundaries above.
+Outside `commit_changes`, BranchMe intentionally does **not** create user-authored commits or accept or generate commit messages. It never forces checkout, stash, force-push, reset, copy ignored/untracked files between worktrees, or delete branches during standalone `remove_worktree`. Explicit `stage_changes`/`unstage_changes` manage approved index entries; `restore_paths` requires a preview, fresh file expectations, and explicit discard authorization. `revert_changes` stages an inverse without committing; `conclude_merge` stages only formerly unmerged paths. Rebase-driven rewriting occurs only through explicit `rebase_branch`; a Git-generated standard merge commit is possible through explicit `integrate_branch` or `update_from_base` for divergent histories; one exact local ref can be deleted only through explicit `retire_branch` or merged-only `land_branch` under the leased boundaries above.
 
 ---
 
@@ -531,8 +627,8 @@ Ensure the token and Git credentials have permission for the branch and pull req
 | Existing worktree branch is occupied | Choose another existing local branch or remove its other linked checkout after cleaning it; BranchMe does not force multiple checkouts. |
 | Worktree removal rejected | Use `list_worktrees` and select a non-main/non-current linked worktree. Remove or preserve staged, unstaged, untracked, and unmerged files. Preserve valuable ignored files, then retry with `deleteIgnored: true` if deleting the remaining ignored residue is intended. Locked, detached, prunable/missing, bare, and foreign paths are not removable. |
 | Linked-worktree agent cannot find credentials | Pass credentials through the process environment. BranchMe does not copy repository-root `.env` or other ignored/untracked files. |
-| Dirty worktree before branch switch, pull, rebase, or integration | Commit, stash, or discard changes outside BranchMe before using `change_branch`, `pull_branch`, `rebase_branch`, or a target control worktree for `integrate_branch`. |
-| Fetch, pull, or rebase has no upstream | Configure the current branch upstream outside BranchMe, then retry the tool. |
+| Dirty worktree before branch switch, pull, rebase, or integration | Commit through the owning workflow, preserve edits, or explicitly authorize guarded `restore_paths` before using `change_branch`, `pull_branch`, `rebase_branch`, or a target control worktree for `integrate_branch`. |
+| Fetch, pull, or rebase has no upstream | Use `list_remotes` and `set_upstream` for an existing tracking ref, or publish with `push_branch`. An explicit rebase base needs no upstream. |
 | Unknown remote issue branch or stale branch listing | Run `fetch_remote` (optionally `prune: true`), wait for success, then `list_branches` with `kind: "remote-tracking"` and issue-name patterns. For reftable or unsafe symbolic destinations, inspect repository refs outside BranchMe. |
 | Pull is not a fast-forward | Run `fetch_branch`, wait for it to complete, then explicitly run `rebase_branch` if rewriting local commits is intended; otherwise reconcile outside BranchMe. |
 | Rebase fails or conflicts | `rebase_branch` automatically attempts `git rebase --abort`. Inspect repository state before continuing if automatic cleanup also fails. |
@@ -554,7 +650,12 @@ Ensure the token and Git credentials have permission for the branch and pull req
 | PR branch does not exist locally | Create or fetch/check out the local `headBranch` and `baseBranch` branches first; BranchMe does not use remote-only or cross-repository PR refs. |
 | PR branch is not visible or is stale on GitHub | Run `push_branch`, wait for it to complete, then retry `pull_request`; do not batch `push_branch` and `pull_request` in the same assistant tool call. |
 | Repository mismatch | Make `origin` and `GITHUB_REPOSITORY` refer to the same `owner/repo`. |
-| Need a user-authored commit | Use CommitMe or normal Git commands. BranchMe does not accept commit messages or create user-authored commits; `integrate_branch`, `update_from_base`, and `conclude_merge` may let Git create a standard merge commit. |
+| Need a user-authored commit | Use `commit_changes`. Other tools never accept commit messages; `integrate_branch`, `update_from_base`, and `conclude_merge` may let Git create a standard merge commit. |
+| No active model or API key for a drafted commit | Select or configure a Pi model, or pass an explicit `message` to `commit_changes action="commit"`. |
+| `confirm=true requires a UI-capable Pi mode` | Run Pi with the TUI, or omit `confirm` in non-UI mode. |
+| Commit flagged for secret files/tokens or unreadable files | In the TUI, approve only reviewed safe fixtures or placeholders. In non-UI mode, remove the file or token, make the file readable, or commit manually. |
+| Git status changed while committing | Rerun the commit so it gathers fresh context. |
+| Empty, thinking-only, length-stopped, or invalid model draft | The draft is retried or repaired once. If it still fails, reduce the change size, lower model thinking, add steering text, or use `commit_changes action="gather"` and commit with an explicit `message`. |
 | Other extensions interfere | Test with `pi --no-extensions -e .`. |
 
 ---
@@ -569,7 +670,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all twenty-five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm every tool in the canonical `BRANCHME_TOOL_NAMES` inventory is visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 

package/SECURITY.md

@@ -17,14 +17,14 @@ Implemented git mutations are limited to:
 
 - `init_repository`: `git init --no-template --initial-branch <initialBranch>` in pi's exact canonical current directory after rejecting filesystem root, an existing `.git` entry, reinitialization, and nesting inside another repository. It verifies an in-place non-bare `.git` directory, the requested unborn branch, and absence of a commit.
 - `change_branch`: `git switch <branchName>` after branch-name validation, local `refs/heads/<branchName>` verification, and clean-worktree preflight.
-- `create_branch`: `git switch -c <branchName>` from current `HEAD` after branch-name validation and existing-branch checks.
+- `create_branch`: `git switch -c <branchName>` from current `HEAD` by default, or an explicitly captured local/remote-tracking/full-commit base. Explicit bases require tracked-clean idle state and ignored-overwrite protection; no fetch or inferred upstream is performed.
 - `track_branch`: narrow fetch followed by `git switch --no-overwrite-ignore --track=direct -c <branchName> refs/remotes/<remote>/<remoteBranch>`. Requires a new local branch, clean idle checkout, direct fetched commit ref, and verified final HEAD/upstream.
 - `update_from_base`: narrow fetch followed by the fixed integration merge policy against a captured remote-base commit. Reuses verified outcomes and automatic conflict abort; with explicit `keepConflicts: true` a conflicted merge is instead verified and left in progress (MERGE_HEAD equals the captured base commit, HEAD unchanged) for `conclude_merge`. Does not rewrite published history or change upstream. Both new fetch workflows explicitly disable pruning, extra ref mappings, tags, and submodule recursion, and reject symbolic remote-tracking destinations before fetching so Git cannot dereference them into unrelated refs. Base updates compare stored upstream configuration, not whether cached upstream refs happen to resolve.
 - `conclude_merge`: on the current checkout with MERGE_HEAD present, `action: "conclude"` lists unmerged paths with `git diff --name-only --diff-filter=U -z`, refuses if `git --literal-pathspecs grep` finds a default/custom-sized conflict marker in those working-tree files or staged changed blobs (including CRLF and binary content), then runs `git --literal-pathspecs add -- <those paths>` and checks the candidate index again before `git commit --no-edit`, then verifies MERGE_HEAD is gone and HEAD is an exact two-parent merge of the previous HEAD and MERGE_HEAD on the same branch. It never uses `commit -a`, never stages other paths, accepts no message, and runs repository hooks as Git normally would. `action: "abort"` runs `git merge --abort` and verifies the same restoration as the automatic abort path. It refuses multi-head merges before mutation, honors cancellation until staging begins, and reports lost commit responses as uncertain postconditions. The commit includes the entire index, including previously staged entries; callers must not stage unrelated edits during a merge. Marker-like lines are conservatively refused, and configured marker sizes above 4,096 are rejected.
 - `fetch_remote`: atomic fetch of `+refs/heads/*:refs/remotes/<remote>/*` for one validated configured remote, with `--refmap=`, `--no-tags`, `--no-prune-tags`, `--no-recurse-submodules`, and `--no-auto-maintenance`. Explicit `--no-prune` is the default even when Git configuration enables pruning; optional `prune: true` adds `--prune` only within that remote's heads mapping. Configured extra fetch mappings, tag options, and tag-pruning settings cannot expand this scope. Rewritten tips may update cached remote-tracking refs; no local branch, tag, checkout, or upstream configuration is changed. A negative `^refs/heads/HEAD` refspec prevents writes through conventional remote HEAD aliases. Preflight rejects unsafe symbolic destinations, symlinked/malformed loose-ref namespaces, and overlapping configured remote names such as `origin` and `origin/team` so pruning cannot consume another remote's namespace. Since Git silently omits dangling symrefs from `for-each-ref`, bounded loose-ref inspection is also required, and non-files ref backends such as reftable are refused. The common-Git-directory queue serializes these fetches across linked worktrees; external processes can still race preflight. Fetch failure/cancellation is not a rollback guarantee: inspect refs before retrying.
 - `fetch_branch`: `git fetch --no-tags --no-recurse-submodules <remote> <remoteBranchRef>:<remoteTrackingRef>`. With no arguments it validates and fetches the current branch's configured upstream; with explicit `branch` and optional configured `remote` (default `origin`) it fetches that exact remote branch. The explicit destination is limited to the selected remote-tracking ref, so local branches and working-tree files are not changed.
 - `pull_branch`: `git pull --ff-only --no-rebase --no-autostash <upstreamRemote> <upstreamBranchRef>` for the clean current branch after validating its configured upstream target.
-- `rebase_branch`: `git rebase --no-autostash --no-update-refs <upstream>` for the clean current branch after validating its configured upstream target. It rewrites local commits and automatically attempts `git rebase --abort` without the cancelled caller signal if the rebase fails or is killed.
+- `rebase_branch`: `git rebase --no-autostash --no-update-refs <upstream>` by default, or an explicitly captured local base with additional no-autosquash/no-rebase-merges policy. Explicit-base mode requires clean idle state, refuses ignored local-only residue, preserves configuration/unrelated refs, and verifies abort/restoration. It rewrites local commits and automatically attempts `git rebase --abort` without the cancelled caller signal if the rebase fails or is killed.
 - `integrate_branch`: after rejecting a non-empty `branch.<targetBranch>.mergeOptions` setting, runs `git -c rerere.enabled=false merge --ff --no-edit --no-autostash --no-rerere-autoupdate --no-overwrite-ignore refs/heads/<sourceBranch>` from the verified clean control worktree, which must already have the distinct existing local `targetBranch` checked out. It uses normal merge semantics: no-op, fast-forward, or a Git-generated standard two-parent merge commit for divergent histories. Conflicts are automatically aborted with restoration verified by default; explicit `keepConflicts: true` instead returns `conflict_kept` after verifying the captured paths, unchanged target HEAD, source MERGE_HEAD, repository identity, and single-merge operation state. Use `conclude_merge` to finish after resolution or abort before any other Git mutation.
 - `push_branch`: `git push <upstreamRemote> HEAD:<upstreamBranchRef>` for the current branch when an upstream exists, or `git push --set-upstream origin <currentBranch>` when no upstream exists.
 - `create_worktree`: `git worktree add -b <branchName> <canonicalPath> <capturedCommit>` for a new local branch from current HEAD or optional read-only `baseRef`, or `git worktree add <canonicalPath> <existingLocalBranch>` for an existing unoccupied local branch, after destination and repository-boundary validation.
@@ -34,11 +34,39 @@ Implemented git mutations are limited to:
 
 Before each agent run, BranchMe also runs bounded, read-only Git commands to collect branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged or untracked path entries, and up to 5 recent commits. The same collector runs when `branch_status` explicitly refreshes context. An explicit optional `branch_status.ancestry` query captures exact local or remote-tracking source/target commit IDs and uses `git merge-base --is-ancestor` against those commits; automatic Git context never runs this query and remains unchanged. Collection does not run `fetch`, `switch`, `pull`, `rebase`, `merge`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
 
-Repository initialization creates `.git` metadata in the current directory. Branch switching, worktree creation/removal, fast-forward pulls, successful rebases, and branch integration can update or remove filesystem content as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree, and retirement deletes one verified local branch ref. Mutating operations for the same repository are serialized to avoid same-turn races; initialization uses Pi's file-mutation queue for the new `.git` entry and is serialized by its canonical target directory. `integrate_branch` holds one queue window across preflight, merge, cleanup, and final verification; `retire_branch` holds one active-worktree-keyed window across preflight, immediate reinspection, leased deletion, and postcondition verification; `pull_request` uses the queue around PR preflight and creation. This in-memory queue is process-local: it coordinates BranchMe calls using the same active checkout but does not lock a different active worktree, another Pi process, or an external Git process. Integration refs are captured and re-verified. Retirement additionally uses an expected-old-value ref lease and rechecks its captured target and complete worktree occupancy. Unexpected or inconclusive movement produces a bounded uncertain error with manual inspection guidance and no reset-based rollback.
+Repository initialization creates `.git` metadata in the current directory. Branch switching, worktree creation/removal, fast-forward pulls, successful rebases, and branch integration can update or remove filesystem content as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree, and retirement deletes one verified local branch ref. Mutating operations for the same repository are serialized to avoid same-turn races; initialization uses Pi's file-mutation queue for the new `.git` entry and is serialized by its canonical target directory. `integrate_branch` holds one queue window across preflight, merge, cleanup, and final verification; `retire_branch` holds one active-worktree-keyed window across preflight, immediate reinspection, leased deletion, and postcondition verification; `pull_request` uses the queue around PR preflight and creation. These helper-level queues are process-local; mutating tool calls additionally use an outer process-wide coordinator across linked worktrees. Other Pi processes, extensions, and external Git processes are not locked. Integration refs are captured and re-verified. Retirement additionally uses an expected-old-value ref lease and rechecks its captured target and complete worktree occupancy. Unexpected or inconclusive movement produces a bounded uncertain error with manual inspection guidance and no reset-based rollback.
 
-BranchMe rejects staged, unstaged, or unmerged tracked changes before `change_branch`, `pull_branch`, `rebase_branch`, `track_branch`, and `update_from_base`, naming the affected paths. Untracked files do not block these preflights; Git still refuses non-ignored file collisions, and tracking/base-update/landing operations also protect ignored files. Standalone `integrate_branch` still requires a fully clean control worktree, including untracked files. Standalone `remove_worktree` rejects any staged, unstaged, untracked, or unmerged entry in a linked worktree. Standalone removal protects ignored residue by default and deletes it only with explicit `deleteIgnored: true` authorization. `land_branch` also allows ignored residue to be deleted, but still refuses tracked/staged or non-ignored untracked changes. Retirement does not require an unrelated active worktree to be clean, but every registered worktree record is inspected and any occupancy of the retiring branch blocks deletion. Integration also rejects an existing merge, rebase, cherry-pick, revert, or sequencer state and any non-empty target-branch `mergeOptions` setting that could alter the fixed command policy. After merge or retirement mutation begins, cleanup/postcondition inspection ignores caller cancellation and uses bounded timeouts. A `conflict` result is returned only after exact repository-relative conflict paths are captured, `git merge --abort` succeeds, source and target refs are restored, repository/control-worktree identity is preserved, operation state is cleared, and the control worktree is clean. Failed non-conflict merges remain errors; inconclusive cleanup or verification is never reported as success. After retirement is attempted, contradictory or inconclusive repository, target-ref, retiring-ref, or occupancy state is an uncertain error stating that retirement may have completed and requiring manual inspection before retry.
+BranchMe rejects staged, unstaged, or unmerged tracked changes before `change_branch`, `pull_branch`, default upstream `rebase_branch`, `track_branch`, and `update_from_base`, naming the affected paths. Untracked files do not block these default preflights; explicit-base rebase and no-commit revert require stricter clean state and refuse ignored residue; Git still refuses non-ignored file collisions, and tracking/base-update/landing operations also protect ignored files. Standalone `integrate_branch` still requires a fully clean control worktree, including untracked files. Standalone `remove_worktree` rejects any staged, unstaged, untracked, or unmerged entry in a linked worktree. Standalone removal protects ignored residue by default and deletes it only with explicit `deleteIgnored: true` authorization. `land_branch` also allows ignored residue to be deleted, but still refuses tracked/staged or non-ignored untracked changes. Retirement does not require an unrelated active worktree to be clean, but every registered worktree record is inspected and any occupancy of the retiring branch blocks deletion. Integration also rejects an existing merge, rebase, cherry-pick, revert, or sequencer state and any non-empty target-branch `mergeOptions` setting that could alter the fixed command policy. After merge or retirement mutation begins, cleanup/postcondition inspection ignores caller cancellation and uses bounded timeouts. A `conflict` result is returned only after exact repository-relative conflict paths are captured, `git merge --abort` succeeds, source and target refs are restored, repository/control-worktree identity is preserved, operation state is cleared, and the control worktree is clean. Failed non-conflict merges remain errors; inconclusive cleanup or verification is never reported as success. After retirement is attempted, contradictory or inconclusive repository, target-ref, retiring-ref, or occupancy state is an uncertain error stating that retirement may have completed and requiring manual inspection before retry.
 
-BranchMe does not force checkout/removal, stash, create user-authored commits, accept commit messages, reset, force-push, or edit project files directly. Rebase-driven rewriting occurs only through explicit `rebase_branch`. Explicit `integrate_branch` or `update_from_base` may let Git create a standard merge commit for divergent histories, but BranchMe exposes no strategy, squash, unrelated-history, signing, force, or commit-message control and no generic `continue_merge` or `abort_merge` tool. The only staging surface is `conclude_merge`, which adds exactly the formerly unmerged paths of an in-progress merge after proving no conflict marker line remains in them. Explicit `retire_branch` and merged-only `land_branch` are the local branch-deletion surfaces. Standalone retirement has no bulk, pattern, inferred-target, remote-delete, remote-tracking-delete, automatic worktree-removal, or rollback-ref control.
+Outside `commit_changes`, BranchMe does not create user-authored commits or accept commit messages. It does not force checkout/removal, stash, reset, force-push, or expose arbitrary project-file editing. Guarded restoration below is an explicit Git-mediated file mutation. Rebase-driven rewriting occurs only through explicit `rebase_branch`. Explicit `integrate_branch` or `update_from_base` may let Git create a standard merge commit for divergent histories, but BranchMe exposes no strategy, squash, unrelated-history, signing, force, or commit-message control and no generic `continue_merge` or `abort_merge` tool. General index changes are limited to explicitly approved `stage_changes`/`unstage_changes` and no-commit `revert_changes`; `conclude_merge` still adds exactly the formerly unmerged paths after marker checks. `restore_paths` separately permits explicitly authorized replacement/deletion of selected tracked working files while preserving logical index entries; raw Git stat-cache bytes may refresh. Explicit `retire_branch` and merged-only `land_branch` are the local branch-deletion surfaces. Standalone retirement has no bulk, pattern, inferred-target, remote-delete, remote-tracking-delete, automatic worktree-removal, or rollback-ref control.
+
+## Guarded shell-free operations
+
+`git_log`, `git_show`, and `git_conflicts` are explicit read-only history/object/index-stage surfaces. Shared readers disable optional locks, lazy fetch, pagers, and fsmonitor, cap raw responses at 4 MiB, and sanitize before bounding text. History pages pin captured commit IDs; shallow history is explicitly local-only. Merge comparisons require a parent, and binary/oversized blobs are summarized. Conflict previews expose only requested stages; absent versions are explicit. These opt-in content reads never enlarge automatic context and never resolve or stage conflicts. Requested content remains potentially sensitive and untrusted despite best-effort redaction.
+
+`stage_changes`/`unstage_changes` require 1–25 exact approved paths and fresh HEAD/logical-index expectations. They refuse active operations, unmerged entries, unsupported/split/sparse/intent-to-add/assume-unchanged/skip-worktree indexes, gitlinks, directory expansion, ignored additions, and Git path environment overrides. Selected file fingerprints are rechecked; working bytes and unrelated index entries are verified unchanged. Both rename sides need approval. No commit, force-add, hunk editing, or all-files mode exists. Git clean filters remain trusted configuration and may execute arbitrary code.
+
+`commit_changes` creates local commits only and never pushes. `commit_changes action=gather` is read-only. Drafting uses only the active Pi model, with at most one retry or repair prompt; drafting diagnostics never include raw prompts, diffs, file contents, or model output. Secret files such as `.env`, `.envrc`, private keys, kubeconfigs, and credential stores are not read. Sensitive, generated, binary-looking, unreadable, oversized, and symlinked changed files are omitted from model context. Diff excerpts are collected with external diff and textconv disabled, then redacted. Before staging, commit actions rescan for known secret files, unreadable files, and high-confidence secret tokens. UI sessions must approve flagged files; non-UI sessions refuse them. Commits stop if `git status` changed after context gathering, and `paths` refuses listed paths without changes or staged changes outside the list.
+
+`restore_paths` previews selected tracked paths and applies only with explicit discard authorization, fresh HEAD/index expectations, and matching per-file fingerprints. An explicit source must be pinned to a full commit when applying. The index's staged entries stay unchanged (Git may refresh stat-cache bytes), while approved working paths can be replaced or deleted. Untracked/ignored content, symlink ancestors, unsupported index modes, and directory expansion are protected/refused. No reset/clean or automatic destructive rollback exists; a partial failure reports that selected paths may already have changed.
+
+`revert_changes` requires one contained non-merge full commit and a clean idle checkout with current expectations, and refuses ignored local-only files at the paths the commit touches (Git could overwrite them); ignored files elsewhere, such as `.env` or installed dependencies, do not block it. It uses `git revert --no-commit` with rerere disabled. Conflicts use owned `REVERT_HEAD` evidence before abort and verified restoration. A successful inverse may leave operation markers; owned state is cleared by `git revert --quit`, preserving the staged inverse without creating a commit. Unknown ownership or uncertain cleanup blocks a success claim. No generic sequencer continuation or hidden commit call exists.
+
+`list_remotes` returns bounded sanitized destination previews and a configuration fingerprint, not arbitrary config contents. Add-only `add_remote` requires an unused non-overlapping name, credential-free HTTPS/SSH destination, current config expectation, regular repository config, and no URL rewriting. `set_upstream` changes only one local branch's remote/merge keys for an existing direct remote-tracking ref or explicit unset; inherited/included/ambiguous/worktree-specific settings are refused. Config mutations are common-directory queued and verified, never change global/system config, and never fetch automatically. Failed verification reports uncertain config rather than rolling it back blindly.
+
+Mutating tool calls now have an outer process-wide coordinator before the existing helper root/common-directory queues. This serializes tool-mediated mutations across linked worktrees without taking an external filesystem lock. Direct helper callers retain their existing queue contracts. Read-only tools remain independent; callers must sequence dependent reads after mutations. No mechanism guarantees isolation from independent Git processes, extensions, or malicious filesystem writers.
+
+See [shell-free workflows](docs/SHELL_FREE_WORKFLOWS.md) for exact contracts, output limits, supported indexes, and recovery guidance.
+
+## Explicit diff inspection
+
+`git_status` explicitly reads NUL-delimited porcelain v2 status, logical index entries/flags, operation markers, and changed-path filesystem metadata, with optional same-repository `worktreePath`. Its Git calls disable optional locks, lazy fetching, pagers, and fsmonitor; no direct network request or mutation occurs. Normal Git clean filters may still execute during status comparison, so this is not a configuration sandbox. Ignored paths and submodule working-tree contents are excluded, and Git's assume-unchanged/skip-worktree policies still apply. Each raw Git response is limited to 4 MiB; pages contain at most 50 entries / 24 KiB of entry JSON. Whole-checkout changes and filtered results/completeness are distinguished. Continuation hashes bind checkout/filter/HEAD/index/operations/status/available filesystem metadata and reject detected changes, but do not lock out external writers. The logical index fingerprint covers stage entries and `ls-files -v` flags, not raw stat-cache bytes. Explicit `paths` additionally read bounded regular-file bytes or symlink targets solely to produce content/mode fingerprints (8 MiB per regular file); contents are never returned or added to automatic context. Symlink ancestors, unsafe/invalid-encoding, redacted, and abbreviated paths are non-reusable. Filesystem reads verify observed identities before/after but cannot provide isolation from a malicious concurrent filesystem writer. All text/details are sanitized before bounding, and no raw paths are hidden in continuation tokens.
+
+`git_diff` is an explicit content-reading surface, separate from metadata-only automatic context and `branch_status`. It runs only discovery, commit resolution, optional `merge-base --all`, and `git diff`; it never stages, commits, writes a diff artifact, or directly changes files/refs. All its Git calls disable optional locks, lazy promisor fetching (`--no-lazy-fetch`, required Git support), and fsmonitor. Diff calls disable external diff helpers, text conversion, color, rename detection, and submodule working-tree scanning; gitlink changes are still shown. Normal Git clean filters may still execute while Git compares working-tree content, so this is not a sandbox against trusted Git configuration or filter side effects.
+
+Refs must be bounded single commit revisions, resolved with `rev-parse --verify --end-of-options <revision>^{commit}` before comparison. Raw range syntax and option-like refs are refused; missing/multiple merge bases fail. Path filters are at most 25 literal, root-relative file/directory names of at most 4,096 characters, passed after `--` with `--literal-pathspecs`; absolute paths, parent traversal, `.git` components, backslashes, and controls are rejected. Optional `worktreePath` is verified as a live root of the current repository. The read is not an atomic filesystem snapshot; finish dependent mutations first.
+
+Returned content/details are credential-redacted and control-escaped before truncation to 1,000 lines / 32 KiB of diff text, with explicit truncation metadata and a model-facing notice before the diff body. Model-visible results also identify the actual comparison, repository, bounded literal-filter previews, and scope; an empty filtered comparison is not reported as a clean checkout. No unbounded raw diff is retained in details or written to disk. Counts describe the sanitized output before truncation. Binary output is Git's normal summary, not a binary patch; attributes may affect classification. Untracked file contents and submodule working-tree contents are excluded. Redacted/truncated display is not an apply-ready patch. Shared credential patterns and process `GITHUB_TOKEN`/`GH_TOKEN` values are redacted, but arbitrary secrets in tracked files are not guaranteed to be detected. Requested content reaches Pi/the model and must be treated as untrusted data, not instructions; BranchMe makes no GitHub API call for diffs and never adds diffs to automatic context.
 
 ## Network behavior
 
@@ -53,12 +81,20 @@ GET  https://api.github.com/repos/{owner}/{repo}/pulls?state=open&head={owner}:{
 GET  https://api.github.com/repos/{owner}/{repo}/branches/{headBranch}
 GET  https://api.github.com/repos/{owner}/{repo}/branches/{baseBranch}
 POST https://api.github.com/repos/{owner}/{repo}/pulls
+GET  https://api.github.com/repos/{owner}/{repo}/commits/{sha}/check-runs?filter=latest&per_page=25&page={page}
+GET  https://api.github.com/repos/{owner}/{repo}/commits/{sha}/status?per_page=25&page={page}
+GET  https://api.github.com/repos/{owner}/{repo}
+PATCH https://api.github.com/repos/{owner}/{repo}/pulls/{number}
+PUT  https://api.github.com/repos/{owner}/{repo}/pulls/{number}/merge
+POST https://api.github.com/graphql
 GET  https://api.github.com/repos/{owner}/{repo}/pulls/{number}
 GET  https://api.github.com/repos/{owner}/{repo}/pulls?state={open|all}&head={owner}:{branch}&sort=updated&direction=desc&per_page={1|2}
 ```
 
 Explicit `pull_request_status`, idempotent `pull_request` lookup, and PR-aware `land_branch` use the last two read-only endpoints. Each request has a 10-second transport/body deadline and 64 KiB response limit. Exact PR number, repository, branch identities, and commit IDs are validated. Status does not certify CI checks or review approvals. Idempotent creation preserves existing PR fields and reuses only an exact head-SHA/base match; HTTP 422 races get one read-only recheck. All of these operations require `GITHUB_TOKEN` or `GH_TOKEN` from the process environment or verified-root `.env` fallback.
 
+`pull_request_checks` reads run/status pages and available host mergeability/review/rollup state for an exact head; partial pages, permission failures, missing policy, no checks, and moved heads never imply approval. `edit_pull_request` updates only supplied title/body/draft fields of an open PR, verifies preservation of omitted fields, and reconciles ambiguous writes by reads. `merge_pull_request` requires explicit authorization, expected head SHA, an enabled selected method, known CLEAN/MERGEABLE host state, and no known outstanding review/check blocker. It submits only `sha` and `merge_method`; no admin/bypass, auto-merge, branch deletion, local merge, push, or cleanup is exposed. GitHub enforces protections. The endpoint leases HEAD but cannot atomically lease base SHA: head/base/state are rechecked before the write and merged identities afterward. Lost responses trigger read-only reconciliation, not a second blind merge. New requests reject redirects, bound transport/body to 10 seconds/64 KiB, and use existing repository/token resolution. Readiness metadata is not merge authorization.
+
 `list_branches` is an explicit read-only local inventory, limited to 200 returned refs, 128 KiB raw ref output, and 4,000 characters of text. Optional `kind` selects local or remote-tracking refs; optional `patterns` accepts 1–25 nonblank, control-free Git branch-list glob patterns of at most 512 characters, matched before output limits and display redaction. Patterns are argv values after `--`, never shell code or refspecs. Paths and names are display-safe metadata, not executable handoffs. Upstream counts reflect cached refs, not a fresh remote fetch; call `fetch_remote` separately when fresh discovery is needed.
 
 The first request is an automatic network boundary: it can run before each agent run and whenever `branch_status` explicitly refreshes context. It is a bounded, read-only lookup for one open pull request whose head is the current local branch (`per_page=1`), with a default 4-second timeout and a 64 KiB response-body limit. It is skipped when repository/branch resolution or authentication is unavailable, so BranchMe never makes an unauthenticated fallback request. Timeout, HTTP, network, malformed, and oversized-response failures become a safe unavailable state without exposing response bodies or raw network errors. Git alone is not used or claimed to provide PR metadata.
@@ -71,16 +107,16 @@ The branch preflight requests have no body. BranchMe uses the resolved `headBran
 
 - `init_repository` accepts only optional `initialBranch` (default `main`), never a path. It rejects existing and nested repositories and exposes no bare, separate-Git-dir, template, shared, remote, commit, README, `.gitignore`, or configuration controls. Ambient Git repository/object/index path and discovery overrides are refused before execution and rechecked inside the mutation queue. Ancestor `.git` entries block initialization even when Git discovery fails; only an explicit Git non-repository diagnostic permits initialization. Unrecognized or localized discovery failures fail closed. Failed postcondition verification reports partial-state inspection guidance and performs no cleanup.
 - The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
-- Except for `land_branch`'s optional absolute cleanup path, repository initialization, branch, and PR tools never accept filesystem paths. They reject `owner`, `repo`, and owner-prefixed `owner:branch` PR refs. Worktree mutations accept only an explicitly approved absolute `worktreePath`, with `branchName` and `branchMode` additionally required for creation.
+- `git_status` accepts literal root-relative status filters and an optional verified same-repository worktree selector; it never stages or changes files/refs. `git_diff` accepts literal root-relative content filters and an optional verified same-repository `worktreePath`; `branch_status`, `integrate_branch`, and `conclude_merge` also accept that worktree selector. History/conflict and guarded index/restore/revert tools support the same selector. Branch-dependent create/change/track/fetch/pull/rebase/push/base-update/PR tools also support it; branch-inferred PR status/feedback reject it with an exact number. Initialization still accepts no path. Literal content/index paths are repository-root-relative, not arbitrary filesystem targets. They reject `owner`, `repo`, and owner-prefixed `owner:branch` PR refs. Worktree mutations accept only an explicitly approved absolute `worktreePath`, with `branchName` and `branchMode` additionally required for creation.
 - `list_worktrees` is read-only and returns a bounded inventory collected from `git worktree list --porcelain -z`; automatic Git context remains focused on the active worktree.
 - `create_worktree` requires `worktreePath`, `branchName`, and `branchMode` (`new` or `existing`), with optional read-only `baseRef` in new mode. New mode uses current `HEAD` or an exact local/remote-tracking ref or full commit; existing mode requires an existing local branch not checked out elsewhere and does not infer remote branches.
 - `remove_worktree` requires `worktreePath`, accepts optional boolean `deleteIgnored`, requires an exact canonical match in a fresh current-repository inventory, removes no branch, and does not accept force.
 - `retire_branch` accepts exactly `branchName`, a full 40- or 64-hex-character `expectedHead`, a distinct exact local `targetBranch`, and boolean `force`. Both names must resolve to direct local refs. Paths, repositories, remotes, remote-only or full refs, refspecs, patterns, arrays, inferred targets, worktree controls, and bulk deletion are rejected.
-- `change_branch` accepts only `branchName` and never creates branches, checks out remote branches, forces, stashes, or discards changes.
+- `change_branch` accepts `branchName` and an optional verified worktree selector and never creates branches, checks out remote branches, forces, stashes, or discards changes.
 - `fetch_remote` accepts only optional configured `remote` and boolean `prune`, not URLs, arbitrary refspecs, force, tag, or checkout controls. Only explicit `prune: true` deletes stale remote-tracking branch refs; local branches, tags, and other remotes remain untouched.
 - `fetch_branch` accepts optional `branch` and `remote` (remote requires branch), otherwise resolves the current branch's configured upstream. It constructs the source-to-remote-tracking refspec internally and disables tag fetching and submodule recursion; no arbitrary refspec or prune controls are exposed.
-- `pull_branch` accepts no parameters, updates only the clean current branch from its configured upstream, and uses fast-forward-only semantics.
-- `rebase_branch` accepts no parameters, rebases only the clean current branch onto its configured upstream, disables autostash and multi-ref updates, never pushes, and attempts to abort on failure.
+- `pull_branch` accepts only an optional worktree selector, updates only the clean current branch from its configured upstream, and uses fast-forward-only semantics.
+- `rebase_branch` accepts optional `baseRef` and a verified worktree selector, rebases the selected clean branch onto a configured upstream or captured explicit local base, disables autostash and multi-ref updates, never pushes, and attempts to abort on failure.
 - `integrate_branch` requires exactly `sourceBranch` and `targetBranch`, plus optional boolean `keepConflicts` (default `false`). Both must be distinct existing local refs in the current repository, and the active clean control worktree must already be on the target. Remote-only refs, full refs, commit IDs, paths, repository/remotes, owner-prefixed refs, and merge controls are rejected. A source branch may be checked out in another dirty linked worktree because only its captured committed ref is read.
 - Targeted `branch_status.ancestry` accepts a nested object containing two exact local branch or remote-tracking names; it is read-only, must run after integration completes, and must not share the same parallel tool batch.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, PR creation and related-PR lookup fail closed.