capt-hook 8.0.0__tar.gz → 8.2.0__tar.gz

{capt_hook-8.0.0 → capt_hook-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 8.0.0
+Version: 8.2.0
 Summary: Stop repeating yourself to Claude.
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

capt_hook-8.2.0/captain_hook/packs/general/capt-hook.toml

@@ -0,0 +1,5 @@
+name = "general"
+version = "0.13.0"
+description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, model-routing nudges (review, security audit, and diagnosis route to gpt-5.5), code-review + docs-freshness gates, a detour check-in nudge, a verbose-comment nudge, and delegated-prose nudges that catch doc writing handed to a subagent or workflow without the writing-docs skill."
+hooks = "."
+nlp = true

{capt_hook-8.0.0 → capt_hook-8.2.0}/captain_hook/packs/general/models.py

@@ -321,7 +321,8 @@ The Models rubric: implementation delegates to opus-4.8 at xhigh — opus is ~2x
 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.
+Code/diff review, security review/audit, and bug diagnosis have their own gpt-5.5
+lanes with separate nudges.
 
 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,
@@ -476,20 +477,25 @@ Auth plus concurrency is a sensitive surface — fable's inline lane.
 )
 
 llm_nudge(
-    """Decide whether this delegated subagent runs code review or bug diagnosis that
-should route to gpt-5.5 instead of fable.
+    """Decide whether this delegated subagent runs code review, a security review/audit
+or verification of security-sensitive code, 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,
+correctness, or cleanups; finder and refuter passes over findings — security
+review/audit and verification of security-sensitive code (auth, input validation,
+crypto, secrets), 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, the synthesis/
+accept-reject pass over review findings — and security-sensitive implementation,
+which is not review.
+
+Set fire=true only when the prompt clearly reviews code or diffs for defects, audits
+or verifies security-sensitive code, 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.
@@ -519,10 +525,23 @@ The accept-reject pass over findings stays on fable.
 Review the README draft for factual errors.
 Prose review stays on fable.
 </example>
+<example fire="true">
+Audit the session-token handling in auth/middleware.py for vulnerabilities.
+Security review/audit of code — gpt-5.5's lane via codex.
+</example>
+<example fire="true">
+Verify the new input-validation layer rejects path traversal and injection payloads.
+Verification of security-sensitive code routes to gpt-5.5.
+</example>
+<example fire="false">
+Implement mitigations for the security-audit findings in auth.py.
+Security-sensitive implementation, not review — the implementation lanes apply.
+</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 "
+        "Code/diff review, security review/audit and verification of security-sensitive code, "
+        "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. "
@@ -532,7 +551,11 @@ Prose review stays on fable.
     events=Event.PreToolUse,
     only_if=[
         Tool("Agent|Task"),
-        ToolInput("prompt", r"(?i)\b(review|refut|adversari|audit|correctness|diagnos|root.?caus)"),
+        ToolInput(
+            "prompt",
+            r"(?i)(\b(review|refut|adversari|audit|correctness|diagnos|root.?caus|secur|vuln|pentest)"
+            r"|\bverif\w*[\s\S]{0,160}?\b(auth|crypt|secret|sanitiz|inject|input.?valid|token|session))",
+        ),
     ],
     skip_if=[
         ToolInput("model", r"(?i)\b(opus|sonnet|haiku)\b"),
@@ -552,6 +575,13 @@ Prose review stays on fable.
             prompt="Synthesize the confirmed review findings and decide which to fix",
             llm={"fire": False},
         ): Allow(),
+        Input(prompt="Audit auth/session.py for security vulnerabilities"): Warn(pattern="gpt-5.5"),
+        Input(prompt="Verify the input-validation change blocks path traversal"): Warn(pattern="codex"),
+        Input(prompt="Verify the pagination change renders the last page correctly"): Allow(),
+        Input(
+            prompt="Implement mitigations for the security audit findings in auth.py",
+            llm={"fire": False},
+        ): Allow(),
     },
 )
 
