claude-dev-env 8.52.1 → 8.53.0

package/hooks/advisory/auto_mode_denial_quick_fix.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""PermissionDenied advisor: a proposed quick fix for each auto mode denial.
+
+This hook never retries the denied call. It reads the denial, names the
+classifier rule from the bracketed label in ``denial_reason``, drafts one
+``autoMode.allow`` entry for the denied action, and adds a PowerShell 7 block
+that writes the entry to ``~/.claude/settings.json`` with ``"$defaults"``
+kept. The agent receives the proposal as ``additionalContext``; the user
+receives a one-line ``systemMessage``.
+
+A denial with no ``classifier_verdict`` gets a short note and no block,
+because an allow entry cannot clear it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_root_directory not in sys.path:
+    sys.path.insert(0, _hooks_root_directory)
+
+from hooks_constants.auto_mode_denial_quick_fix_constants import (
+    ALL_COMMAND_INPUT_KEYS,
+    ALLOW_ENTRY_TEMPLATE,
+    HOOK_EVENT_NAME,
+    MAXIMUM_ACTION_SUMMARY_CHARACTERS,
+    NO_VERDICT_CONTEXT_TEMPLATE,
+    POWERSHELL_BLOCK_TEMPLATE,
+    RULE_LABEL_PATTERN,
+    SUMMARY_WORD_SEPARATOR,
+    TRUNCATION_MARKER,
+    UNNAMED_RULE_LABEL,
+    USER_MESSAGE_TEMPLATE,
+    VERDICT_CONTEXT_TEMPLATE,
+)
+
+
+def rule_label_from(denial_reason: str) -> str:
+    """Return the classifier rule name from a denial reason.
+
+    Args:
+        denial_reason: The ``denial_reason`` text, such as
+            ``"[Security Weaken] lowers a guard"``.
+
+    Returns:
+        The first bracketed label, or the unnamed-rule label.
+    """
+    label_match = re.search(RULE_LABEL_PATTERN, denial_reason)
+    return label_match.group(1).strip() if label_match else UNNAMED_RULE_LABEL
+
+
+def _summary_source_text(tool_input: object) -> str:
+    if not isinstance(tool_input, dict):
+        return json.dumps(tool_input, sort_keys=True)
+    for each_key in ALL_COMMAND_INPUT_KEYS:
+        if isinstance(tool_input.get(each_key), str):
+            return tool_input[each_key]
+    return json.dumps(tool_input, sort_keys=True)
+
+
+def action_summary_from(tool_input: object) -> str:
+    """Return one short line that names the denied action.
+
+    Args:
+        tool_input: The denied call's ``tool_input``.
+
+    Returns:
+        The command, URL or path when the input has one, else the compact
+        JSON input, cut to the summary length limit.
+    """
+    single_line_text = SUMMARY_WORD_SEPARATOR.join(_summary_source_text(tool_input).split())
+    if len(single_line_text) <= MAXIMUM_ACTION_SUMMARY_CHARACTERS:
+        return single_line_text
+    kept_length = MAXIMUM_ACTION_SUMMARY_CHARACTERS - len(TRUNCATION_MARKER)
+    return single_line_text[:kept_length] + TRUNCATION_MARKER
+
+
+def powershell_block_for(allow_entry: str) -> str:
+    """Return the PowerShell 7 block that adds one allow entry.
+
+    Args:
+        allow_entry: The ``autoMode.allow`` entry text.
+
+    Returns:
+        The block, with the entry in a single-quoted PowerShell literal.
+    """
+    escaped_entry = allow_entry.replace("'", "''")
+    return POWERSHELL_BLOCK_TEMPLATE.replace("{escaped_entry}", escaped_entry)
+
+
+def _verdict_context_text(
+    tool_name: str, denial_reason: str, action_summary: str, rule_label: str
+) -> str:
+    allow_entry = ALLOW_ENTRY_TEMPLATE.format(
+        rule_label=rule_label,
+        tool_name=tool_name,
+        action_summary=action_summary,
+    )
+    return VERDICT_CONTEXT_TEMPLATE.format(
+        tool_name=tool_name,
+        rule_label=rule_label,
+        denial_reason=denial_reason,
+        action_summary=action_summary,
+        powershell_block=powershell_block_for(allow_entry),
+    )
+
+
+def build_hook_output(all_denial_fields: dict[str, object]) -> dict[str, object]:
+    """Return the PermissionDenied hook output for one denial payload.
+
+    Args:
+        all_denial_fields: The hook input JSON.
+
+    Returns:
+        A ``hookSpecificOutput`` with ``additionalContext`` for the agent and
+        a top-level ``systemMessage`` for the user.
+    """
+    tool_name = str(all_denial_fields.get("tool_name") or "tool")
+    denial_reason = str(all_denial_fields.get("denial_reason") or "")
+    action_summary = action_summary_from(all_denial_fields.get("tool_input"))
+    rule_label = rule_label_from(denial_reason)
+    if all_denial_fields.get("classifier_verdict"):
+        context_text = _verdict_context_text(tool_name, denial_reason, action_summary, rule_label)
+    else:
+        context_text = NO_VERDICT_CONTEXT_TEMPLATE.format(
+            tool_name=tool_name,
+            denial_reason=denial_reason,
+            action_summary=action_summary,
+        )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "additionalContext": context_text,
+        },
+        "systemMessage": USER_MESSAGE_TEMPLATE.format(tool_name=tool_name, rule_label=rule_label),
+    }
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    sys.stdout.write(json.dumps(build_hook_output(payload)))
+    sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/advisory/test_auto_mode_denial_quick_fix.py

