claude-dev-env 2.2.0 → 2.3.0

package/CLAUDE.md

@@ -43,7 +43,7 @@ Run every multi-step code task in two phases:
 1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
 2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
-Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
+Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code (docs, images), a pytest test file by name (`test_*.py`, `*_test.py`, or `conftest.py`), or a Python file whose docstring-stripped AST is unchanged (docstring, comment, or formatting-only edits). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
 
 ## Sub-agent Output Validation
 

package/_shared/advisor/advisor-protocol.md

@@ -30,7 +30,7 @@ A third-party (non-Claude) harness cannot spawn a Claude `session-advisor` throu
    python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model <alias> --effort <effort> --output-format json
    ```
 
-   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. The chain runner walks `~/.claude/claude-chain.json` (binaries such as `claude`, `claude-ev`, `claude-editor`, `claude-mel`) and fails over only on a usage-limit signature.
+   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. The chain runner probes weekly remaining via `claude_chain_usage` / the usage-pause OAuth probe, ranks accounts in `~/.claude/claude-chain.json` highest remaining first, and fails over only on a usage-limit signature.
 4. Stop at the first successful bind. Record `{tier, result: "cli"}` and set `selected_tier` to that tier. Persist `session_id` from the JSON events (any event carries it; reply text is the `type == "result"` event's `.result` field). Run every bind and every later consult with cwd set to the repo root the work is for — Claude sessions are project-scoped by working directory.
 5. **Fail closed:** when every candidate fails (chain exhausted or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. Do **not** answer ENDORSE / CORRECTION / PLAN / STOP as this third-party session. Do **not** self-endorse.
 6. Paste the **Third-party host** Advisor block into every executor spawn prompt — never the Claude SendMessage block. Executors report to the orchestrating session; that session consults the bound Claude CLI advisor and relays the four-signal reply.
@@ -122,7 +122,7 @@ The orchestrating session owns the Claude CLI advisor bind for the whole run —
 
 ## CLI chain
 
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" -- <claude args...>`. It walks `~/.claude/claude-chain.json` and fails over to the next binary only on a usage-limit signature, so a usage-limited primary account still gets served.
+The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" -- <claude args...>`. It ranks accounts in `~/.claude/claude-chain.json` by weekly remaining (via `claude_chain_usage` / the usage-pause OAuth probe) and fails over to the next ranked binary only on a usage-limit signature, so a usage-limited first try still gets served.
 
 **Third-party host:** this runner is the **primary** advisor bind and consult path (see **Host profiles → Third-party host**). Map each walk attempt to `--model <alias>` and the effort flags there. When the walk exhausts, fail closed.
 

package/_shared/pr-loop/scripts/CLAUDE.md

@@ -11,6 +11,7 @@ Python scripts invoked at runtime by the PR-loop skills. Each script is a standa
 | `post_audit_thread.py` | Posts an audit review (APPROVE / REQUEST_CHANGES) to a draft PR via the GitHub reviews API; reads the body skeleton from `audit-reply-template.md` at runtime |
 | `grant_project_claude_permissions.py` | Writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting |
 | `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
+| `stale_worktree_rule_sweep.py` | Drops allow/deny rules pointing at deleted `~/.claude/worktrees/<repo>/<worktree>` directories and deduplicates the rule arrays; run by the grant and revoke flows before they write |
 | `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands, and the terminology sweep over the staged diff |
 | `terminology_sweep.py` | Flags a prose term that near-misses an identifier introduced on added code lines of a unified diff (shared leading word, divergent tail) |
 | `reviews_disabled.py` | Shared helper for the reviewer opt-out and opt-in gates; parses `CLAUDE_REVIEWS_DISABLED` tokens `bugteam`, `bugbot`, `copilot`, and `codex`, plus `CLAUDE_REVIEWS_ENABLED` for bugbot opt-in (bugbot is off by default and runs only when `CLAUDE_REVIEWS_ENABLED` lists it) |

package/_shared/pr-loop/scripts/grant_project_claude_permissions.py