@@ -666,10 +696,13 @@ line that pins a model — a stage not quoted there carries no pin and inherits
 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.
+adversarial refuters over findings — security review/audit stages and verification
+of security-sensitive code (auth, input validation, crypto, secrets), 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 — and security-sensitive implementation, which is
+not review.
 
 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
@@ -695,10 +728,14 @@ Already the codex wrapper — correctly routed.
 agent(`Synthesize the confirmed findings and decide which to fix`)
 Synthesis/accept-reject stays on fable.
 </example>
+<example fire="true">
+agent(`Audit the auth flow for injection and session-fixation issues; return findings as JSON`)
+An unpinned security audit inherits fable; security review/audit is the codex-wrapper lane.
+</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', "
+        "Route finder, refuter, security-audit, 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)."
@@ -707,7 +744,10 @@ Synthesis/accept-reject stays on fable.
     events=Event.PreToolUse,
     only_if=[
         Tool("Workflow"),
-        WorkflowScript(pattern=r"(?i)\b(review|refut|adversari|audit|correctness|diagnos)"),
+        WorkflowScript(
+            pattern=r"(?i)(\b(review|refut|adversari|audit|correctness|diagnos|root.?caus|secur|vuln|pentest)"
+            r"|\bverif\w*[\s\S]{0,160}?\b(auth|crypt|secret|sanitiz|inject|input.?valid|token|session))",
+        ),
     ],
     max_fires=2,
     max_context=16_000,
@@ -730,5 +770,154 @@ Synthesis/accept-reject stays on fable.
             script="agent(`Synthesize the confirmed review findings and decide which to fix`)",
             llm={"fire": False},
         ): Allow(),