@@ -0,0 +1,113 @@
+"""Behavior tests for the auto mode denial quick-fix advisor."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+advisory_directory = str(Path(__file__).resolve().parent)
+if advisory_directory not in sys.path:
+    sys.path.insert(0, advisory_directory)
+import auto_mode_denial_quick_fix
+
+
+def _denial_payload(**overrides: object) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "hook_event_name": "PermissionDenied",
+        "tool_name": "mcp__github__resolve_review_thread",
+        "tool_input": {"threadId": "PRRT_abc"},
+        "denial_reason": "[Security Weaken] resolving review threads bypasses review",
+        "classifier_verdict": "deny",
+    }
+    payload.update(overrides)
+    return payload
+
+
+def test_should_name_the_bracketed_rule() -> None:
+    assert (
+        auto_mode_denial_quick_fix.rule_label_from("[Git Destructive] force") == "Git Destructive"
+    )
+
+
+def test_should_fall_back_when_the_reason_has_no_label() -> None:
+    assert auto_mode_denial_quick_fix.rule_label_from("Blocked by classifier") == "unnamed rule"
+
+
+def test_should_summarize_a_bash_call_by_its_command() -> None:
+    summary = auto_mode_denial_quick_fix.action_summary_from(
+        {"command": "git push\n --force origin x"}
+    )
+    assert summary == "git push --force origin x"
+
+
+def test_should_cut_a_long_summary_to_the_limit() -> None:
+    summary = auto_mode_denial_quick_fix.action_summary_from({"command": "x" * 500})
+    assert len(summary) == 160
+    assert summary.endswith("...")
+
+
+def test_should_escape_single_quotes_in_the_powershell_entry() -> None:
+    block = auto_mode_denial_quick_fix.powershell_block_for("it's allowed")
+    assert "$entry = 'it''s allowed'" in block
+    assert "$allowList.Add('$defaults')" in block
+
+
+def test_should_propose_rule_entry_and_block_for_a_classifier_denial() -> None:
+    hook_output = auto_mode_denial_quick_fix.build_hook_output(_denial_payload())
+    context_text = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert "rule [Security Weaken]" in context_text
+    assert (
+        "Security Weaken exception: mcp__github__resolve_review_thread calls like" in context_text
+    )
+    assert "```powershell" in context_text
+    assert "retry" not in hook_output["hookSpecificOutput"]
+    assert hook_output["systemMessage"].startswith(
+        "Auto mode blocked mcp__github__resolve_review_thread"
+    )
+
+
+def test_should_omit_the_block_when_no_verdict_exists() -> None:
+    payload = _denial_payload(denial_reason="classifier unavailable")
+    del payload["classifier_verdict"]
+    context_text = auto_mode_denial_quick_fix.build_hook_output(payload)["hookSpecificOutput"][
+        "additionalContext"
+    ]
+    assert "no classifier verdict" in context_text
+    assert "powershell" not in context_text
+
+
+def test_should_print_the_output_from_stdin(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(_denial_payload())))
+    assert auto_mode_denial_quick_fix.main() == 0
+    assert (
+        json.loads(capsys.readouterr().out)["hookSpecificOutput"]["hookEventName"]
+        == "PermissionDenied"
+    )
+
+
+def test_should_stay_quiet_on_malformed_input(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+    assert auto_mode_denial_quick_fix.main() == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_should_write_the_entry_with_defaults_when_powershell_runs(tmp_path: Path) -> None:
+    block = (
+        auto_mode_denial_quick_fix.powershell_block_for("it's allowed")
+        .replace("claude auto-mode config", "")
+        .replace("Join-Path $HOME", f"Join-Path '{tmp_path}'")
+    )
+    subprocess.run(["pwsh", "-NoProfile", "-Command", block], check=True)
+    written_settings = json.loads(
+        (tmp_path / ".claude" / "settings.json").read_text(encoding="utf-8")
+    )
+    assert written_settings["autoMode"]["allow"] == ["$defaults", "it's allowed"]

package/hooks/hooks.json

@@ -335,6 +335,18 @@
           }
         ]
       }
+    ],
+    "PermissionDenied": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/advisory/auto_mode_denial_quick_fix.py",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/hooks_constants/auto_mode_denial_quick_fix_constants.py

@@ -0,0 +1,79 @@
+"""Constants for the auto mode denial quick-fix advisor.
+
+The advisor is a PermissionDenied hook. It never retries the call. It turns
+each auto mode denial into a proposed fix: the rule name, a draft
+``autoMode.allow`` entry, and a PowerShell 7 block that adds the entry to
+``~/.claude/settings.json`` with ``"$defaults"`` kept in the list.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "HOOK_EVENT_NAME",
+    "RULE_LABEL_PATTERN",
+    "UNNAMED_RULE_LABEL",
+    "MAXIMUM_ACTION_SUMMARY_CHARACTERS",
+    "TRUNCATION_MARKER",
+    "SUMMARY_WORD_SEPARATOR",
+    "ALL_COMMAND_INPUT_KEYS",
+    "ALLOW_ENTRY_TEMPLATE",
+    "POWERSHELL_BLOCK_TEMPLATE",
+    "VERDICT_CONTEXT_TEMPLATE",
+    "NO_VERDICT_CONTEXT_TEMPLATE",
+    "USER_MESSAGE_TEMPLATE",
+]
+
+HOOK_EVENT_NAME = "PermissionDenied"
+RULE_LABEL_PATTERN = r"\[([^\]]+)\]"
+UNNAMED_RULE_LABEL = "unnamed rule"
+MAXIMUM_ACTION_SUMMARY_CHARACTERS = 160
+TRUNCATION_MARKER = "..."
+SUMMARY_WORD_SEPARATOR = " "
+ALL_COMMAND_INPUT_KEYS = ("command", "url", "file_path", "path")
+
+ALLOW_ENTRY_TEMPLATE = (
+    "{rule_label} exception: {tool_name} calls like `{action_summary}` "
+    "are allowed when they serve the task the user gave."
+)
+
+POWERSHELL_BLOCK_TEMPLATE = """\
+$settingsPath = Join-Path $HOME '.claude/settings.json'
+New-Item -ItemType Directory -Force -Path (Split-Path $settingsPath) | Out-Null
+$settings = if (Test-Path $settingsPath) { Get-Content -Raw $settingsPath | ConvertFrom-Json -AsHashtable } else { @{} }
+if (-not $settings.ContainsKey('autoMode')) { $settings['autoMode'] = @{} }
+$allowList = [System.Collections.Generic.List[string]]::new()
+if ($settings['autoMode'].ContainsKey('allow')) { $allowList.AddRange([string[]]@($settings['autoMode']['allow'])) } else { $allowList.Add('$defaults') }
+$entry = '{escaped_entry}'
+if ($allowList -notcontains $entry) { $allowList.Add($entry) }
+$settings['autoMode']['allow'] = $allowList.ToArray()
+$settings | ConvertTo-Json -Depth 32 | Set-Content -Encoding utf8NoBOM $settingsPath
+claude auto-mode config"""
+
+VERDICT_CONTEXT_TEMPLATE = """\
+=== AUTO MODE DENIAL QUICK FIX ===
+Auto mode denied {tool_name} under rule [{rule_label}].
+Denial reason: {denial_reason}
+Denied action: {action_summary}
+
+In your next message to the user, propose these two fixes. Do not retry and do not run the block yourself.
+1. One-off: the user replies with a message that names this exact action and its target; then you retry once.
+2. Lasting: the user runs this PowerShell 7 block on their machine. It adds one autoMode.allow entry to ~/.claude/settings.json and keeps "$defaults". Narrow the entry text to this action before you send it.
+
+```powershell
+{powershell_block}
+```
+
+For cloud sessions, the same entry must land in the ~/.claude/settings.json that the session's setup installs.
+Read the rule wording with: claude auto-mode defaults --label '{rule_label}'"""
+
+NO_VERDICT_CONTEXT_TEMPLATE = """\
+=== AUTO MODE DENIAL QUICK FIX ===
+Auto mode denied {tool_name} with no classifier verdict.
+Denial reason: {denial_reason}
+Denied action: {action_summary}
+
+An autoMode.allow entry cannot clear a denial with no verdict. Tell the user the action and the reason, and ask them to run it themselves or to retry it later."""
+
+USER_MESSAGE_TEMPLATE = (
+    "Auto mode blocked {tool_name} [{rule_label}]. Claude will propose a quick fix."
+)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.52.1",
+    "version": "8.53.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {