claude-dev-env 2.7.1 → 2.8.0

package/skills/e-code-review/reference/medium.md

@@ -9,8 +9,15 @@ Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
 if there's no upstream) to get the unified diff under review. If there are
 uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
 include the working-tree changes in scope — the review often runs before the
-commit. If a PR number, branch name, or file path was passed as an argument,
-review that target instead. Treat this diff as the review scope.
+commit. If a target was passed as an argument, review that target instead. A
+target names one or more items, each a PR number, a branch name, a file path, or
+`default-range` — the diff this phase gathers when no target is passed — and it
+may mix those forms. A loop round widens a target by adding a path to whatever
+it started as, and it names `default-range` as an item whenever the round it
+widened was given no target argument, so the original scope stays under review.
+When a target names more than one item, gather each item's diff and take their
+union — a shared hunk counted once, an empty one adding nothing — as the
+target's diff. Treat this diff as the review scope.
 
 ## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
 
@@ -116,23 +123,41 @@ Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
 
 Report this review's results — `{level, findings}` — through the structured
 findings-report call: the mechanism that renders a review's results as a typed
-list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
-`summary`, `short_summary` — the claim compressed to ≤60 characters, no
-rationale or consequence clause — `failure_scenario`, and `category` — a short
-kebab-case slug for the angle that produced it (`correctness`,
-`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
-specific slug like `test-coverage` when one fits better) — plus `verdict` when
-a verify pass produced one. If nothing survives verification, make that call
-with an empty array. Do not also print the findings as text, and do not create
-or publish an artifact of the review — the structured call is the report.
+list in the host UI, ranked most-severe first. Each **retained** entry carries
+every field below. Drop REFUTED candidates before this report; do not emit a
+finding that lacks `severity` or `verdict`.
+
+| Field | Required | Value |
+|---|---|---|
+| `file` | yes | path under review |
+| `line` | yes | 1-based line number |
+| `summary` | yes | full claim |
+| `short_summary` | yes | claim compressed to ≤60 characters, no rationale or consequence clause |
+| `failure_scenario` | yes | concrete trigger and wrong outcome, or concrete cost for cleanup |
+| `category` | yes | short kebab-case slug for the angle (`correctness`, `simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a tighter slug like `test-coverage`) |
+| `severity` | yes | one of `blocker`, `high`, `medium`, `low`, `nit` |
+| `verdict` | yes | `CONFIRMED` or `PLAUSIBLE` from Phase 2 |
+
+**Severity rules.** Assign exactly one token from the frozen set above. Use
+`nit` only when all five hold: the change is localized clarity, formatting, or
+a typo; correctness, security, data, and API behavior stay identical; test
+coverage and operability stay identical; dependencies and rollout stay
+identical; the fix is mechanical and bounded. Any other retained finding is
+`low` or higher. Correctness bugs outrank cleanup, altitude, and conventions.
+
+If nothing survives verification, make that call with an empty array. Do not
+also print the findings as text, and do not create or publish an artifact of
+the review — the structured call is the report.
 
 ## Applying fixes (--fix)
 
