multi-forge 0.2.0__py3-none-any.whl

forge/cli/hooks/install.py

@@ -0,0 +1,232 @@
+"""Hook enable/disable for Claude Code settings."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import click
+
+from forge.install.preset import get_builtin_preset
+from forge.session.claude.paths import get_claude_home
+
+SETTINGS_FILENAME = "settings.local.json"
+
+# Single source of truth: derive from the canonical preset
+FORGE_HOOK_CONFIG: dict[str, Any] = {"hooks": get_builtin_preset()["hooks"]}
+
+
+def _find_hooks_target(scope: str | None) -> tuple[Path, str]:
+    """Find target settings file for hooks based on scope.
+
+    Args:
+        scope: "user", "local", or None (auto-detect)
+
+    Returns:
+        Tuple of (settings_file_path, display_location)
+
+    Raises:
+        click.ClickException if no valid target found
+    """
+    if scope == "user":
+        settings_dir = get_claude_home()
+        return settings_dir / SETTINGS_FILENAME, "~/.claude"
+
+    if scope == "local":
+        settings_dir = Path.cwd() / ".claude"
+        return settings_dir / SETTINGS_FILENAME, ".claude"
+
+    current = Path.cwd().resolve()
+    home = Path.home().resolve()
+
+    while True:
+        claude_dir = current / ".claude"
+        if claude_dir.is_dir():
+            if current == home:
+                return claude_dir / SETTINGS_FILENAME, "~/.claude"
+            # Use relpath to safely compute display path (works when .claude is above cwd)
+            display_path = os.path.relpath(claude_dir, Path.cwd())
+            return claude_dir / SETTINGS_FILENAME, display_path
+
+        if current == home:
+            # At home without finding .claude = use user scope
+            return (get_claude_home() / SETTINGS_FILENAME), "~/.claude"
+
+        parent = current.parent
+        if parent == current:
+            raise click.ClickException(
+                "No .claude directory found. " "Run from a Claude Code project, or use --user for global install."
+            )
+        current = parent
+
+
+@click.command(name="enable")
+@click.option(
+    "--user",
+    "-U",
+    "scope",
+    flag_value="user",
+    help="Enable for ~/.claude/settings.local.json",
+)
+@click.option(
+    "--local",
+    "-L",
+    "scope",
+    flag_value="local",
+    help="Enable for .claude/settings.local.json (current directory)",
+)
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Overwrite existing hook configuration",
+)
+def enable(scope: str | None, force: bool) -> None:
+    """Enable Forge hooks in Claude Code settings.
+
+    Adds all Forge hook configurations to settings.local.json.
+
+    \b
+    Scope Detection (when no --user/--local specified):
+        Walks up from current directory looking for a .claude/ directory.
+        - If found: enables in that project's .claude/settings.local.json
+        - If reached ~: enables in ~/.claude/settings.local.json
+    """
+    from forge.install.version import check_minimum_version
+
+    version_check = check_minimum_version()
+    if not version_check.ok:
+        click.echo(f"Error: {version_check.reason}", err=True)
+        click.echo("Tip: Run 'claude update' to upgrade.", err=True)
+        raise SystemExit(1)
+
+    settings_file, location = _find_hooks_target(scope)
+    if scope is None:
+        click.echo(f"Auto-detected: {location}")
+
+    settings: dict[str, Any] = {}
+    if settings_file.exists():
+        try:
+            settings = json.loads(settings_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            click.echo(f"Error: Invalid JSON in {settings_file}: {e}", err=True)
+            raise SystemExit(1)
+
+    existing_hooks = settings.get("hooks", {})
+    if any(key in existing_hooks for key in FORGE_HOOK_CONFIG["hooks"].keys()) and not force:
+        click.echo(f"Forge hooks already configured in {settings_file}")
+        click.echo("Tip: Use --force to overwrite")
+        raise SystemExit(1)
+
+    if "hooks" not in settings:
+        settings["hooks"] = {}
+
+    for key, value in FORGE_HOOK_CONFIG["hooks"].items():
+        settings["hooks"][key] = value
+
+    settings_file.parent.mkdir(parents=True, exist_ok=True)
+    settings_file.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+
+    click.echo(f"Enabled Forge hooks in {location}/{SETTINGS_FILENAME}")
+
+
+def _is_forge_hook_entry(entry: Any) -> bool:
+    """Check if a hook entry is a Forge hook.
+
+    Matches entries where:
+    - type == "command" AND command starts with "forge hook "
+    - OR nested hooks contain such an entry
+    """
+    if not isinstance(entry, dict):
+        return False
+
+    # Direct command format: {type: "command", command: "forge hook ..."}
+    if entry.get("type") == "command":
+        cmd = entry.get("command", "")
+        if isinstance(cmd, str) and cmd.strip().startswith("forge hook "):
+            return True
+
+    # Nested hooks format: {hooks: [{type: "command", command: "forge hook ..."}]}
+    hooks_list = entry.get("hooks")
+    if isinstance(hooks_list, list):
+        for h in hooks_list:
+            if isinstance(h, dict) and h.get("type") == "command":
+                nested_cmd = h.get("command", "")
+                if isinstance(nested_cmd, str) and nested_cmd.strip().startswith("forge hook "):
+                    return True
+
+    return False
+
+
+@click.command(name="disable")
+@click.option(
+    "--user",
+    "-U",
+    "scope",
+    flag_value="user",
+    help="Disable from ~/.claude/settings.local.json",
+)
+@click.option(
+    "--local",
+    "-L",
+    "scope",
+    flag_value="local",
+    help="Disable from .claude/settings.local.json (current directory)",
+)
+def disable(scope: str | None) -> None:
+    """Disable Forge hooks in Claude Code settings.
+
+    Removes all Forge hook configuration entries from settings.local.json.
+
+    \b
+    Scope Detection (when no --user/--local specified):
+        Walks up from current directory looking for a .claude/ directory.
+        - If found: disables in that project's .claude/settings.local.json
+        - If reached ~: disables in ~/.claude/settings.local.json
+    """
+    settings_file, location = _find_hooks_target(scope)
+    if scope is None:
+        click.echo(f"Auto-detected: {location}")
+
+    if not settings_file.exists():
+        click.echo(f"No settings file found at {settings_file}")
+        return
+
+    try:
+        settings = json.loads(settings_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        click.echo(f"Error: Invalid JSON in {settings_file}: {e}", err=True)
+        raise SystemExit(1)
+
+    hooks_config = settings.get("hooks", {})
+    if not hooks_config:
+        click.echo("No hooks configured")
+        return
+
+    removed_any = False
+    for hook_name in list(hooks_config.keys()):
+        existing = hooks_config.get(hook_name, [])
+        if not isinstance(existing, list):
+            continue
+
+        remaining = [e for e in existing if not _is_forge_hook_entry(e)]
+        if len(remaining) != len(existing):
+            removed_any = True
+
+        if remaining:
+            settings["hooks"][hook_name] = remaining
+        else:
+            del settings["hooks"][hook_name]
+
+    if not removed_any:
+        click.echo("No Forge hooks found to disable")
+        return
+
+    if not settings.get("hooks"):
+        settings.pop("hooks", None)
+
+    settings_file.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+
+    click.echo(f"Disabled Forge hooks in {location}/{SETTINGS_FILENAME}")

forge/cli/hooks/policy.py

@@ -0,0 +1,151 @@
+"""Policy check helpers for the PreToolUse policy-check hook."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from forge.core.state import now_iso
+from forge.session import SessionStore
+from forge.session.models import SessionState
+from forge.session.store import HOOK_LOCK_TIMEOUT_S
+
+
+def _build_action_context(
+    data: dict[str, Any],
+    tool_name: str,
+    manifest: Any,
+) -> Any | None:
+    """Build ActionContext from hook payload.
+
+    Args:
+        data: Hook JSON payload
+        tool_name: "Write" or "Edit"
+        manifest: Session manifest
+
+    Returns:
+        ActionContext or None if required fields missing
+    """
+    from forge.guard.types import ActionContext
+
+    tool_input = data.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return None
+
+    target_path = tool_input.get("file_path") or tool_input.get("path")
+    if not isinstance(target_path, str):
+        target_path = None
+
+    cwd = Path.cwd().resolve()
+    if target_path:
+        try:
+            p = Path(target_path)
+            if p.is_absolute():
+                target_path = str(p.relative_to(cwd))
+        except (ValueError, RuntimeError):
+            # Keep as-is if can't make relative
+            pass
+
+    new_content = None
+    if tool_name == "Write":
+        new_content = tool_input.get("content")
+    elif tool_name == "Edit":
+        new_content = tool_input.get("new_string")
+
+    if new_content and len(new_content) > 5000:
+        new_content = new_content[:5000] + "\n... (truncated)"
+
+    return ActionContext(
+        event=f"PreToolUse.{tool_name}",
+        tool_name=tool_name,
+        tool_args=tool_input,
+        repo_root=str(cwd),
+        session_name=manifest.name,
+        target_path=target_path,
+        new_content=new_content,
+    )
+
+
+def _persist_policy_state(
+    *,
+    store: SessionStore,
+    engine: Any,
+    result: Any,
+    effective: Any,
+    context_summary: str,
+) -> None:
+    """Persist policy state updates to session manifest.
+
+    Updates decision log and generic policy_states from stateful policies.
+    """
+    from forge.guard.store import build_policy_state_update
+    from forge.session.models import PolicyConfirmed
+
+    collected_state = engine.get_collected_state()
+
+    def _mutate(m: object) -> None:
+        if not isinstance(m, SessionState):
+            raise TypeError(f"Expected SessionState, got {type(m)}")
+
+        existing = None
+        if m.confirmed.policy:
+            existing = {
+                "decisions": m.confirmed.policy.decisions,
+                "policy_states": m.confirmed.policy.policy_states,
+                "forge_version": m.confirmed.policy.forge_version,
+                "bundles": m.confirmed.policy.bundles,
+                "rules_active": m.confirmed.policy.rules_active,
+            }
+
+        updated = build_policy_state_update(
+            result=result,
+            engine_state=collected_state,
+            existing_state=existing,
+            bundles=effective.policy.bundles if effective.policy else [],
+            rules_active=[p.policy_id for p in engine.policies],
+            context_summary=context_summary,
+        )
+
+        m.confirmed.policy = PolicyConfirmed(
+            forge_version=updated.get("forge_version"),
+            bundles=updated.get("bundles", []),
+            rules_active=updated.get("rules_active", []),
+            decisions=updated.get("decisions", []),
+            policy_states=updated.get("policy_states", {}),
+        )
+
+        m.confirmed.confirmed_at = now_iso()
+        m.confirmed.confirmed_by = "hook:policy-check"
+
+    store.update(timeout_s=HOOK_LOCK_TIMEOUT_S, mutate=_mutate)
+
+
+def _derive_policy_source_label(result: Any, effective: Any) -> str:
+    """Derive source label from the most relevant policy for the outcome.
+
+    For deny: the first denying policy (the blocker).
+    For non-deny: prefer the supervisor if it participated (the expensive check),
+    fall back to the first matching deterministic policy.
+    """
+    sup = effective.policy.supervisor if effective.policy else None
+    sup_resume_id = sup.resume_id if sup else None
+
+    if result.final_decision == "deny":
+        for d in result.decisions:
+            if d.decision == "deny":
+                if d.policy_id == "semantic.supervisor" and sup_resume_id:
+                    return f"'{sup_resume_id}'"
+                return d.policy_id
+    else:
+        # Non-deny: prefer supervisor if it evaluated
+        for d in result.decisions:
+            if d.policy_id == "semantic.supervisor":
+                if sup_resume_id:
+                    return f"'{sup_resume_id}'"
+                return d.policy_id
+        # No supervisor — use first decision with matching outcome
+        for d in result.decisions:
+            if d.decision == result.final_decision:
+                return d.policy_id
+
+    return "policy"