@@ -1,284 +1,306 @@
-"""Grant Edit/Write/Read permissions on the current directory's .claude tree.
-
-Run from the project root whose .claude/** you want a Claude Code session
-(including spawned subagents) to edit without prompting. Writes idempotent
-entries into the user-scope settings at ~/.claude/settings.json and prints
-the changes applied. No-op when the entries already exist.
-"""
-
-import sys
-from pathlib import Path
-
-parent_directory = str(Path(__file__).resolve().parent)
-if parent_directory not in sys.path:
-    sys.path.insert(0, parent_directory)
-
-from _claude_permissions_common import (  # noqa: E402
-    append_if_missing,
-    build_agent_config_deny_rules,
-    build_permission_rules,
-    ensure_dict_section,
-    ensure_list_entry,
-    exit_with_error,
-    get_current_project_path,
-    is_trust_entry_for_project,
-    is_valid_project_root,
-    load_settings,
-    remove_matching_entries_from_list,
-    save_settings,
-)
-from pr_loop_shared_constants.claude_permissions_constants import (
-    ALL_AGENT_CONFIG_DENY_TOOLS,
-    ALL_AGENT_CONFIG_PATH_PATTERNS,
-    ALL_PERMISSION_ALLOW_TOOLS,
-    AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX,
-    AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE,
-    get_claude_user_settings_path,
-)
-from pr_loop_shared_constants.claude_settings_keys_constants import (
-    CLAUDE_SETTINGS_ADDITIONAL_DIRECTORIES_KEY,
-    CLAUDE_SETTINGS_ALLOW_KEY,
-    CLAUDE_SETTINGS_AUTO_MODE_KEY,
-    CLAUDE_SETTINGS_DENY_KEY,
-    CLAUDE_SETTINGS_ENVIRONMENT_KEY,
-    CLAUDE_SETTINGS_PERMISSIONS_KEY,
-)
-
-
-def add_rules_to_allow_list(
-    all_settings: dict[str, object], all_rules_to_add: list[str]
-) -> int:
-    """Add permission rules to the settings allow list.
-
-    Args:
-        all_settings: The parsed settings dictionary.
-        all_rules_to_add: Permission rule strings to append.
-
-    Returns:
-        Number of rules actually added (new entries).
-    """
-    permissions_section = ensure_dict_section(
-        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
-    )
-    existing_allow_list = ensure_list_entry(
-        permissions_section, CLAUDE_SETTINGS_ALLOW_KEY
-    )
-    return sum(
-        1
-        for each_rule in all_rules_to_add
-        if append_if_missing(existing_allow_list, each_rule)
-    )
-
-
-def add_rules_to_deny_list(
-    all_settings: dict[str, object], all_rules_to_add: list[str]
-) -> int:
-    """Add permission rules to the settings deny list.
-
-    Deny rules take precedence over allow rules in Claude Code's permission
-    matching, so writing agent-config paths into the deny list forces a
-    per-edit user approval even when a broader allow rule would cover them.
-
-    Args:
-        all_settings: The parsed settings dictionary.
-        all_rules_to_add: Permission rule strings to append.
-
-    Returns:
-        Number of rules actually added (new entries).
-    """
-    permissions_section = ensure_dict_section(
-        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
-    )
-    existing_deny_list = ensure_list_entry(
-        permissions_section, CLAUDE_SETTINGS_DENY_KEY
-    )
-    return sum(
-        1
-        for each_rule in all_rules_to_add
-        if append_if_missing(existing_deny_list, each_rule)
-    )
-
-
-def add_directory_to_additional_directories(
-    all_settings: dict[str, object], directory_path: str
-) -> int:
-    """Add a project path to the additionalDirectories allow list.
-
-    Args:
-        all_settings: The parsed settings dictionary.
-        directory_path: The project directory path to add.
-
-    Returns:
-        1 when the entry was added, 0 when it already existed.
-    """
-    permissions_section = ensure_dict_section(
-        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
-    )
-    existing_directories = ensure_list_entry(
-        permissions_section, CLAUDE_SETTINGS_ADDITIONAL_DIRECTORIES_KEY
-    )
-    if append_if_missing(existing_directories, directory_path):
-        return 1
-    return 0
-
-
-def add_auto_mode_environment_entry(
-    all_settings: dict[str, object], entry_text: str
-) -> int:
-    """Add an auto-mode environment entry for the project.
-
-    Args:
-        all_settings: The parsed settings dictionary.
-        entry_text: The environment entry text to add.
-
-    Returns:
-        1 when the entry was added, 0 when it already existed.
-    """
-    auto_mode_section = ensure_dict_section(
-        all_settings, CLAUDE_SETTINGS_AUTO_MODE_KEY
-    )
-    existing_environment = ensure_list_entry(
-        auto_mode_section, CLAUDE_SETTINGS_ENVIRONMENT_KEY
-    )
-    if append_if_missing(existing_environment, entry_text):
-        return 1
-    return 0
-
-
-def purge_stale_trust_entries(
-    all_settings: dict[str, object],
-    project_path: str,
-    prefix: str,
-    protected_entry: str | None = None,
-) -> int:
-    """Remove every prior trust entry for the project from autoMode.environment.
-
-    A trust entry is any string in autoMode.environment whose prefix matches
-    the trust-entry marker and that contains the project's .claude/** path.
-    Purging stale entries before adding the current template prevents
-    accumulation across template revisions. The optional protected_entry
-    survives the purge so an entry byte-identical to the one about to be
-    re-added is not removed and re-added on every invocation, preserving the
-    idempotency contract documented on grant_permissions_for_current_directory.
-
-    Args:
-        all_settings: The parsed settings dictionary.
-        project_path: The POSIX-style project root path.
-        prefix: The literal prefix that marks a trust entry.
-        protected_entry: Optional entry text that, when byte-equal to a
-            candidate, prevents removal. Pass the freshly-formatted current
-            template entry from grant to preserve idempotency. Revoke passes
-            None so every matching entry is removed.
-
-    Returns:
-        Number of stale entries removed.
-    """
-    auto_mode_section = all_settings.get(CLAUDE_SETTINGS_AUTO_MODE_KEY)
-    if not isinstance(auto_mode_section, dict):
-        return 0
-    existing_environment = auto_mode_section.get(CLAUDE_SETTINGS_ENVIRONMENT_KEY)
-    if not isinstance(existing_environment, list):
-        return 0
-
-    def _should_purge_candidate(candidate_entry: object) -> bool:
-        if not is_trust_entry_for_project(candidate_entry, project_path, prefix):
-            return False
-        if protected_entry is not None and candidate_entry == protected_entry:
-            return False
-        return True
-
-    return remove_matching_entries_from_list(
-        existing_environment,
-        _should_purge_candidate,
-    )
-
-
-def grant_permissions_for_current_directory() -> None:
-    """Grant Edit/Write/Read permissions for the current project directory.
-
-    Reads the current project path, constructs permission rules from config
-    constants, and writes them to ~/.claude/settings.json atomically. Adds
-    deny rules for agent-config paths so edits to settings, hooks, commands,
-    agents, skills, mcp.json, and CLAUDE.md still require per-edit user
-    approval. Purges any prior trust entries for this project before writing
-    the current template to prevent accumulation across template revisions.
-
-    Raises:
-        SystemExit: When the current directory is not a valid project root.
-        ValueError: Propagated from get_current_project_path() when the path
-                    contains glob metacharacters.
-    """
-    claude_user_settings_path: Path = get_claude_user_settings_path()
-    project_root_path = Path.cwd()
-    if not is_valid_project_root(project_root_path):
-        print(
-            f"ERROR: cwd {project_root_path} is not a project root "
-            f"(no .git or .claude). Run from a project root.",
-            file=sys.stderr,
-        )
-        raise SystemExit(1)
-    project_path = get_current_project_path()
-    all_permission_rules = build_permission_rules(
-        project_path, ALL_PERMISSION_ALLOW_TOOLS
-    )
-    all_agent_config_deny_rules = build_agent_config_deny_rules(
-        project_path,
-        ALL_AGENT_CONFIG_DENY_TOOLS,
-        ALL_AGENT_CONFIG_PATH_PATTERNS,
-    )
-    environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
-        project_path=project_path
-    )
-    settings = load_settings(claude_user_settings_path)
-    allow_rules_added_count = add_rules_to_allow_list(settings, all_permission_rules)
-    deny_rules_added_count = add_rules_to_deny_list(
-        settings, all_agent_config_deny_rules
-    )
-    directories_added_count = add_directory_to_additional_directories(
-        settings, project_path
-    )
-    stale_trust_entries_purged_count = purge_stale_trust_entries(
-        settings,
-        project_path,
-        AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX,
-        protected_entry=environment_entry,
-    )
-    environment_entries_added_count = add_auto_mode_environment_entry(
-        settings, environment_entry
-    )
-    total_changes_count = (
-        allow_rules_added_count
-        + deny_rules_added_count
-        + directories_added_count
-        + stale_trust_entries_purged_count
-        + environment_entries_added_count
-    )
-    if total_changes_count == 0:
-        print(f"Project path: {project_path}")
-        print(f"Settings file: {claude_user_settings_path}")
-        print("No changes needed; settings file left untouched.")
-        return
-    save_settings(claude_user_settings_path, settings)
-    print(f"Project path: {project_path}")
-    print(f"Settings file: {claude_user_settings_path}")
-    print(
-        f"Allow rules added: {allow_rules_added_count} of {len(all_permission_rules)}"
-    )
-    print(
-        f"Deny rules added: {deny_rules_added_count} of "
-        f"{len(all_agent_config_deny_rules)}"
-    )
-    print(f"Additional directories added: {directories_added_count}")
-    if stale_trust_entries_purged_count > 0:
-        print(
-            f"Stale auto-mode environment entries purged: "
-            f"{stale_trust_entries_purged_count}"
-        )
-    print(f"Auto-mode environment entries added: {environment_entries_added_count}")
-
-
-if __name__ == "__main__":
-    try:
-        grant_permissions_for_current_directory()
-    except ValueError as path_error:
-        exit_with_error(str(path_error))
+"""Grant Edit/Read permissions on the current directory's .claude tree.
+
+Run from the project root whose .claude/** you want a Claude Code session
+(including spawned subagents) to edit without prompting. Writes idempotent
+entries into the user-scope settings at ~/.claude/settings.json and prints
+the changes applied. No-op when the entries already exist.
+"""
+
+import sys
+from pathlib import Path
+
+parent_directory = str(Path(__file__).resolve().parent)
+if parent_directory not in sys.path:
+    sys.path.insert(0, parent_directory)
+
+from _claude_permissions_common import (  # noqa: E402
+    append_if_missing,
+    build_agent_config_deny_rules,
+    build_permission_rules,
+    ensure_dict_section,
+    ensure_list_entry,
+    exit_with_error,
+    get_current_project_path,
+    is_trust_entry_for_project,
+    is_valid_project_root,
+    load_settings,
+    remove_matching_entries_from_list,
+    save_settings,
+)
+from pr_loop_shared_constants.claude_permissions_constants import (
+    ALL_AGENT_CONFIG_DENY_TOOLS,
+    ALL_AGENT_CONFIG_PATH_PATTERNS,
+    ALL_PERMISSION_ALLOW_TOOLS,
+    AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX,
+    AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE,
+    get_claude_user_settings_path,
+)
+from pr_loop_shared_constants.claude_settings_keys_constants import (
+    CLAUDE_SETTINGS_ADDITIONAL_DIRECTORIES_KEY,
+    CLAUDE_SETTINGS_ALLOW_KEY,
+    CLAUDE_SETTINGS_AUTO_MODE_KEY,
+    CLAUDE_SETTINGS_DENY_KEY,
+    CLAUDE_SETTINGS_ENVIRONMENT_KEY,
+    CLAUDE_SETTINGS_PERMISSIONS_KEY,
+)
+from stale_worktree_rule_sweep import (  # noqa: E402
+    sweep_stale_worktree_rules_from_settings,
+)
+
+
+def add_rules_to_allow_list(
+    all_settings: dict[str, object], all_rules_to_add: list[str]
+) -> int:
+    """Add permission rules to the settings allow list.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        all_rules_to_add: Permission rule strings to append.
+
+    Returns:
+        Number of rules actually added (new entries).
+    """
+    permissions_section = ensure_dict_section(
+        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
+    )
+    existing_allow_list = ensure_list_entry(
+        permissions_section, CLAUDE_SETTINGS_ALLOW_KEY
+    )
+    return sum(
+        1
+        for each_rule in all_rules_to_add
+        if append_if_missing(existing_allow_list, each_rule)
+    )
+
+
+def add_rules_to_deny_list(
+    all_settings: dict[str, object], all_rules_to_add: list[str]
+) -> int:
+    """Add permission rules to the settings deny list.
+
+    Deny rules take precedence over allow rules in Claude Code's permission
+    matching, so writing agent-config paths into the deny list forces a
+    per-edit user approval even when a broader allow rule would cover them.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        all_rules_to_add: Permission rule strings to append.
+
+    Returns:
+        Number of rules actually added (new entries).
+    """
+    permissions_section = ensure_dict_section(
+        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
+    )
+    existing_deny_list = ensure_list_entry(
+        permissions_section, CLAUDE_SETTINGS_DENY_KEY
+    )
+    return sum(
+        1
+        for each_rule in all_rules_to_add
+        if append_if_missing(existing_deny_list, each_rule)
+    )
+
+
+def add_directory_to_additional_directories(
+    all_settings: dict[str, object], directory_path: str
+) -> int:
+    """Add a project path to the additionalDirectories allow list.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        directory_path: The project directory path to add.
+
+    Returns:
+        1 when the entry was added, 0 when it already existed.
+    """
+    permissions_section = ensure_dict_section(
+        all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
+    )
+    existing_directories = ensure_list_entry(
+        permissions_section, CLAUDE_SETTINGS_ADDITIONAL_DIRECTORIES_KEY
+    )
+    if append_if_missing(existing_directories, directory_path):
+        return 1
+    return 0
+
+
+def add_auto_mode_environment_entry(
+    all_settings: dict[str, object], entry_text: str
+) -> int:
+    """Add an auto-mode environment entry for the project.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        entry_text: The environment entry text to add.
+
+    Returns:
+        1 when the entry was added, 0 when it already existed.
+    """
+    auto_mode_section = ensure_dict_section(
+        all_settings, CLAUDE_SETTINGS_AUTO_MODE_KEY
+    )
+    existing_environment = ensure_list_entry(
+        auto_mode_section, CLAUDE_SETTINGS_ENVIRONMENT_KEY
+    )
+    if append_if_missing(existing_environment, entry_text):
+        return 1
+    return 0
+
+
+def _is_stale_trust_entry(
+    candidate_entry: object,
+    project_path: str,
+    prefix: str,
+    protected_entry: str | None,
+) -> bool:
+    if not is_trust_entry_for_project(candidate_entry, project_path, prefix):
+        return False
+    if protected_entry is not None and candidate_entry == protected_entry:
+        return False
+    return True
+
+
+def purge_stale_trust_entries(
+    all_settings: dict[str, object],
+    project_path: str,
+    prefix: str,
+    protected_entry: str | None = None,
+) -> int:
+    """Remove every prior trust entry for the project from autoMode.environment.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        project_path: The POSIX-style project root path.
+        prefix: The literal prefix that marks a trust entry.
+        protected_entry: When byte-equal to a candidate, prevents its removal.
+
+    Returns:
+        Number of stale entries removed.
+    """
+    auto_mode_section = all_settings.get(CLAUDE_SETTINGS_AUTO_MODE_KEY)
+    if not isinstance(auto_mode_section, dict):
+        return 0
+    existing_environment = auto_mode_section.get(CLAUDE_SETTINGS_ENVIRONMENT_KEY)
+    if not isinstance(existing_environment, list):
+        return 0
+    return remove_matching_entries_from_list(
+        existing_environment,
+        lambda candidate_entry: _is_stale_trust_entry(
+            candidate_entry, project_path, prefix, protected_entry
+        ),
+    )
+
+
+def _resolve_project_path_or_exit() -> str:
+    project_root_path = Path.cwd()
+    if not is_valid_project_root(project_root_path):
+        print(
+            f"ERROR: cwd {project_root_path} is not a project root "
+            f"(no .git or .claude). Run from a project root.",
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+    return get_current_project_path()
+
+
+def _build_grant_rule_sets(
+    project_path: str,
+) -> tuple[list[str], list[str], str]:
+    all_permission_rules = build_permission_rules(
+        project_path, ALL_PERMISSION_ALLOW_TOOLS
+    )
+    all_agent_config_deny_rules = build_agent_config_deny_rules(
+        project_path,
+        ALL_AGENT_CONFIG_DENY_TOOLS,
+        ALL_AGENT_CONFIG_PATH_PATTERNS,
+    )
+    environment_entry = AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(
+        project_path=project_path
+    )
+    return (all_permission_rules, all_agent_config_deny_rules, environment_entry)
+
+
+def _apply_grant(
+    all_settings: dict[str, object],
+    project_path: str,
+    all_grant_rule_sets: tuple[list[str], list[str], str],
+) -> tuple[int, int, int, int, int]:
+    all_permission_rules, all_agent_config_deny_rules, environment_entry = (
+        all_grant_rule_sets
+    )
+    allow_added = add_rules_to_allow_list(all_settings, all_permission_rules)
+    deny_added = add_rules_to_deny_list(all_settings, all_agent_config_deny_rules)
+    dirs_added = add_directory_to_additional_directories(all_settings, project_path)
+    purged = purge_stale_trust_entries(
+        all_settings,
+        project_path,
+        AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX,
+        protected_entry=environment_entry,
+    )
+    env_added = add_auto_mode_environment_entry(all_settings, environment_entry)
+    return (allow_added, deny_added, dirs_added, purged, env_added)
+
+
+def _print_no_change_notice(
+    project_path: str, claude_user_settings_path: Path
+) -> None:
+    print(f"Project path: {project_path}")
+    print(f"Settings file: {claude_user_settings_path}")
+    print("No changes needed; settings file left untouched.")
+
+
+def _print_grant_summary(
+    project_path: str,
+    claude_user_settings_path: Path,
+    all_grant_rule_sets: tuple[list[str], list[str], str],
+    all_change_counts: tuple[int, int, int, int, int],
+) -> None:
+    all_permission_rules, all_agent_config_deny_rules, _ = all_grant_rule_sets
+    allow_added, deny_added, dirs_added, purged, env_added = all_change_counts
+    print(f"Project path: {project_path}")
+    print(f"Settings file: {claude_user_settings_path}")
+    print(f"Allow rules added: {allow_added} of {len(all_permission_rules)}")
+    print(f"Deny rules added: {deny_added} of {len(all_agent_config_deny_rules)}")
+    print(f"Additional directories added: {dirs_added}")
+    if purged > 0:
+        print(f"Stale auto-mode environment entries purged: {purged}")
+    print(f"Auto-mode environment entries added: {env_added}")
+
+
+def grant_permissions_for_current_directory() -> None:
+    """Grant Edit/Read permissions for the current project directory.
+
+    Builds allow and agent-config deny rules from config, writes them to the
+    user settings, and prints the counts applied. A fresh grant reports::
+
+        Allow rules added: 2 of 2
+        Deny rules added: 14 of 14
+        Additional directories added: 1
+        Auto-mode environment entries added: 1
+
+    Raises:
+        SystemExit: When the current directory is not a valid project root.
+        ValueError: Propagated from get_current_project_path() when the path
+                    contains glob metacharacters.
+    """
+    claude_user_settings_path: Path = get_claude_user_settings_path()
+    project_path = _resolve_project_path_or_exit()
+    grant_rule_sets = _build_grant_rule_sets(project_path)
+    settings = load_settings(claude_user_settings_path)
+    worktree_sweep_removed_count = sweep_stale_worktree_rules_from_settings(settings)
+    change_counts = _apply_grant(settings, project_path, grant_rule_sets)
+    if sum(change_counts) + worktree_sweep_removed_count == 0:
+        _print_no_change_notice(project_path, claude_user_settings_path)
+        return
+    save_settings(claude_user_settings_path, settings)
+    _print_grant_summary(
+        project_path, claude_user_settings_path, grant_rule_sets, change_counts
+    )
+
+
+if __name__ == "__main__":
+    try:
+        grant_permissions_for_current_directory()
+    except ValueError as path_error:
+        exit_with_error(str(path_error))