-The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
-skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
-it governs which agent applies each fix, how a fix gets committed, how a skip
-is logged, and how outcomes get reported. Do not repeat the findings as text;
-follow that document's reporting rules once fixes land.
+The `--fix` flag was passed. Follow `reference\fix.md` (relative
+to this skill's folder) for the exact fix, code-rules-gate, and skip-handling
+behavior — it governs which agent applies each fix, how the code-rules gate
+runs, how a skip is logged, and how outcomes get reported. Do not repeat the
+findings as text; follow that document's reporting rules once fixes land.
+
+When `loop` is also set, skip this section.
 
 ## If findings are fixed later
 
@@ -146,8 +171,17 @@ summary; the host UI's per-finding status updates only from that call.
 ## Looping (`loop`)
 
 The `loop` arg was passed. Follow `reference\loop.md` (relative to this
-skill's folder) for how to re-run Phases 0–2, Output, and (if `--fix` is also
-present) `reference\fix.md`'s fix pass, repeatedly — including its exit
-condition, iteration cap, and re-invocation rules. Do not treat a single pass
-through this document as complete while `loop` is active; hand control to that
-document instead of stopping at Output.
+skill's folder) for how to re-run Phases 0–2 and Output repeatedly — including
+its exit condition and re-invocation rules. Schedule no fix pass of your own
+here: when `--fix` is also present, `reference\loop.md`'s gate sequence owns the
+round's fixing and loads `reference\fix.md` for the mechanics. Do not treat a
+single pass through this document as complete while `loop` is active; hand
+control to that document, and do not stop at Output.
+
+That hand-off applies when this document is entered directly. When a loop round
+is already running and has handed this document its target, the round owns the
+loop: end at Output with the findings report and return those findings to
+`reference\loop.md`'s gate sequence, rather than handing control to that
+document again from here.
+
+When `loop` was not passed, skip this section.

package/skills/e-code-review/reference/xhigh.md

@@ -10,8 +10,15 @@ Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
 if there's no upstream) to get the unified diff under review. If there are
 uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
 include the working-tree changes in scope — the review often runs before the
-commit. If a PR number, branch name, or file path was passed as an argument,
-review that target instead. Treat this diff as the review scope.
+commit. If a target was passed as an argument, review that target instead. A
+target names one or more items, each a PR number, a branch name, a file path, or
+`default-range` — the diff this phase gathers when no target is passed — and it
+may mix those forms. A loop round widens a target by adding a path to whatever
+it started as, and it names `default-range` as an item whenever the round it
+widened was given no target argument, so the original scope stays under review.
+When a target names more than one item, gather each item's diff and take their
+union — a shared hunk counted once, an empty one adding nothing — as the
+target's diff. Treat this diff as the review scope.
 
 ## Phase 1 — Find candidates (5 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
 
@@ -157,11 +164,13 @@ or publish an artifact of the review — the structured call is the report.
 
 ## Applying fixes (--fix)
 
-The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
-skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
-it governs which agent applies each fix, how a fix gets committed, how a skip
-is logged, and how outcomes get reported. Do not repeat the findings as text;
-follow that document's reporting rules once fixes land.
+The `--fix` flag was passed. Follow `reference\fix.md` (relative
+to this skill's folder) for the exact fix, code-rules-gate, and skip-handling
+behavior — it governs which agent applies each fix, how the code-rules gate
+runs, how a skip is logged, and how outcomes get reported. Do not repeat the
+findings as text; follow that document's reporting rules once fixes land.
+
+When `loop` is also set, skip this section.
 
 ## If findings are fixed later
 
@@ -175,8 +184,17 @@ summary; the host UI's per-finding status updates only from that call.
 ## Looping (`loop`)
 
 The `loop` arg was passed. Follow `reference\loop.md` (relative to this
-skill's folder) for how to re-run Phases 0–3, Output, and (if `--fix` is also
-present) `reference\fix.md`'s fix pass, repeatedly — including its exit
-condition, iteration cap, and re-invocation rules. Do not treat a single pass
-through this document as complete while `loop` is active; hand control to that
-document instead of stopping at Output.
+skill's folder) for how to re-run Phases 0–3 and Output repeatedly — including
+its exit condition and re-invocation rules. Schedule no fix pass of your own
+here: when `--fix` is also present, `reference\loop.md`'s gate sequence owns the
+round's fixing and loads `reference\fix.md` for the mechanics. Do not treat a
+single pass through this document as complete while `loop` is active; hand
+control to that document, and do not stop at Output.
+
+That hand-off applies when this document is entered directly. When a loop round
+is already running and has handed this document its target, the round owns the
+loop: end at Output with the findings report and return those findings to
+`reference\loop.md`'s gate sequence, rather than handing control to that
+document again from here.
+
+When `loop` was not passed, skip this section.

package/skills/fresh-branch/CLAUDE.md

@@ -1,14 +1,14 @@
 # fresh-branch
 
-Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Does not push, open a PR, or run `checkout -b` in the caller tree.
+Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under a configured root. Default: `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Optional absolute `--worktree-root` relocates the root (agent and branch still nest under it). Relative roots and path escape fail closed. Does not push, open a PR, or run `checkout -b` in the caller tree.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Phases, checklist, execute-vs-read for the CLI, gotchas |
-| `scripts/create_fresh_branch.py` | Deterministic CLI: fetch base, `git worktree add -b`, JSON stdout |
+| `SKILL.md` | Phases, checklist, configured-root contract, execute-vs-read for the CLI, gotchas |
+| `scripts/create_fresh_branch.py` | Deterministic CLI: resolve configured root (fail closed before fetch), fetch base, `git worktree add -b`, JSON stdout |
 | `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
-| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos (default root, explicit root, escape, collisions) |
 | `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
-| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |
+| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for CLI flags and error strings |

package/skills/fresh-branch/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: fresh-branch
 description: >-
-  Fresh git branch from origin/main in an isolated worktree under the repo's .claude/worktrees/ (never checkout -b in the caller tree).
+  Fresh git branch from origin/main in an isolated worktree under a configured root (default: <repo>/.claude/worktrees/<agent>/; never checkout -b in the caller tree).
   Triggers: fresh branch, new branch from main, /fresh-branch, start fresh, clean branch off main,
   worktree branch, branch in temp.
 ---
 
 # fresh-branch
 
-Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under the repository's `.claude/worktrees/<agent>/` root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
+Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under a **configured isolated root**. Default root is the repository's `.claude/worktrees/`; pass `--worktree-root` for an absolute alternate root (including outside the repo). Every worktree path must resolve under that root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
 
 **Announce at start:** "Creating a fresh branch from origin/main."
 
@@ -62,15 +62,21 @@ Optional flags:
 | Flag | Role |
 |------|------|
 | `--repo <path>` | Source repo (default: current directory) |
-| `--agent <slug>` | Worktree-root segment: `claude`, `grok`, `cursor`, `codex`, … |
+| `--agent <slug>` | Agent segment under the configured root: `claude`, `grok`, `cursor`, `codex`, … |
 | `--base <ref>` | Base ref (default: `origin/main`) |
+| `--worktree-root <abs-path>` | Absolute isolated root for all worktrees (default: `<repo-root>/.claude/worktrees`) |
 
 Agent resolution inside the script: `--agent` → `FRESH_BRANCH_AGENT` env → host markers → `claude`.
 
-Worktree path:
+Configured-root contract:
 
-- `<repo-root>/.claude/worktrees/<agent>/<branch-name>`, on every platform
+- Default configured root: `<repo-root>/.claude/worktrees`
+- Explicit `--worktree-root` must be absolute; a relative value fails closed with a deterministic error before any git fetch
+- Absolute roots outside the repository are legal; the agent and branch still nest under that root
+- Worktree path: `<configured-root>/<agent>/<branch-name>`, on every platform
+- Every allocated path must resolve under the configured root; traversal that escapes fails closed
 - If the path exists, the script suffixes `-2`, `-3`, …
+- Permission-rule cleanup (`stale_worktree_rule_sweep`) only walks `~/.claude/worktrees`; external `--worktree-root` trees are outside that sweep until a follow-up ships
 
 On exit 0, stdout is one JSON object:
 
@@ -100,10 +106,12 @@ Further edits for the new branch belong in `worktree_path`, not in the caller's
 
 ## Gotchas
 
-- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `<repo-root>/.claude/worktrees/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
+- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `<configured-root>/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
 - **Caller HEAD must stay put.** After success, the original repo's checked-out branch and dirty files are unchanged; only the new worktree has the new branch.
 - **Branch name collision.** If the branch already exists, the script exits non-zero with `{"error":...}`. Pick a new name; do not delete remote branches unless the user asks.
 - **Path already occupied.** A leftover folder at the preferred worktree path gets a numeric suffix (`-2`, …); report the path from JSON, not the path you assumed.
+- **Relative `--worktree-root` is refused before fetch.** Only an absolute path is accepted; the default root applies when the flag is omitted. Validation runs before `git fetch`, so a bad root never touches the network or remote-tracking refs.
+- **External roots and stale permission rules.** `stale_worktree_rule_sweep` only walks `~/.claude/worktrees`. Edit rules granted under an external `--worktree-root` are not swept when that tree is deleted.
 
 ## File index
 

package/skills/fresh-branch/scripts/create_fresh_branch.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create a fresh branch in an isolated git worktree under the repository.
+"""Create a fresh branch in an isolated git worktree under a configured root.
 
 ::
 
@@ -9,8 +9,9 @@
 
 Never runs ``git checkout -b`` in the caller's working tree. Fetches the base
 ref, then ``git worktree add -b --no-track`` into
-``<repo-root>/.claude/worktrees/<agent>/<branch>``. Exit 0 prints success JSON;
-any failure prints ``{"error": ...}`` and exits non-zero.
+``<configured-root>/<agent>/<branch>`` (default configured root:
+``<repo-root>/.claude/worktrees``). Exit 0 prints success JSON; any failure
+prints ``{"error": ...}`` and exits non-zero.
 """
 
 from __future__ import annotations
@@ -33,6 +34,8 @@ from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     AGENT_SLUG_PATTERN,
     ALL_AGENT_DETECTION_MARKERS,
     ALL_REPOSITORY_WORKTREE_ROOT_PARTS,
+    CLI_FLAG_WORKTREE_ROOT,
+    CLI_HELP_WORKTREE_ROOT,
     DEFAULT_AGENT_SLUG,
     DEFAULT_BASE_REF,
     ERROR_AGENT_SLUG_INVALID,
@@ -41,6 +44,7 @@ from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     ERROR_CLI_ARGUMENTS,
     ERROR_UNIQUE_PATH_EXHAUSTED,
     ERROR_WORKTREE_PATH_OUTSIDE_ROOT,
+    ERROR_WORKTREE_ROOT_NOT_ABSOLUTE,
     EXIT_CODE_FAILURE,
     EXIT_CODE_SUCCESS,
     FRESH_BRANCH_AGENT_ENV_VAR,
@@ -91,26 +95,79 @@ def _detect_agent_slug_from_environment() -> str:
     return DEFAULT_AGENT_SLUG
 
 
-def resolve_agent_worktree_root(repo_root: Path, agent_slug: str) -> Path:
-    """Return the repository's per-agent worktree root.
+def resolve_configured_worktree_root(
+    repo_root: Path,
+    maybe_worktree_root: str | None = None,
+) -> Path:
+    """Return the isolated root that every worktree path must stay under.
+
+    ::
+
+        resolve_configured_worktree_root(Path("/srv/app"))
+        # ok: /srv/app/.claude/worktrees
+        resolve_configured_worktree_root(Path("/srv/app"), "/tmp/isolated")
+        # ok: /tmp/isolated
+        resolve_configured_worktree_root(Path("/srv/app"), "relative/path")
+        # flag: ValueError --worktree-root must be an absolute path
+
+    When ``maybe_worktree_root`` is omitted, the default root is the repository's
+    ``.claude/worktrees`` directory. An explicit root must be absolute; it may
+    sit outside the repository.
+
+    Args:
+        repo_root: Absolute path of the repository the branch comes from.
+        maybe_worktree_root: Optional absolute configured root, or None.
+
+    Returns:
+        Resolved absolute configured root directory.
+
+    Raises:
+        ValueError: When ``maybe_worktree_root`` is set and is not absolute.
+    """
+    if maybe_worktree_root is None:
+        return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS).resolve()
+    cleaned_worktree_root = maybe_worktree_root.strip()
+    if not cleaned_worktree_root:
+        return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS).resolve()
+    configured_root = Path(cleaned_worktree_root)
+    if not configured_root.is_absolute():
+        raise ValueError(ERROR_WORKTREE_ROOT_NOT_ABSOLUTE)
+    return configured_root.resolve()
+
+
+def resolve_agent_worktree_root(
+    repo_root: Path,
+    agent_slug: str,
+    maybe_worktree_root: str | None = None,
+) -> Path:
+    """Return the per-agent directory under the configured worktree root.
 
     ::
 
         # repo_root=/srv/app, agent_slug=grok
         resolve_agent_worktree_root(Path("/srv/app"), "grok")
         # -> /srv/app/.claude/worktrees/grok
+        resolve_agent_worktree_root(
+            Path("/srv/app"), "grok", maybe_worktree_root="/tmp/isolated",
+        )
+        # -> /tmp/isolated/grok
 
-    Every worktree sits under the repository it branches from, so a worktree
-    travels with its repository and each agent keeps its own subdirectory.
+    Each agent keeps its own subdirectory under the configured root so concurrent
+    hosts do not share worktree folders.
 
     Args:
         repo_root: Absolute path of the repository the branch comes from.
         agent_slug: Short host label (one path segment).
+        maybe_worktree_root: Optional absolute configured root, or None.
 
     Returns:
         Directory that should hold per-branch worktree folders.
     """
-    return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS, agent_slug)
+    configured_root = resolve_configured_worktree_root(
+        repo_root,
+        maybe_worktree_root=maybe_worktree_root,
+    )
+    return configured_root / agent_slug
 
 
 def resolve_unique_worktree_path(preferred_path: Path) -> Path:
@@ -170,38 +227,55 @@ def create_fresh_branch(
     repo_path: Path,
     agent_slug: str,
     base_ref: str,
+    maybe_worktree_root: str | None = None,
 ) -> dict[str, str]:
     """Fetch base_ref and create an isolated worktree branch with no upstream.
 
     ::
 
         create_fresh_branch("fix/x", Path("."), "grok", "origin/main")
+        # worktree under <repo>/.claude/worktrees/grok/fix/x
+        create_fresh_branch(
+            "fix/x", Path("."), "grok", "origin/main",
+            maybe_worktree_root="/tmp/isolated",
+        )
+        # worktree under /tmp/isolated/grok/fix/x
 
-    The caller's working tree is never checked out. The worktree lands under
-    the repository's ``.claude/worktrees/<agent>/<branch>``, suffixed ``-2``,
-    ``-3``, … when that path is already taken.
+    The caller's working tree is never checked out. The configured root is
+    validated before any git fetch so a relative ``--worktree-root`` fails
+    closed with no network I/O. The worktree lands under
+    ``<configured-root>/<agent>/<branch>``, suffixed ``-2``, ``-3``, … when
+    that path is already taken. Every allocated path must resolve beneath the
+    configured root.
 
     Args:
         branch_name: Branch to create; must be a safe relative path.
         repo_path: Any path inside the repository the branch comes from.
         agent_slug: Short host label naming the worktree-root subdirectory.
         base_ref: Ref the branch starts from, such as ``origin/main``.
+        maybe_worktree_root: Optional absolute configured root, or None for
+            the default ``<repo>/.claude/worktrees``.
 
     Returns:
         The success payload: branch, worktree_path, base_ref, base_commit,
         agent, and repo_root.
 
     Raises:
-        ValueError: When the branch name or the agent slug is unsafe.
+        ValueError: When the branch name, agent slug, or worktree root is unsafe.
         RuntimeError: When git refuses the fetch or the worktree add.
     """
     cleaned_branch = _require_safe_branch_name(branch_name)
     normalized_agent_slug = _normalize_agent_slug(agent_slug)
-    resolved_base_ref, repo_root, base_commit = _resolve_branch_base(
-        repo_path, base_ref,
+    repo_root = resolve_repo_root(repo_path)
+    configured_root = resolve_configured_worktree_root(
+        repo_root,
+        maybe_worktree_root=maybe_worktree_root,
     )
+    resolved_base_ref, base_commit = _fetch_resolved_base(repo_root, base_ref)
     worktree_path = _allocate_worktree_path(
-        cleaned_branch, normalized_agent_slug, repo_root,
+        cleaned_branch,
+        normalized_agent_slug,
+        configured_root,
     )
     create_worktree_branch(
         repo_root,
@@ -215,15 +289,11 @@ def create_fresh_branch(
     )
 
 
-def _resolve_branch_base(
-    repo_path: Path,
-    base_ref: str,
-) -> tuple[str, Path, str]:
+def _fetch_resolved_base(repo_root: Path, base_ref: str) -> tuple[str, str]:
     resolved_base_ref = normalize_base_ref(base_ref)
-    repo_root = resolve_repo_root(repo_path)
     fetch_base_ref(repo_root, resolved_base_ref)
     base_commit = resolve_base_commit(repo_root, resolved_base_ref)
-    return resolved_base_ref, repo_root, base_commit
+    return resolved_base_ref, base_commit
 
 
 def main() -> int:
@@ -233,14 +303,7 @@ def main() -> int:
         Process exit code (0 success, 1 failure).
     """
     try:
-        parsed_arguments = _parse_arguments()
-        agent_slug = resolve_agent_slug(parsed_arguments.agent)
-        success_payload = create_fresh_branch(
-            branch_name=parsed_arguments.branch_name,
-            repo_path=Path(parsed_arguments.repo).resolve(),
-            agent_slug=agent_slug,
-            base_ref=parsed_arguments.base,
-        )
+        success_payload = _create_fresh_branch_from_cli_arguments()
         print(json.dumps(success_payload))
         return EXIT_CODE_SUCCESS
     except (ValueError, RuntimeError, OSError) as error:
@@ -248,6 +311,18 @@ def main() -> int:
         return EXIT_CODE_FAILURE
 
 
+def _create_fresh_branch_from_cli_arguments() -> dict[str, str]:
+    parsed_arguments = _parse_arguments()
+    agent_slug = resolve_agent_slug(parsed_arguments.agent)
+    return create_fresh_branch(
+        branch_name=parsed_arguments.branch_name,
+        repo_path=Path(parsed_arguments.repo).resolve(),
+        agent_slug=agent_slug,
+        base_ref=parsed_arguments.base,
+        maybe_worktree_root=parsed_arguments.worktree_root,
+    )
+
+
 def _require_safe_branch_name(branch_name: str) -> str:
     cleaned_branch = branch_name.strip()
     if not cleaned_branch:
@@ -257,19 +332,21 @@ def _require_safe_branch_name(branch_name: str) -> str:
 
 
 def _allocate_worktree_path(
-    branch_name: str, agent_slug: str, repo_root: Path,
+    branch_name: str,
+    agent_slug: str,
+    configured_root: Path,
 ) -> Path:
-    agent_worktree_root = resolve_agent_worktree_root(repo_root, agent_slug)
+    agent_worktree_root = configured_root / agent_slug
     agent_worktree_root.mkdir(parents=True, exist_ok=True)
     preferred_path = agent_worktree_root / branch_name
-    _assert_path_is_under_agent_root(
+    _assert_path_is_under_configured_root(
         candidate_path=preferred_path,
-        agent_worktree_root=agent_worktree_root,
+        configured_root=configured_root,
     )
     worktree_path = resolve_unique_worktree_path(preferred_path)
-    _assert_path_is_under_agent_root(
+    _assert_path_is_under_configured_root(
         candidate_path=worktree_path,
-        agent_worktree_root=agent_worktree_root,
+        configured_root=configured_root,
     )
     return worktree_path
 
@@ -309,12 +386,12 @@ def _validate_branch_name_for_worktree_path(branch_name: str) -> None:
     assert_git_accepts_branch_name(branch_name)
 
 
-def _assert_path_is_under_agent_root(
+def _assert_path_is_under_configured_root(
     candidate_path: Path,
-    agent_worktree_root: Path,
+    configured_root: Path,
 ) -> None:
     resolved_candidate = candidate_path.resolve()
-    resolved_root = agent_worktree_root.resolve()
+    resolved_root = configured_root.resolve()
     if resolved_candidate == resolved_root:
         return
     try:
@@ -342,13 +419,19 @@ def _parse_arguments() -> argparse.Namespace:
     parser.add_argument(
         "--agent",
         default=None,
-        help="Host label for .claude/worktrees/<agent>/ (default: detect from environment).",
+        help="Host label for <configured-root>/<agent>/ (default: detect from environment).",
     )
     parser.add_argument(
         "--base",
         default=DEFAULT_BASE_REF,
         help=f"Base ref to fetch and branch from (default: {DEFAULT_BASE_REF}).",
     )
+    parser.add_argument(
+        CLI_FLAG_WORKTREE_ROOT,
+        default=None,
+        dest="worktree_root",
+        help=CLI_HELP_WORKTREE_ROOT,
+    )
     try:
         return parser.parse_args()
     except SystemExit as exit_error:

package/skills/fresh-branch/scripts/fresh_branch_scripts_constants/fresh_branch_cli_constants.py

@@ -1,7 +1,7 @@
 """Constants for the fresh-branch worktree creator.
 
-Groups: default refs, agent detection, path layout, JSON payload keys,
-exit codes, and unique-path suffix limits.
+Groups: default refs, agent detection, path layout, CLI flags, JSON payload
+keys, exit codes, and unique-path suffix limits.
 """
 
 from __future__ import annotations
@@ -25,6 +25,12 @@ PATH_SEGMENT_PARENT = ".."
 
 ALL_REPOSITORY_WORKTREE_ROOT_PARTS = (".claude", "worktrees")
 
+CLI_FLAG_WORKTREE_ROOT = "--worktree-root"
+CLI_HELP_WORKTREE_ROOT = (
+    "Absolute isolated root for worktrees "
+    "(default: <repo>/.claude/worktrees). Agent and branch nest under it."
+)
+
 MAXIMUM_UNIQUE_PATH_ATTEMPTS = 100
 UNIQUE_PATH_SUFFIX_START = 2
 
@@ -60,7 +66,8 @@ ERROR_BRANCH_NAME_REQUIRED = "branch name is required"
 ERROR_BRANCH_NAME_UNSAFE = (
     "branch name must be a relative path without '.' or '..' segments"
 )
-ERROR_WORKTREE_PATH_OUTSIDE_ROOT = "worktree path escapes agent root: %s"
+ERROR_WORKTREE_PATH_OUTSIDE_ROOT = "worktree path escapes configured root: %s"
+ERROR_WORKTREE_ROOT_NOT_ABSOLUTE = "--worktree-root must be an absolute path"
 ERROR_CLI_ARGUMENTS = "invalid or missing command-line arguments"
 ERROR_AGENT_SLUG_INVALID = "agent slug must be lowercase letters, digits, or hyphens"
 ERROR_REPO_NOT_GIT = "path is not inside a git repository: %s"