capt-hook 6.3.0__tar.gz → 6.4.0__tar.gz

{capt_hook-6.3.0 → capt_hook-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 6.3.0
+Version: 6.4.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/cli.py

@@ -501,7 +501,9 @@ def run_tests(json_output: bool = False) -> None:
 @click.pass_context
 def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
     """Captain Hook — declarative hook framework for Claude Code lifecycle events."""
-    root = Path(root_path) if root_path else Path(env) if (env := os.environ.get("CLAUDE_PROJECT_DIR")) else Path.cwd()
+    from captain_hook.settings import resolve_project_dir
+
+    root = Path(root_path) if root_path else Path(p) if (p := resolve_project_dir()) else Path.cwd()
     ctx.obj = CliState(root=root, hooks=hooks or str(root / ".claude" / "hooks"))
 
 

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/context.py

@@ -21,6 +21,7 @@ from spawnllm.proc import run_cli
 from captain_hook.classifiers import detect
 from captain_hook.prompt import Prompt
 from captain_hook.session import SessionStore
+from captain_hook.settings import resolve_project_dir
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -78,7 +79,7 @@ def lift_session(events: Sequence[TranscriptEvent], *, path: Path | None = None)
     from captain_hook.app import _state
 
     classifier = _state.classifier or detect(
-        cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
+        cwd=resolve_project_dir(),
         transcript_path=str(path) if path else None,
         events=events,
     )
@@ -185,7 +186,7 @@ class HookContext:
                 input=input,
                 timeout=timeout,
                 env=os.environ | (env or {}),
-                cwd=os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR"),
+                cwd=resolve_project_dir(),
             )
         except (OSError, subprocess.SubprocessError):
             if throw:
@@ -309,7 +310,7 @@ class HookContext:
     ) -> str | BaseModel:
         diff_text = self.diff("uncommitted" if diff is True else diff) if diff else None
         prompt = self.assemble_prompt(template, args, kwargs, transcript=transcript, diff_text=diff_text)
