claude-dev-env 8.72.2 → 8.73.1

package/hooks/blocking/context_budget_blocker.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that denies a write growing an agent context file past its budget.
+
+The edited file's own repository supplies ``.claude/context-budget.json``; a
+repository without one uses the built-in kinds and treats the file's current
+content as its baseline entry. The hook denies only what an edit adds: an edit
+that only shrinks a file passes, and the CI ratchet never runs here.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking.codex_apply_patch import (
+    CodexPatchError,
+    parse_codex_apply_patch,
+    payload_patch_command,
+)
+from context_budget.findings import edit_findings
+from context_budget.model import BudgetPolicy, ContextBudgetPolicyError
+from context_budget.policy_file import default_policy, find_repository_root, read_policy_file
+from hooks_constants.context_budget_constants import (
+    CONTENT_KEY,
+    CONTEXT_BUDGET_BLOCK_PREFIX,
+    CONTEXT_BUDGET_HOOK_NAME,
+    CONTEXT_BUDGET_NOTICE,
+    CONTEXT_BUDGET_REASON_SEPARATOR,
+    CWD_KEY,
+    FILE_PATH_KEY,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    UTF8_ENCODING,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.multi_edit_reconstruction import apply_edits, edits_for_tool
+from hooks_constants.pre_tool_use_dispatcher_constants import (
+    ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    APPLY_PATCH_TOOL_NAME,
+    HOOK_EVENT_NAME,
+    WRITE_TOOL_NAME,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+EditedText = tuple[Path, str | None, str]
+
+
+def _read_optional_text(file_path: Path) -> str | None:
+    try:
+        return file_path.read_text(encoding=UTF8_ENCODING)
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _absolute_path(raw_path: str, payload_by_key: Mapping[str, object]) -> Path:
+    candidate = Path(raw_path).expanduser()
+    working_directory = payload_by_key.get(CWD_KEY)
+    if not candidate.is_absolute() and isinstance(working_directory, str):
+        candidate = Path(working_directory) / candidate
+    return candidate.resolve()
+
+
+def _edited_texts(payload_by_key: Mapping[str, object]) -> Iterator[EditedText]:
+    tool_name = payload_by_key.get(TOOL_NAME_KEY)
+    tool_input = payload_by_key.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict):
+        return
+    if tool_name == APPLY_PATCH_TOOL_NAME:
+        command, working_directory = payload_patch_command(dict(payload_by_key), tool_input)
+        try:
+            all_patch_files = parse_codex_apply_patch(command, working_directory)
+        except CodexPatchError:
+            return
+        for each_file in all_patch_files:
+            yield Path(each_file.file_path), each_file.prior_content or None, each_file.post_content
+        return
+    raw_path = tool_input.get(FILE_PATH_KEY)
+    if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES or not isinstance(raw_path, str):
+        return
+    file_path = _absolute_path(raw_path, payload_by_key)
+    prior_text = _read_optional_text(file_path)
+    if tool_name == WRITE_TOOL_NAME:
+        content = tool_input.get(CONTENT_KEY)
+        if isinstance(content, str):
+            yield file_path, prior_text, content
+    elif prior_text is not None:
+        yield file_path, prior_text, apply_edits(prior_text, edits_for_tool(str(tool_name), tool_input))
+
+
+def _policy_for(repository_root: Path) -> tuple[BudgetPolicy, bool]:
+    try:
+        policy = read_policy_file(repository_root)
+    except ContextBudgetPolicyError:
+        policy = None
+    if policy is None:
+        return default_policy(), True
+    return policy, False
+
+
+def _messages_for(edited_text: EditedText) -> list[str]:
+    file_path, prior_text, post_text = edited_text
+    repository_root = find_repository_root(file_path)
+    if repository_root is None:
+        return []
+    policy, is_prior_the_baseline = _policy_for(repository_root)
+    relative_path = file_path.relative_to(repository_root).as_posix()
+    all_findings = edit_findings(policy, relative_path, prior_text, post_text, is_prior_the_baseline)
+    return [each.message for each in all_findings]
+
+
+def evaluate(payload_by_key: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a write adds context past its budget.
+
+    Args:
+        payload_by_key: The PreToolUse payload.
+
+    Returns:
+        The deny reason, or None to allow.
+    """
+    all_messages = [
+        each_message
+        for each_edited_text in _edited_texts(payload_by_key)
+        for each_message in _messages_for(each_edited_text)
+    ]
+    if not all_messages:
+        return None
+    return CONTEXT_BUDGET_BLOCK_PREFIX + CONTEXT_BUDGET_REASON_SEPARATOR.join(all_messages)
+
+
+def build_deny_payload(deny_reason: str, tool_name: str | None) -> dict[str, object]:
+    """Build the PreToolUse deny response and log the block.
+
+    Args:
+        deny_reason: The reason ``evaluate`` returned.
+        tool_name: The intercepted tool name.
+
+    Returns:
+        The deny payload.
+    """
+    log_hook_block(
+        calling_hook_name=CONTEXT_BUDGET_HOOK_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=deny_reason,
+        tool_name=tool_name,
+    )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        },
+        "systemMessage": CONTEXT_BUDGET_NOTICE,
+    }
+
+
+def main() -> None:
+    """Read one hook payload and emit a deny response when needed."""
+    payload_by_key = read_hook_input_dictionary_from_stdin()
+    if payload_by_key is None:
+        return
+    deny_reason = evaluate(payload_by_key)
+    if deny_reason is None:
+        return
+    raw_tool_name = payload_by_key.get(TOOL_NAME_KEY)
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else None
+    sys.stdout.write(json.dumps(build_deny_payload(deny_reason, tool_name)) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_context_budget_blocker.py

@@ -0,0 +1,189 @@
+"""The context budget write hook denies only what an edit adds to agent context."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from blocking.context_budget_blocker import evaluate
+
+FIXTURE_DIRECTORY = HOOKS_DIRECTORY / "test_files" / "context_budget"
+DISPATCHER_PATH = HOOKS_DIRECTORY / "blocking" / "pre_tool_use_dispatcher.py"
+ORCHESTRATOR_RELATIVE_PATH = "packages/claude-dev-env/.agents/skills/orchestrator/SKILL.md"
+OVER_LIMIT_DETAIL = "".join(f"Detail line {each}.\n" for each in range(9))
+
+
+def _fixture_text(file_name: str) -> str:
+    return (FIXTURE_DIRECTORY / file_name).read_text(encoding="utf-8")
+
+
+@pytest.fixture
+def repository_root(tmp_path: Path) -> Path:
+    root = tmp_path / "other-repository"
+    (root / ".git").mkdir(parents=True)
+    return root
+
+
+def _write_payload(file_path: Path, content: str) -> dict[str, object]:
+    return {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(file_path), "content": content},
+    }
+
+
+def _edit_payload(file_path: Path, old_string: str, new_string: str) -> dict[str, object]:
+    return {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(file_path),
+            "old_string": old_string,
+            "new_string": new_string,
+        },
+    }
+
+
+def _over_budget_skill() -> str:
+    return "# Skill\n## Plan\n" + OVER_LIMIT_DETAIL + "filler\n" * 200
+
+
+def test_calibration_old_revision_is_denied_and_new_revision_allowed(repository_root: Path) -> None:
+    target_path = repository_root / ORCHESTRATOR_RELATIVE_PATH
+
+    old_reason = evaluate(
+        _write_payload(target_path, _fixture_text("orchestrator_skill_3f2c3ef.txt"))
+    )
+    new_reason = evaluate(
+        _write_payload(target_path, _fixture_text("orchestrator_skill_98f45b1.txt"))
+    )
+
+    assert old_reason is not None
+    assert (
+        'section "Oversee delegated work" has 9 detail lines and no pointer (limit 6)' in old_reason
+    )
+    assert new_reason is None
+
+
+def test_edit_that_only_shrinks_an_over_budget_file_is_allowed(repository_root: Path) -> None:
+    target_path = repository_root / "skills" / "big" / "SKILL.md"
+    target_path.parent.mkdir(parents=True)
+    target_path.write_text(_over_budget_skill(), encoding="utf-8")
+
+    assert evaluate(_edit_payload(target_path, "filler\nfiller\n", "")) is None
+
+
+def test_edit_that_grows_an_over_budget_file_is_denied(repository_root: Path) -> None:
+    target_path = repository_root / "skills" / "big" / "SKILL.md"
+    target_path.parent.mkdir(parents=True)
+    target_path.write_text(_over_budget_skill(), encoding="utf-8")
+
+    reason = evaluate(_edit_payload(target_path, "# Skill\n", "# Skill\nOne more line.\n"))
+
+    assert reason is not None
+    assert "was already over its limit at 211 lines and may only shrink" in reason
+    assert "list" not in reason
+
+
+def test_edit_that_adds_a_line_to_a_short_skill_with_one_long_section_is_allowed(
+    repository_root: Path,
+) -> None:
+    target_path = repository_root / "skills" / "short" / "SKILL.md"
+    target_path.parent.mkdir(parents=True)
+    plan_body = "".join(f"Detail line {each}.\n" for each in range(8))
+    target_path.write_text("# Skill\nIntro.\n## Plan\n" + plan_body, encoding="utf-8")
+
+    assert len(target_path.read_text(encoding="utf-8").splitlines()) == 11
+    assert evaluate(_edit_payload(target_path, "Intro.\n", "Intro.\nOne more line.\n")) is None
+
+
+def test_multi_edit_adding_an_unpointed_section_is_denied(repository_root: Path) -> None:
+    target_path = repository_root / "AGENTS.md"
+    target_path.write_text("# Agents\nShort.\n", encoding="utf-8")
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(target_path),
+            "edits": [
+                {"old_string": "Short.\n", "new_string": "Short.\n## Steps\n" + OVER_LIMIT_DETAIL}
+            ],
+        },
+    }
+
+    reason = evaluate(payload)
+
+    assert reason is not None and 'section "Steps"' in reason
+
+
+def test_apply_patch_adding_an_over_budget_rule_is_denied(repository_root: Path) -> None:
+    patch_lines = ["*** Begin Patch", "*** Add File: rules/long.md"]
+    patch_lines.extend(f"+Rule line {each}." for each in range(31))
+    patch_lines.append("*** End Patch")
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(repository_root),
+        "tool_input": {"command": "\n".join(patch_lines) + "\n"},
+    }
+
+    reason = evaluate(payload)
+
+    assert reason is not None and "file has 31 lines (rule limit 30)" in reason
+
+
+def test_policy_file_of_the_edited_repository_supplies_kinds_and_baseline(
+    repository_root: Path,
+) -> None:
+    (repository_root / ".claude").mkdir()
+    policy = {
+        "kinds": [
+            {"name": "guide", "patterns": ["docs/*.md"], "line_limit": 3, "section_rule": False}
+        ],
+        "baseline": {"files": {"docs/a.md": {"lines": 5, "sections": []}}},
+    }
+    (repository_root / ".claude" / "context-budget.json").write_text(
+        json.dumps(policy), encoding="utf-8"
+    )
+    target_path = repository_root / "docs" / "a.md"
+
+    assert evaluate(_write_payload(target_path, "1\n2\n3\n4\n5\n")) is None
+    reason = evaluate(_write_payload(target_path, "1\n2\n3\n4\n5\n6\n"))
+    assert reason is not None and "grew from 5 to 6 lines" in reason
+    assert evaluate(_write_payload(repository_root / "SKILL.md", OVER_LIMIT_DETAIL * 30)) is None
+
+
+def test_malformed_policy_file_falls_back_to_the_built_in_kinds(repository_root: Path) -> None:
+    (repository_root / ".claude").mkdir()
+    (repository_root / ".claude" / "context-budget.json").write_text("{broken", encoding="utf-8")
+
+    reason = evaluate(_write_payload(repository_root / "rules" / "r.md", "x\n" * 31))
+
+    assert reason is not None and "rule limit 30" in reason
+
+
+def test_files_outside_context_or_any_repository_are_allowed(
+    repository_root: Path, tmp_path: Path
+) -> None:
+    assert evaluate(_write_payload(repository_root / "notes.txt", "x\n" * 999)) is None
+    assert evaluate(_write_payload(tmp_path / "loose" / "SKILL.md", OVER_LIMIT_DETAIL * 99)) is None
+
+
+def test_dispatcher_carries_the_denial(repository_root: Path) -> None:
+    payload = _write_payload(repository_root / "rules" / "r.md", "x\n" * 31)
+
+    completed_process = subprocess.run(
+        [sys.executable, str(DISPATCHER_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    decision = json.loads(completed_process.stdout)["hookSpecificOutput"]
+    assert decision["permissionDecision"] == "deny"
+    assert "[CONTEXT_BUDGET]" in decision["permissionDecisionReason"]

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -804,7 +804,9 @@ def test_dispatcher_allows_clean_apply_patch_add(tmp_path: Path) -> None:
     assert not is_deny, reason_text
 
 
-ALL_RETAINED_PATHS: set[str] = set()
+ALL_RETAINED_PATHS = {
+    "blocking/context_budget_blocker.py",
+}
 ALL_RETIRED_PATHS = {
     "validation/hook_format_validator.py",
     "blocking/code_rules_enforcer.py",

package/hooks/context_budget/__init__.py

@@ -0,0 +1 @@
+"""Context budget check: measure agent context files and hooks against a policy."""

package/hooks/context_budget/baseline.py

@@ -0,0 +1,78 @@
+"""Build the over-budget list from the current tree, so no person writes it by hand.
+
+::
+
+    tree    a/SKILL.md 743 lines, section "Plan" over the limit
+    hooks   "startup print" injects 5200 characters (limit 1500)
+    result  {"files": {"a/SKILL.md": {"lines": 743, "sections": ["Plan"]}},
+             "hooks": {"startup print": 5200}}
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+from context_budget.model import BudgetPolicy
+from context_budget.sections import baseline_entry_for, measure_file
+from hooks_constants.context_budget_constants import (
+    BASELINE_FILES_KEY,
+    BASELINE_HOOKS_KEY,
+    BASELINE_KEY,
+    JSON_INDENT,
+    LINES_KEY,
+    SECTIONS_KEY,
+)
+
+
+def _file_entries(policy: BudgetPolicy, text_by_path: Mapping[str, str]) -> dict[str, dict]:
+    entry_by_path: dict[str, dict] = {}
+    for each_path in sorted(text_by_path):
+        measure = measure_file(policy, each_path, text_by_path[each_path])
+        entry = None if measure is None else baseline_entry_for(measure)
+        if entry is not None:
+            entry_by_path[each_path] = {
+                LINES_KEY: entry.lines,
+                SECTIONS_KEY: list(entry.all_section_headings),
+            }
+    return entry_by_path
+
+
+def build_baseline(
+    policy: BudgetPolicy,
+    text_by_path: Mapping[str, str],
+    characters_by_hook_name: Mapping[str, int],
+) -> dict[str, dict]:
+    """Return the baseline object that records every item over budget now.
+
+    Args:
+        policy: Budget policy whose kinds and hook limits apply.
+        text_by_path: Text of each tracked file by repository-relative path.
+        characters_by_hook_name: Measured characters of each policy hook.
+
+    Returns:
+        The ``baseline`` object with sorted file and hook entries.
+    """
+    entry_by_path = _file_entries(policy, text_by_path)
+    limit_by_hook_name = {each.name: each.char_limit for each in policy.all_hooks}
+    count_by_hook_name = {
+        each_name: each_count
+        for each_name, each_count in sorted(characters_by_hook_name.items())
+        if each_count > limit_by_hook_name.get(each_name, each_count)
+    }
+    return {BASELINE_FILES_KEY: entry_by_path, BASELINE_HOOKS_KEY: count_by_hook_name}
+
+
+def policy_text_with_baseline(policy_text: str, baseline_by_key: Mapping[str, dict]) -> str:
+    """Return the policy text with its baseline replaced and every other key kept.
+
+    Args:
+        policy_text: Current policy JSON text.
+        baseline_by_key: The new ``baseline`` object.
+
+    Returns:
+        Indented policy JSON text ending in a newline.
+    """
+    raw_policy = json.loads(policy_text)
+    raw_policy[BASELINE_KEY] = dict(baseline_by_key)
+    return json.dumps(raw_policy, indent=JSON_INDENT) + "\n"