forge/cli/hooks/read_hygiene.py

@@ -0,0 +1,74 @@
+"""Read hygiene hook: strip extra params from skill instruction file reads.
+
+Skill instruction files (code.md, docs.md, code-openai.md, docs-gemini.md, etc.)
+have a strict "file_path only" Read contract defined in SKILL.md. Models often
+add offset/limit/pages anyway. This hook silently fixes the call via updatedInput
+rather than blocking it — zero token cost, deterministic correction.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_SKILL_RESOURCE_RE = re.compile(r"/skills/[^/]+/resources/")
+_INSTRUCTION_BASENAME_RE = re.compile(r"^(code|docs)(-[a-z0-9_-]+)?\.md$")
+_EXTRA_READ_PARAMS = {"offset", "limit", "pages"}
+
+
+def _is_skill_instruction_file(file_path: str) -> bool:
+    """Check if a path is a skill instruction file with a strict Read contract.
+
+    Three checks, all must pass:
+    1. Path contains /skills/<name>/resources/
+    2. File is an immediate child of resources/ (parent dir is "resources")
+    3. Basename matches {mode}.md or {mode}-{family}.md
+    """
+    if not _SKILL_RESOURCE_RE.search(file_path):
+        return False
+    p = Path(file_path)
+    if p.parent.name != "resources":
+        return False
+    return bool(_INSTRUCTION_BASENAME_RE.fullmatch(p.name))
+
+
+def handle_read_hygiene(data: dict[str, Any]) -> dict[str, Any] | None:
+    """Process a PreToolUse:Read event and strip extra params if needed.
+
+    Returns the hookSpecificOutput dict to print, or None if no fix needed.
+    """
+    if data.get("hook_event_name") != "PreToolUse":
+        return None
+    if data.get("tool_name") != "Read":
+        return None
+
+    tool_input = data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return None
+
+    file_path = tool_input.get("file_path")
+    if not isinstance(file_path, str):
+        return None
+
+    if not _is_skill_instruction_file(file_path):
+        return None
+
+    extra_keys = set(tool_input.keys()) & _EXTRA_READ_PARAMS
+    if not extra_keys:
+        return None
+
+    logger.debug("read-hygiene: stripped %s from %s", sorted(extra_keys), Path(file_path).name)
+
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": {
+                "file_path": file_path,
+            },
+        }
+    }