+        Input(
+            script="agent(`Audit the login flow for auth bypass and injection; return findings as JSON`)"
+        ): Warn(pattern="gpt-5.5"),
+        Input(script="agent('Verify the CLI renders the last page correctly')"): Allow(),
+    },
+)
+
+llm_nudge(
+    """Decide whether this delegated subagent call delegates documentation or prose
+writing without directing the subagent to read the writing-docs skill.
+
+<delegated_spawn> holds the pending Agent/Task call: its model pin, agent type, and
+prompt, ending with the sentences a clause prefilter matched — each asks a writing verb
+of a prose artifact, with negated asks ("do NOT edit the docs") already screened out.
+
+You are watching an orchestrating agent spawn a subagent. Decide whether the pending
+prompt delegates documentation or prose writing — a README, docs page, CHANGELOG,
+tutorial, release notes, or similar deliverable — without directing the subagent to
+read the writing-docs skill. Restated style rules ('technical-builder voice', 'no hype
+adjectives', 'first person, confident') do not count as reading the skill; that
+paraphrase is exactly the failure to catch. Fire only when the prompt's deliverable is
+prose the writing-docs skill governs. Do not fire for code work that incidentally
+mentions a doc file, for reading or reviewing docs without writing them, or for a prompt
+that already tells the agent to read the skill or its references.
+
+When uncertain, fire=false — a false alarm teaches the agent to ignore this nudge. Keep
+reasoning under 40 words.
+
+<examples>
+<example fire="true">
+Rewrite the README for this repo. You are fable; technical-builder voice, no hype adjectives.
+README prose with the style rules paraphrased in place of the skill — the drift this catches.
+</example>
+<example fire="true">
+Draft the release notes for v2. Keep it first-person and confident, no marketing fluff.
+Release-notes prose; restated voice rules, no pointer to the writing-docs skill.
+</example>
+<example fire="false">
+Fix the failing test in cli.py; the README already documents the new flag.
+Code work that only mentions the README — no prose is produced.
+</example>
+<example fire="false">
+Rewrite the README, but read the doc-writing skill and its references first.
+Already directs the subagent to the skill — nothing to nudge.
+</example>
+</examples>""",
+    message=lambda r: (
+        "This prompt delegates prose but paraphrases the writing rules instead of pointing at them. "
+        f"{r.reasoning} A paraphrase drifts and silently overrides the skill — rewrite the prompt to "
+        "direct the agent to READ the writing-docs skill and its references (the installed plugin under "
+        "~/.claude/plugins/cache/skills/writing-docs, or plugins/writing-docs in the cc-skills repo) "
+        "before it writes."
+    ),
+    contexts=[ProseSpawn()],
+    events=Event.PreToolUse,
+    only_if=[Tool("Agent|Task")],
+    skip_if=[
+        ToolInput("prompt", r"(?i)writing-docs"),
+        Agent("Explore|claude-code-guide"),
+    ],
+    max_context=16_000,
+    agent=False,
+    transcript=False,
+    tests={
+        Input(
+            prompt="Rewrite the README of /repo. You are fable; technical-builder voice, no hype "
+            "adjectives. Verify commands against the binary."
+        ): Warn(pattern="writing-docs"),
+        Input(
+            prompt="Rewrite the README of /repo; technical-builder voice, no hype adjectives. Read "
+            "the writing-docs skill at ~/.claude/plugins/cache/skills/writing-docs first."
+        ): Allow(),
+        Input(prompt="Fix the race in daemon.go; update the failing test"): Allow(),
+        Input(
+            prompt="Rewrite the README, but read the doc-writing skill and its references first",
+            llm={"fire": False},
+        ): Allow(),
+    },
+)
+
+llm_nudge(
+    """Decide whether this workflow script delegates documentation or prose writing to an
+agent() stage without directing that subagent to read the writing-docs skill.
+
+<workflow_script> holds the pending Workflow call's script source, headed by every line
+that pins a model, followed by the sentences a clause prefilter matched — each asks a
+writing verb of a prose artifact, with negated asks ("do NOT edit CHANGELOG.md") already
+screened out.
+
+Decide whether an agent() prompt delegates documentation or prose writing — a README,
+docs page, CHANGELOG, tutorial, release notes, or similar deliverable — without
+directing that subagent to read the writing-docs skill. Restated style rules
+('technical-builder voice', 'no hype adjectives', 'first person, confident') do not
+count as reading the skill; that paraphrase is exactly the failure to catch. Fire only
+when a stage's deliverable is prose the writing-docs skill governs. Do not fire for code
+work that incidentally mentions a doc file, for reading or reviewing docs without writing
+them, or for a stage that already tells its subagent to read the skill or its references.
+
+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('Rewrite the README for the new CLI. Technical-builder voice, no hype adjectives', {model: 'opus'})
+The stage's deliverable is README prose with the style rules paraphrased in place of the skill.
+</example>
+<example fire="true">
+agent(`Draft the docs-site page for ${feature}. First-person, confident, no marketing fluff`)
+A docs page delegated with restated voice rules and no pointer to the writing-docs skill.
+</example>
+<example fire="false">
+agent('Fix the failing import in cli.py; the README already documents the flag', {model: 'opus'})
+Code work that only mentions the README — no prose is produced.
+</example>
+<example fire="false">
+agent('Rewrite the troubleshooting guide, but read the doc-writing skill and its references first')
+The stage already directs its subagent to the skill — nothing to nudge.
+</example>
+</examples>""",
+    message=lambda r: (
+        "This workflow script delegates prose but paraphrases the writing rules instead of pointing at "
+        f"them. {r.reasoning} A paraphrase drifts and silently overrides the skill — rewrite the offending "
+        "agent() prompt to direct its subagent to READ the writing-docs skill and its references (the "
+        "installed plugin under ~/.claude/plugins/cache/skills/writing-docs, or plugins/writing-docs in "
+        "the cc-skills repo) before it writes."
+    ),
+    contexts=[ProseWorkflowScript()],
+    events=Event.PreToolUse,
+    only_if=[Tool("Workflow")],
+    skip_if=[WorkflowScript(pattern=r"(?i)writing-docs")],
+    max_fires=2,
+    max_context=16_000,
+    agent=False,
+    transcript=False,
+    tests={
+        Input(
+            script="agent('Rewrite the README. You are fable; technical-builder voice, no hype "
+            "adjectives', {model: 'opus'})"
+        ): Warn(pattern="writing-docs"),
+        Input(
+            script="agent('Rewrite the README per the writing-docs skill at "
+            "~/.claude/plugins/cache/skills/writing-docs', {model: 'opus'})"
+        ): Allow(),
+        Input(script="agent('Fix the race in daemon.go; update the failing test')"): Allow(),
+        Input(
+            script="agent('Rewrite the README, but read the doc-writing skill and its references "
+            "first', {model: 'opus'})",
+            llm={"fire": False},
+        ): Allow(),
     },
 )