-        cwd = os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR")
+        cwd = resolve_project_dir()
         if response_model is not None:
             return extract_sync(
                 prompt, response_model, specialty=specialty, model=model, agent=agent, cwd=cwd, timeout=timeout

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/durable.py

@@ -26,13 +26,11 @@ if TYPE_CHECKING:
 
 Scope = Literal["project", "global"]
 
-DURABLE_ROOT_OVERRIDE: list[Path] = []
-
 
 def durable_root() -> Path:
     from captain_hook.settings import resolve_state_dir
 
-    return DURABLE_ROOT_OVERRIDE[-1] if DURABLE_ROOT_OVERRIDE else resolve_state_dir() / "hooks" / "durable"
+    return resolve_state_dir() / "hooks" / "durable"
 
 
 def project_key(repo_root: Path) -> str:
@@ -98,11 +96,6 @@ class DurableStore:
         if model not in cls.TRACKED:
             cls.TRACKED.append(model)
 
-    @classmethod
-    def untrack(cls, model: type[BaseModel]) -> None:
-        if model in cls.TRACKED:
-            cls.TRACKED.remove(model)
-
     @classmethod
     def tracked_models(cls) -> Sequence[type[BaseModel]]:
         return tuple(cls.TRACKED)

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/loader.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING
 
 from loguru import logger
 
-from captain_hook.app import State, _state, on
+from captain_hook.app import _state, on
 from captain_hook.settings import build_settings
 from captain_hook.types import Event
 
@@ -47,8 +47,7 @@ def import_or_reload(fqn: str, fresh_this_pass: set[str]) -> ModuleType:
     return mod
 
 
-def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
-    target = state or _state
+def discover_hooks(hooks_dir: str | Path) -> None:
     hooks_path = Path(hooks_dir).resolve()
     if str(hooks_path.parent) not in sys.path:
         sys.path.insert(0, str(hooks_path.parent))
@@ -60,9 +59,9 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
 
     if CONF_MODULE in top_level:
         conf_module = import_or_reload(f"{pkg}.{CONF_MODULE}", fresh_this_pass)
-        target.settings = build_settings(conf_module)
+        _state.settings = build_settings(conf_module)
         if classifier := getattr(conf_module, "classifier", None):
-            target.classifier = classifier
+            _state.classifier = classifier
 
     all_modules = {
         info.name
@@ -80,7 +79,7 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
             import_or_reload(fqn, fresh_this_pass)
         except Exception as exc:
             logger.bind(module=fqn).opt(exception=True).warning("skipped unloadable hook module")
-            target.load_errors.append((fqn, exc))
+            _state.load_errors.append((fqn, exc))
 
 
 def ensure_pack_package(fqn: str, search_paths: list[str]) -> ModuleType:

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/packs/general/capt-hook.toml

@@ -1,5 +1,5 @@
 name = "general"
-version = "0.8.0"
+version = "0.9.0"
 description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, and code-review + docs-freshness gates."
 hooks = "."
 nlp = true

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/packs/general/models.py

@@ -10,6 +10,7 @@ from captain_hook import (
     Block,
     Clause,
     Event,
+    FilePath,
     Input,
     Phrase,
     Rewrite,
@@ -43,6 +44,19 @@ class DelegatedSpawn:
         return f"model: {model}\nagent_type: {call.agent_type or '(default)'}\nprompt:\n{call.prompt}"
 
 
+@dataclass(frozen=True, slots=True)
+class InlineEdit:
+    """Gating context: the file the main agent is about to edit inline on the main loop."""
+
+    tag: str = "edit_target"
+    required: bool = True
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        if not evt.file or evt.content is None:
+            return None
+        return f"file: {evt.file.path}\nincoming text: {len(evt.content):,} chars"
+
+
 WORKFLOW_SCRIPT_CAP = 14_000  # below the prose hooks' max_context=16_000, so truncation stays ours
 
 
@@ -120,12 +134,13 @@ class ProseSpawn(DelegatedSpawn):
 
 @dataclass(frozen=True, slots=True)
 class WorkflowScriptSource:
-    """Gating context: the pending Workflow call's script source, headed by its model pins and prose asks."""
+    """Gating context: the pending Workflow call's script source, headed by its model pins."""
 
     tag: str = "workflow_script"
     required: bool = True
 
-    def content(self, evt: BaseHookEvent) -> str | None:
+    @staticmethod
+    def pins_and_source(evt: BaseHookEvent) -> tuple[str, str] | None:
         if (source := workflow_script_source(evt)) is None:
             return None
         pin_lines = "\n".join(
@@ -138,14 +153,31 @@ class WorkflowScriptSource:
                 f"… [script truncated: {len(source):,} chars total; every model pin is quoted above] …\n"
                 f"{source[-tail:]}"
             )
+        header = (
+            "lines that pin a model in this script (a stage not quoted here inherits the "
+            f"session model, fable):\n{pin_lines or '  (none)'}"
+        )
+        return header, source
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        if (parts := self.pins_and_source(evt)) is None:
+            return None
+        header, source = parts
+        return f"{header}\n\n{source}"
+
+
+@dataclass(frozen=True, slots=True)
+class ProseWorkflowScript(WorkflowScriptSource):
+    """Gating context: the script source, present only when its prose asks survive the prefilter."""
+
+    def content(self, evt: BaseHookEvent) -> str | None:
+        if (parts := self.pins_and_source(evt)) is None:
+            return None
+        header, source = parts
         if not (sentences := prose_deliverable_sentences(source)):
             return None
         matched = "\n".join(f"  {s[:300]}" for s in sentences)
-        return (
-            "lines that pin a model in this script (a stage not quoted here inherits the "
-            f"session model, fable):\n{pin_lines or '  (none)'}\n\n"
-            f"sentences the prose prefilter matched:\n{matched}\n\n{source}"
-        )
+        return f"{header}\n\nsentences the prose prefilter matched:\n{matched}\n\n{source}"
 
 
 hook(
@@ -286,16 +318,17 @@ llm_nudge(
 the session model, fable), agent type, and prompt.
 
 The Models rubric: implementation delegates to opus-4.8 at xhigh — opus is ~2x cheaper
-than fable and nearly as capable. Fable's lanes are orchestration, review, hard
-planning/design/diagnosis, all prose/writing, and implementation that is very sensitive
-or error-prone (auth, migrations, concurrency, data loss, crypto, subtle algorithms).
+than fable and nearly as capable. Fable's lanes are orchestration, design/architecture
+review, hard planning, all prose/writing, and implementation that is very sensitive or
+error-prone (auth, migrations, concurrency, data loss, crypto, subtle algorithms).
+Code/diff review and bug diagnosis have their own gpt-5.5 lane with a separate nudge.
 
 Set fire=true only when the prompt is clearly routine implementation — building, fixing,
 wiring, or refactoring code — with no fable-lane signal. A prompt that reviews, plans,
-designs, diagnoses a hard bug, writes prose, or touches a sensitive surface stays on
-fable: fire=false. When uncertain, fire=false — the agent may have chosen fable
-deliberately, and a false alarm teaches it to ignore this nudge. Keep reasoning under
-40 words.
+designs, diagnoses a bug, writes prose, or touches a sensitive surface is not an
+implementation prompt: fire=false. When uncertain, fire=false — the agent may have
+chosen fable deliberately, and a false alarm teaches it to ignore this nudge. Keep
+reasoning under 40 words.
 
 <examples>
 <example fire="true">
@@ -308,7 +341,7 @@ Well-scoped feature wiring; the default implementation lane.
 </example>
 <example fire="false">
 Review the diff for correctness and concurrency issues.
-Review is fable's lane.
+Not implementation — review routes via its own nudge (gpt-5.5's lane), not to opus.
 </example>
 <example fire="false">
 Design the migration strategy for the sharded session store.
@@ -344,6 +377,184 @@ Auth plus concurrency: sensitive, error-prone implementation stays on fable.
     },
 )
 
+llm_nudge(
+    """Decide whether the main agent should delegate this inline edit instead of making
+it itself.
+
+The main loop runs on fable-5; this pending edit is fable implementing directly.
+<edit_target> names the file; <before_edit>/<after_edit> hold the text being replaced
+and written.
+
+The Models rubric: implementation belongs to a delegated opus-4.8 subagent at xhigh —
+~2x cheaper than fable and nearly as capable — or, for a well-scoped edit to existing
+code, to gpt-5.5 via the codex skill. Fable edits inline when the change is small or
+judgment-bound: a fix-up finishing work it just reasoned through, a subtle algorithm,
+or a sensitive surface (auth, migrations, concurrency, data loss, crypto).
+
+Set fire=true only when this edit is clearly substantial routine implementation —
+building out a feature, wiring components, refactoring — that a subagent could own end
+to end. A small fix-up, a sensitive surface, or a change entangled with judgment the
+main agent just exercised stays inline: fire=false. When uncertain, fire=false — the
+agent may be editing inline deliberately, and a false alarm teaches it to ignore this
+nudge. Keep reasoning under 40 words.
+
+<examples>
+<example fire="true">
+after_edit: a new 180-line pagination module written to src/api/pagination.py.
+Substantial net-new feature code — a delegated opus xhigh subagent's lane.
+</example>
+<example fire="true">
+after_edit: rewiring three call sites and adding a formatter class in export.py.
+Routine multi-part refactor a subagent could own end to end.
+</example>
+<example fire="false">
+after_edit: a two-line fix to the retry counter the agent just diagnosed.
+Small fix-up entangled with judgment already exercised — inline is right.
+</example>
+<example fire="false">
+after_edit: reworking the token-refresh lock in auth/middleware.py.
+Auth plus concurrency is a sensitive surface — fable's inline lane.
+</example>
+</examples>""",
+    message=lambda r: (
+        f"This inline edit reads as routine implementation on fable. {r.reasoning} "
+        "Implementation delegates: spawn a model='opus', effort='xhigh' subagent to own the change, "
+        "or route a well-scoped edit to gpt-5.5 via the codex skill. Keep editing inline only when "
+        "the change is small, sensitive, or bound to judgment you just exercised. "
+        "See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    contexts=[InlineEdit()],
+    events=Event.PreToolUse,
+    only_if=[
+        Tool("Edit|Write|MultiEdit"),
+        FilePath(
+            "**/*.py",
+            "**/*.go",
+            "**/*.swift",
+            "**/*.rs",
+            "**/*.ts",
+            "**/*.tsx",
+            "**/*.js",
+            "**/*.jsx",
+            "**/*.rb",
+            "**/*.java",
+            "**/*.kt",
+            "**/*.c",
+            "**/*.cc",
+            "**/*.cpp",
+            "**/*.h",
+            "**/*.zig",
+        ),
+    ],
+    skip_if=[
+        FilePath("**/test_*.py", "**/*_test.py", "**/*_test.go", "**/tests/**", "**/*.test.*", "**/*.spec.*"),
+    ],
+    when=lambda evt: not evt.is_subagent and len(evt.content or "") >= 400,
+    max_fires=1,
+    agent=False,
+    transcript=False,
+    tests={
+        Input(
+            file="src/api/users.py",
+            content="def list_users(page: int):\n    return paginate(page)\n" * 12,
+        ): Warn(pattern="opus"),
+        Input(
+            file="README.md",
+            content="Pagination lands in the users API.\n" * 20,
+        ): Allow(),
+        Input(file="src/api/users.py", old="page = 1", content="page = 2"): Allow(),
+        Input(
+            file="tests/test_users.py",
+            content="def test_list_users(page: int):\n    assert paginate(page)\n" * 12,
+        ): Allow(),
+        Input(
+            file="src/auth/middleware.py",
+            content="def refresh_token(lock: Lock):\n    with lock:\n        rotate()\n" * 12,
+            llm={"fire": False},
+        ): Allow(),
+    },
+)
+
+llm_nudge(
+    """Decide whether this delegated subagent runs code review or bug diagnosis that
+should route to gpt-5.5 instead of fable.
+
+<delegated_spawn> holds the pending Agent/Task call: its model pin (or that it inherits
+the session model, fable), agent type, and prompt.
+
+The Models rubric: code/diff review — sweeping a diff or codebase for bugs,
+correctness, or cleanups; finder and refuter passes over findings — and bug diagnosis
+route to gpt-5.5 via the codex skill; fable is the escalation target when gpt-5.5's
+output misses. Fable keeps design/architecture review, "is this the right approach"
+judgment, prose review, and the synthesis/accept-reject pass over review findings.
+
+Set fire=true only when the prompt clearly reviews code or diffs for defects, or
+diagnoses a bug, and the spawn would run on fable. Design review, approach judgment,
+synthesis over findings, and prose review are fable's lanes: fire=false. When
+uncertain, fire=false — the agent may have chosen fable deliberately, and a false
+alarm teaches it to ignore this nudge. Keep reasoning under 40 words.
+
+<examples>
+<example fire="true">
+Review the diff for correctness and concurrency issues; report findings as JSON.
+Diff review for defects — gpt-5.5's lane via codex.
+</example>
+<example fire="true">
+Adversarially refute this finding: the retry loop double-increments the counter.
+A refuter pass over a code finding is review work.
+</example>
+<example fire="true">
+Diagnose why the exporter hangs when two workers flush concurrently.
+Bug diagnosis starts on gpt-5.5; fable is the escalation target.
+</example>
+<example fire="false">
+Judge these three sharding designs and recommend one.
+Design/architecture judgment is fable's lane.
+</example>
+<example fire="false">
+Synthesize the confirmed findings and decide which to fix before release.
+The accept-reject pass over findings stays on fable.
+</example>
+<example fire="false">
+Review the README draft for factual errors.
+Prose review stays on fable.
+</example>
+</examples>""",
+    message=lambda r: (
+        f"This review/diagnosis delegation would run on fable. {r.reasoning} "
+        "Code/diff review and bug diagnosis route to gpt-5.5: run the codex skill (from a "
+        "workflow or subagent, spawn a model='sonnet', effort='low' wrapper that writes a "
+        "self-contained codex prompt), and escalate to fable only when gpt-5.5's output misses. "
+        "Design review and findings synthesis stay on fable. "
+        "See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    contexts=[DelegatedSpawn()],
+    events=Event.PreToolUse,
+    only_if=[
+        Tool("Agent|Task"),
+        ToolInput("prompt", r"(?i)\b(review|refut|adversari|audit|correctness|diagnos|root.?caus)"),
+    ],
+    skip_if=[
+        ToolInput("model", r"(?i)\b(opus|sonnet|haiku)\b"),
+        Agent("Explore|claude-code-guide"),
+    ],
+    agent=False,
+    transcript=False,
+    tests={
+        Input(prompt="Review the diff for correctness and concurrency issues"): Warn(pattern="gpt-5.5"),
+        Input(model="fable", prompt="Adversarially refute this finding: the retry loop is wrong"): Warn(
+            pattern="codex"
+        ),
+        Input(model="sonnet", prompt="Review the diff for correctness via the codex skill"): Allow(),
+        Input(prompt="fix the failing import in cli.py"): Allow(),
+        Input(agent_type="Explore", prompt="find where the review pipeline lives"): Allow(),
+        Input(
+            prompt="Synthesize the confirmed review findings and decide which to fix",
+            llm={"fire": False},
+        ): Allow(),
+    },
+)
+
 nudge(
     """
     This workflow script pins agent() steps to haiku. Reserve haiku for mechanical single-fact
@@ -422,7 +633,7 @@ Reading and classifying docs is analysis, not a prose deliverable.
         "session model or pin model: 'fable' on that stage. "
         "See CLAUDE.md § Plan Execution & Orchestration (Models)."
     ),
-    contexts=[WorkflowScriptSource()],
+    contexts=[ProseWorkflowScript()],
     events=Event.PreToolUse,
     only_if=[
         Tool("Workflow"),
@@ -445,3 +656,79 @@ Reading and classifying docs is analysis, not a prose deliverable.
         ): Allow(),
     },
 )
+
+llm_nudge(
+    """Decide whether this workflow script runs code review or bug diagnosis stages on
+fable that should route to gpt-5.5.
+
+<workflow_script> holds the pending Workflow call's script source, headed by every
+line that pins a model — a stage not quoted there carries no pin and inherits the
+session model, fable.
+
+The Models rubric: code/diff review stages — finder sweeps over a diff or codebase,
+adversarial refuters over findings — and bug diagnosis route to gpt-5.5 via the codex
+skill. A stage does that correctly when it pins model 'sonnet' at low effort and its
+prompt writes a self-contained codex prompt and runs the codex skill. Fable keeps the
+synthesis/accept-reject stage over findings and design/architecture judgment.
+
+Set fire=true only when at least one review or diagnosis stage would run on fable —
+unpinned, or pinned 'fable'. Stages already wrapped for codex, synthesis stages, and
+design judgment are routed right: fire=false. When uncertain, fire=false — a false
+alarm teaches the agent to ignore this nudge. Keep reasoning under 40 words and name
+the offending stage.
+
+<examples>
+<example fire="true">
+agent(`Sweep the diff for go-correctness issues; return findings as JSON`)
+An unpinned finder inherits fable; finder sweeps are the codex-wrapper lane.
+</example>
+<example fire="true">
+findings.map(f => agent(`Adversarially refute: ${f.title}`, {effort: 'max'}))
+Refuters over code findings inherit fable — route them through codex wrappers.
+</example>
+<example fire="false">
+agent(`Write a self-contained codex prompt reviewing this diff for correctness,
+then run the codex skill`, {model: 'sonnet', effort: 'low'})
+Already the codex wrapper — correctly routed.
+</example>
+<example fire="false">
+agent(`Synthesize the confirmed findings and decide which to fix`)
+Synthesis/accept-reject stays on fable.
+</example>
+</examples>""",
+    message=lambda r: (
+        f"This workflow runs review/diagnosis stages on fable. {r.reasoning} "
+        "Route finder, refuter, and diagnosis stages to gpt-5.5: make each a model: 'sonnet', "
+        "effort: 'low' stage that writes a self-contained codex prompt and runs the codex skill; "
+        "keep the synthesis/accept-reject stage on fable (inherit the session model). "
+        "See CLAUDE.md § Plan Execution & Orchestration (Models)."
+    ),
+    contexts=[WorkflowScriptSource()],
+    events=Event.PreToolUse,
+    only_if=[
+        Tool("Workflow"),
+        WorkflowScript(pattern=r"(?i)\b(review|refut|adversari|audit|correctness|diagnos)"),
+    ],
+    max_fires=2,
+    max_context=16_000,
+    agent=False,
+    transcript=False,
+    tests={
+        Input(script="const findings = await agent(`Sweep the diff for correctness issues; return JSON`)"): Warn(
+            pattern="codex"
+        ),
+        Input(script="agent(`Adversarially refute: ${f.title}`, {model: 'fable', effort: 'max'})"): Warn(
+            pattern="gpt-5.5"
+        ),
+        Input(
+            script="agent('Write a self-contained codex prompt reviewing this diff, "
+            "then run the codex skill', {model: 'sonnet', effort: 'low'})",
+            llm={"fire": False},
+        ): Allow(),
+        Input(script="agent('fix the failing import in cli.py')"): Allow(),
+        Input(
+            script="agent(`Synthesize the confirmed review findings and decide which to fix`)",
+            llm={"fire": False},
+        ): Allow(),
+    },
+)

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/packs/manager.py

@@ -32,7 +32,7 @@ from typing import Any
 
 from filelock import FileLock
 
-from captain_hook import state
+from captain_hook.settings import resolve_cache_dir
 from captain_hook.util import http
 
 PACK_MANIFEST = "capt-hook.toml"
@@ -209,7 +209,7 @@ def delete_entry(path: Path, name: str) -> None:
 
 
 def packs_cache_root() -> Path:
-    return state.CACHE_ROOT / "packs"
+    return resolve_cache_dir() / "packs"
 
 
 def meta_path(name: str) -> Path:

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/primitives/llm.py

@@ -9,11 +9,11 @@ from typing import TYPE_CHECKING, Any, Literal
 from loguru import logger
 from pydantic import BaseModel
 
-from captain_hook import state
 from captain_hook.app import on
 from captain_hook.contexts import apply_contexts, with_defaults
 from captain_hook.primitives.nudge import DEFAULT_FIRES
 from captain_hook.prompt import Prompt
+from captain_hook.settings import resolve_cache_dir
 from captain_hook.signals import extract_signal_context, resolve_signals, transcript_texts
 from captain_hook.state import PrimitiveState, fired_this_turn, hook_name, record_fire
 from captain_hook.types import (
@@ -27,8 +27,6 @@ from captain_hook.types import (
     Waiting,
 )
 
-FAILURE_ROOT = state.CACHE_ROOT / "failures"
-
 if TYPE_CHECKING:
     from spawnllm import TModel, TSpecialty
 
@@ -362,7 +360,9 @@ def record_prompt_check_failure(
         case _:
             argv, exit_code, stdout, stderr = None, None, "", ""
 
-    failure_path = FAILURE_ROOT / (p.stem if (p := evt.ctx.t.path) else "unknown") / f"{timestamp}.json"
+    failure_path = (
+        resolve_cache_dir() / "failures" / (p.stem if (p := evt.ctx.t.path) else "unknown") / f"{timestamp}.json"
+    )
     failure_path.parent.mkdir(parents=True, exist_ok=True)
     failure_path.write_text(
         json.dumps(

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/prompt.py

@@ -5,17 +5,16 @@ import textwrap
 from dataclasses import dataclass
 from pathlib import Path
 
+from captain_hook.state import FRAMEWORK_DIR
+
 
 def dedent_text(text: str) -> str:
     return textwrap.dedent(text).strip()
 
 
-_FRAMEWORK_DIR = Path(__file__).resolve().parent
-
-
-def _caller_dir() -> Path:
+def caller_dir() -> Path:
     frame = inspect.currentframe()
-    while frame and Path(frame.f_code.co_filename).resolve().is_relative_to(_FRAMEWORK_DIR):
+    while frame and Path(frame.f_code.co_filename).resolve().is_relative_to(FRAMEWORK_DIR):
         frame = frame.f_back
     return Path(frame.f_code.co_filename).resolve().parent if frame else Path.cwd()
 
@@ -83,7 +82,7 @@ class Prompt:
             FileNotFoundError: If no matching file exists in any searched directory.
             KeyError: If the file references a placeholder not supplied in ``**vars``.
         """
-        dirs = [Path(base) if base else _caller_dir() / "prompts", _FRAMEWORK_DIR / "prompts"]
+        dirs = [Path(base) if base else caller_dir() / "prompts", Path(FRAMEWORK_DIR) / "prompts"]
         for path in (d / f"{name}.md" for d in dirs):
             if path.is_file():
                 return cls.from_template(path.read_text(), **vars)

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/session.py

@@ -149,12 +149,6 @@ class SessionStore:
         if model not in cls.TRACKED:
             cls.TRACKED.append(model)
 
-    @classmethod
-    def untrack(cls, model: type[BaseModel]) -> None:
-        """Reverse ``track`` — primarily for test isolation."""
-        if model in cls.TRACKED:
-            cls.TRACKED.remove(model)
-
     @classmethod
     def tracked_models(cls) -> Sequence[type[BaseModel]]:
         """Return the registered tracked-state models as an immutable tuple."""

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/settings.py

@@ -32,18 +32,23 @@ DEFAULT_WAITING_TOOLS = [
 
 
 def resolve_state_dir() -> Path:
-    return Path(
-        os.environ.get("CAPTAIN_HOOK_STATE_DIR")
-        or os.environ.get("CLAUDE_HOOKS_STATE_DIR")
-        or Path.home() / ".claude" / "state"
-    )
+    return Path(os.environ.get("CAPTAIN_HOOK_STATE_DIR") or Path.home() / ".claude" / "state")
+
+
+def resolve_project_dir() -> str | None:
+    return os.environ.get("CLAUDE_PROJECT_DIR") or os.environ.get("FACTORY_PROJECT_DIR")
+
+
+def resolve_cache_home() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+
+
+def resolve_cache_dir() -> Path:
+    return resolve_cache_home() / "captain-hook"
 
 
 def resolve_log_dir() -> Path:
-    return Path(
-        os.environ.get("CAPTAIN_HOOK_LOG_DIR")
-        or Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "captain-hook" / "logs"
-    )
+    return Path(os.environ.get("CAPTAIN_HOOK_LOG_DIR") or resolve_cache_dir() / "logs")
 
 
 class HooksSettings(BaseSettings):

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/state.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import inspect
-import os
 import re
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass
@@ -24,7 +23,6 @@ if TYPE_CHECKING:
 
 FRAMEWORK_DIR = str(Path(__file__).resolve().parent)
 PACKS_DIR = str(Path(FRAMEWORK_DIR) / "packs")
-CACHE_ROOT = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "captain-hook"
 SPACY_MODEL = "en_core_web_sm"
 
 

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/testing/helpers.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 import atexit
+import functools
+import os
 import re
 import shutil
 import tempfile
-from collections.abc import Callable, Iterator
+from collections.abc import Iterator
 from contextlib import contextmanager
+from dataclasses import dataclass, field
 from itertools import count
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, cast, overload
 
 from cc_transcript.parser import parse_event
 from cc_transcript.query import Session
@@ -27,6 +30,7 @@ from captain_hook.events import (
     ToolHookEvent,
     UserPromptSubmitEvent,
 )
+from captain_hook.prompt import Prompt
 from captain_hook.session import SessionStore
 from captain_hook.testing.session_cache import SessionCache
 from captain_hook.testing.types import Allow, Block, FileFixture, Input, Rewrite, TranscriptFixture, Warn
@@ -40,16 +44,52 @@ STUB_FIELD_VALUES: dict[str, Any] = {
     "reason": "inline test stub",
 }
 
-FIXTURE_FILE_DIR: list[Path] = []
 FIXTURE_FILE_COUNTER = count()
 
 
+@dataclass
+class StubbedContext(HookContext):
+    """HookContext for inline tests: ``call_llm`` fabricates a deterministic verdict from
+    ``STUB_FIELD_VALUES`` merged with the per-test ``Input.llm`` overrides."""
+
+    llm: dict[str, Any] = field(default_factory=dict)
+
+    @overload
+    def call_llm[M: BaseModel](
+        self, template: str | Prompt, *args: Any, response_model: type[M], **kwargs: Any
+    ) -> M: ...
+    @overload
+    def call_llm(self, template: str | Prompt, *args: Any, response_model: None = None, **kwargs: Any) -> str: ...
+    def call_llm(
+        self, template: str | Prompt, *args: Any, response_model: type[BaseModel] | None = None, **kwargs: Any
+    ) -> str | BaseModel:
+        if response_model is None:
+            return "stubbed"
+        values = STUB_FIELD_VALUES | self.llm
+        return response_model(
+            **{
+                name: values.get(name, "")
+                for name, info in response_model.model_fields.items()
+                if name in values or info.default is None
+            }
+        )
+
+    @classmethod
+    def wrapping(cls, ctx: HookContext, llm: dict[str, Any] | None = None) -> StubbedContext:
+        return cls(
+            session=ctx.session,
+            transcript=ctx.transcript,
+            settings=ctx.settings,
+            project_root=ctx.project_root,
+            llm=llm or {},
+        )
+
+
+@functools.cache
 def fixture_file_dir() -> Path:
-    if not FIXTURE_FILE_DIR:
-        root = Path(tempfile.mkdtemp(prefix="capt-hook-fixture-"))
-        FIXTURE_FILE_DIR.append(root)
-        atexit.register(shutil.rmtree, root, ignore_errors=True)
-    return FIXTURE_FILE_DIR[0]
+    root = Path(tempfile.mkdtemp(prefix="capt-hook-fixture-"))
+    atexit.register(shutil.rmtree, root, ignore_errors=True)
+    return root
 
 
 def materialize_file(fixture: FileFixture) -> str:
@@ -403,13 +443,13 @@ def input_to_event(
         # injected list in inline tests — no native task store / session_id required.
         evt.__dict__["tasks"] = Tasks(tuple(Task.from_raw(t) for t in inp.tasks))
 
+    evt.ctx = StubbedContext.wrapping(evt.ctx, inp.llm)
     return evt
 
 
 def replay_session(entry: Any, jsonl: Path) -> Iterator[HookResult | None]:
     transcript = load_transcript(jsonl)
-    ctx = HookContext(session=SessionStore(None), transcript=transcript, settings=None)
-    ctx.call_llm = stub_call_llm  # type: ignore[method-assign]
+    ctx = StubbedContext(session=SessionStore(None), transcript=transcript, settings=None)
     transcript_path = str(jsonl)
 
     for ev_type in entry.spec.events:
@@ -508,42 +548,19 @@ def assert_result(
                 assert val in actual, f"{prefix}Rewrite {key}={actual!r} doesn't contain '{val}'"
 
 
-def make_stub_call_llm(overrides: dict[str, Any] | None = None) -> Callable[..., str | BaseModel]:
-    values = STUB_FIELD_VALUES | (overrides or {})
-
-    def stub_call_llm(
-        _template: Any,
-        *args: Any,
-        response_model: type[BaseModel] | None = None,
-        **kwargs: Any,
-    ) -> str | BaseModel:
-        if response_model is None:
-            return "stubbed"
-        return response_model(
-            **{
-                name: values.get(name, "")
-                for name, info in response_model.model_fields.items()
-                if name in values or info.default is None
-            }
-        )
-
-    return stub_call_llm
-
-
-stub_call_llm = make_stub_call_llm()
-
-
 @contextmanager
-def isolated_durable_root() -> Iterator[Path]:
-    """Point ``DurableState`` at a throwaway root so tests never read or write the real store."""
-    from captain_hook.durable import DURABLE_ROOT_OVERRIDE
-
-    root = Path(tempfile.mkdtemp(prefix="capt-hook-durable-"))
-    DURABLE_ROOT_OVERRIDE.append(root)
+def isolated_state_root() -> Iterator[Path]:
+    """Point the whole capt-hook state root at a throwaway dir so inline tests never touch real state."""
+    root = Path(tempfile.mkdtemp(prefix="capt-hook-state-"))
+    saved = os.environ.get("CAPTAIN_HOOK_STATE_DIR")
+    os.environ["CAPTAIN_HOOK_STATE_DIR"] = str(root)
     try:
         yield root
     finally:
-        DURABLE_ROOT_OVERRIDE.remove(root)
+        if saved is None:
+            del os.environ["CAPTAIN_HOOK_STATE_DIR"]
+        else:
+            os.environ["CAPTAIN_HOOK_STATE_DIR"] = saved
         shutil.rmtree(root, ignore_errors=True)
 
 
@@ -552,7 +569,7 @@ def run_inline_tests() -> list[tuple[str, str, bool, str]]:
 
     results: list[tuple[str, str, bool, str]] = []
 
-    with isolated_durable_root():
+    with isolated_state_root():
         for entry in _state.hooks:
             if not entry.spec.tests:
                 continue
@@ -571,7 +588,6 @@ def run_inline_tests() -> list[tuple[str, str, bool, str]]:
                             if spec_tools
                             else None,
                         )
-                        evt.ctx.call_llm = make_stub_call_llm(key.llm)  # type: ignore[assignment]
                         hook_result = (
                             execute_hook(entry, evt)
                             if matches_conditions(entry.spec, evt) and not is_planning_agent_skip(entry.spec, evt)

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/testing/session_cache.py

@@ -6,6 +6,8 @@ import shutil
 from pathlib import Path
 from typing import ClassVar
 
+from captain_hook.settings import resolve_project_dir
+
 
 class SessionCache:
     """Resolves UUID-keyed inline-test fixtures to a cached transcript jsonl.
@@ -24,7 +26,7 @@ class SessionCache:
 
     @classmethod
     def for_root(cls, root: Path | str | None = None) -> SessionCache:
-        return cls(Path(root or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()))
+        return cls(Path(root or resolve_project_dir() or os.getcwd()))
 
     def path(self, uuid: str) -> Path:
         return self.dir / f"{uuid}.jsonl"

{capt_hook-6.3.0 → capt_hook-6.4.0}/captain_hook/util/model_cache.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import functools
 import hashlib
-import os
 import re
 import shutil
 import zipfile
@@ -12,6 +11,7 @@ from typing import Any
 
 from filelock import FileLock
 
+from captain_hook.settings import resolve_cache_home
 from captain_hook.util import http
 
 MODEL_NAME = "en_core_web_sm"
@@ -19,9 +19,8 @@ WN_LEXICON = "oewn:2025"
 WHEEL_CHECKSUM = re.compile(r"Checksum \.whl:\*\*\s*`([0-9a-f]{64})`")
 
 
-@functools.cache
 def cache_root() -> Path:
-    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "spacy" / "models"
+    return resolve_cache_home() / "spacy" / "models"
 
 
 @functools.cache

{capt_hook-6.3.0 → capt_hook-6.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "capt-hook"
 # Inert sentinel — the real version is stamped from the release tag (uv version --frozen).
-version = "6.3.0"
+version = "6.4.0"
 description = "Declarative hook framework for Claude Code"
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"