{capt_hook-8.0.0 → capt_hook-8.2.0}/captain_hook/packs/general/prompts.py

@@ -24,6 +24,7 @@ nudge(
     skip_if=[
         UsedSkill("llm-prompts"),
         UsedSkill("slop-cop-check", "slop-cop-prose"),
+        Content(r"\.count_tokens\(", project_only=False),
     ],
     tests={
         Input(
@@ -31,5 +32,14 @@ nudge(
         ): Warn(),
         Input(file="prompt.md", content="<instruction>\nSummarize the document.\n</instruction>\n"): Warn(),
         Input(file="util.py", content="def add(a, b):\n    return a + b\n"): Allow(),
+        Input(
+            file="tokens.py",
+            content=(
+                "def api_count(text: str, model: str) -> int:\n"
+                "    resp = client.messages.count_tokens(\n"
+                '        model=model,\n        messages=[{"role": "user", "content": text or " "}],\n'
+                "    )\n    return int(resp.input_tokens)\n"
+            ),
+        ): Allow(),
     },
 )

{capt_hook-8.0.0 → capt_hook-8.2.0}/captain_hook/packs/general/tasks.py

@@ -55,6 +55,13 @@ class DriftedFromTasks(CustomCondition):
         return since.tool_calls.named("Bash|Grep|Glob|WebSearch|WebFetch|LSP|Skill").count() >= TASK_DRIFT_THRESHOLD
 
 
+class TaskNotification(CustomCondition):
+    """Matches when the prompt is a system-injected background-task report, not free-form user text."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return (evt.user_prompt or "").strip().startswith("<task-notification>")
+
+
 gate(
     "Open tasks remain. Before stopping, mark each finished task status='completed' via the "
     "TaskUpdate tool (add a note if you're deliberately deferring one), or output "
@@ -120,7 +127,7 @@ nudge(
 nudge(
     "This message has several distinct requests. Use the TaskCreate tool for each item "
     "before starting work, so none gets dropped. See: CLAUDE.md § Task Tracking.",
-    skip_if=[InPlanMode()],
+    skip_if=[InPlanMode(), TaskNotification()],
     events=Event.UserPromptSubmit,
     signals=Signals(
         [
@@ -141,5 +148,12 @@ nudge(
         Input(prompt="1. add foo\n2. fix bar\n3. update baz"): Warn(),
         Input(prompt="just fix the typo"): Allow(),
         Input(prompt="1. add foo\n2. fix bar\n3. update baz", permission_mode="plan"): Allow(),
+        Input(
+            prompt=(
+                "<task-notification>\n<task-id>abc</task-id>\n<status>completed</status>\n"
+                "<summary>Agent finished</summary>\n<result>\n- `cc-transcript` -> version 7.0.1\n"
+                "- `spawnllm` -> version 0.5.2\n</result>\n</task-notification>"
+            )
+        ): Allow(),
     },
 )

capt_hook-8.2.0/captain_hook/packs/steering/capt-hook.toml

@@ -0,0 +1,5 @@
+name = "steering"
+version = "0.4.0"
+description = "Steer the agent's judgment on what's worth fixing: prefer fundamental, first-principles fixes over band-aids, don't dismiss a real pre-existing issue, don't chase trivial type noise, and don't defer the requested fix by swapping in docs or a follow-up nobody asked for."
+hooks = "."
+nlp = true