capt-hook 7.0.0__tar.gz → 8.1.0__tar.gz

{capt_hook-7.0.0 → capt_hook-8.1.0}/PKG-INFO

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

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

@@ -0,0 +1,5 @@
+name = "general"
+version = "0.12.0"
+description = "Language-agnostic guards: git/command safety, doc & prompt nudges, task & plan discipline, 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.1.0/captain_hook/packs/general/comments.py

@@ -0,0 +1,160 @@
+"""Discourage verbose comments: warn when an edit introduces a long comment or line-comment run.
+
+Comments should be terse and used sparingly — names, types, and organization carry the
+meaning. The one legitimate exception is documentation-generation comments (godoc, rustdoc,
+docstrings), and even a long doc run trips this warn by design: the threshold is deliberately
+strict so verbosity of any kind gets a nudge. Language-agnostic via the tree-sitter comment
+kinds in :data:`~captain_hook.ast_grep.COMMENT_TYPES`; diff-based, so only comments the edit
+*introduces* count — a pre-existing long comment re-saved unchanged never fires.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from captain_hook import (
+    Allow,
+    BaseHookEvent,
+    CustomCondition,
+    Event,
+    FileFixture,
+    Input,
+    Tool,
+    Warn,
+    nudge,
+)
+from captain_hook.ast_grep import introduced_comments, lang_for_path
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from captain_hook.ast_grep import Match
+
+MAX_COMMENT_LINES = 4
+MAX_COMMENT_CHARS = 300
+
+# Fixtures for the inline tests — kept as module constants so each physical line stays short.
+GO_NO_COMMENT = "package p\n\nfunc F() {}\n"
+GO_ONE_LINE_DOC = "package p\n\n// F does a thing.\nfunc F() {}\n"
+GO_THREE_LINE_DOC = (
+    "package p\n\n// F does a thing.\n// It handles the empty case.\n// Returns an error otherwise.\nfunc F() {}\n"
+)
+GO_LONG_RUN = (
+    "package p\n\nfunc F() {\n"
+    "\t// explanation line one goes here\n"
+    "\t// explanation line two goes here\n"
+    "\t// explanation line three is here\n"
+    "\t// explanation line four is here\n"
+    "\t// explanation line five is here\n"
+    "\t// explanation line six is here ok\n"
+    "\tx := 1\n}\n"
+)
+GO_EXISTING_OLD = "func F() {\n\t// aaa\n\t// bbb\n\t// ccc\n\t// ddd\n\t// eee\n\t// fff\n\tx := 1\n}\n"
+GO_EXISTING_NEW = "func F() {\n\t// aaa\n\t// bbb\n\t// ccc\n\t// ddd\n\t// eee\n\t// fff\n\tx := 2\n}\n"
+GO_WRITE_PLAIN = "package p\n\nvar x = 1\n"
+GO_WRITE_RUN = (
+    "package p\n\n"
+    "// note one here\n// note two here\n// note three here\n"
+    "// note four here\n// note five here\n// note six here\n"
+    "var x = 1\n"
+)
+GO_WRITE_EXISTING_OLD = "package p\n\n// aaa\n// bbb\n// ccc\n// ddd\n// eee\n// fff\nvar x = 1\n"
+GO_WRITE_EXISTING_NEW = "package p\n\n// aaa\n// bbb\n// ccc\n// ddd\n// eee\n// fff\nvar x = 2\n"
+RS_LONG_BLOCK = "/*\n one\n two\n three\n four\n five\n six\n seven\n eight\n*/\nfn f() {}\n"
+RS_LONG_DOC = (
+    "/// line one of the rustdoc here\n"
+    "/// line two of the rustdoc here\n"
+    "/// line three of the rustdoc\n"
+    "/// line four of the rustdoc\n"
+    "/// line five of the rustdoc\n"
+    "/// line six of the rustdoc ok\n"
+    "pub fn f() {}\n"
+)
+PY_LONG_RUN = (
+    "# note one here\n# note two here\n# note three here\n# note four here\n# note five here\n# note six here\nx = 1\n"
+)
+PY_LONG_DOCSTRING = (
+    'def f():\n    """\n'
+    "    line one\n    line two\n    line three\n"
+    "    line four\n    line five\n    line six\n"
+    '    """\n    return 1\n'
+)
+
+
+def runs(matches: Iterable[Match]) -> list[list[Match]]:
+    """Group comments into runs of adjacent lines — a block comment, or consecutive line
+    comments with no code between — each a list of :class:`Match` in document order."""
+    grouped: list[list[Match]] = []
+    for m in sorted(matches, key=lambda c: c.line):
+        if grouped and m.line <= grouped[-1][-1].end_line + 1:
+            grouped[-1].append(m)
+        else:
+            grouped.append([m])
+    return grouped
+
+
+def too_long(run: list[Match]) -> bool:
+    """Whether a comment run exceeds the line or character budget."""
+    lines = run[-1].end_line - run[0].line + 1
+    chars = sum(len(m.text) for m in run)
+    return lines > MAX_COMMENT_LINES or chars > MAX_COMMENT_CHARS
+
+
+class LongCommentIntroduced(CustomCondition):
+    """True when the pending edit introduces a comment (or adjacent line-comment run) past
+    the length budget. Diffs the edit's pre-image against its new text, so a comment already
+    present before the edit never counts; files whose language ast-grep can't parse yield False."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        if (
+            not (file := evt.file)
+            or not (lang := lang_for_path(file.path))
+            or (old := evt.replaced) is None
+            or (new := evt.content) is None
+        ):
+            return False
+        return any(too_long(run) for run in runs(introduced_comments(old, new, lang)))
+
+
+nudge(
+    "Verbose comment introduced. Comments should be terse and used sparingly — let names, "
+    "types, and organization document the code. Keep documentation-generation comments "
+    "(godoc / rustdoc / docstrings) to a real description, and drop long inline commentary "
+    "or anything that restates the code. See: STYLEGUIDE.md § Comments.",
+    only_if=[Tool("Edit", "Write", "MultiEdit"), LongCommentIntroduced()],
+    events=Event.PreToolUse,
+    tests={
+        # Short / within-budget comments — allowed.
+        Input(file="doc.go", old=GO_NO_COMMENT, content=GO_ONE_LINE_DOC): Allow(),
+        Input(file="doc.go", old=GO_NO_COMMENT, content=GO_THREE_LINE_DOC): Allow(),
+        Input(file="m.py", old="x = 1\n", content="# set x\nx = 1\n"): Allow(),
+        Input(file="lib.rs", old="pub fn f() {}\n", content="/// Builds a widget.\npub fn f() {}\n"): Allow(),
+        # Long introduced comment runs — warned.
+        Input(file="svc.go", old="package p\n\nfunc F() {\n\tx := 1\n}\n", content=GO_LONG_RUN): Warn(
+            pattern="Verbose comment"
+        ),  # 6-line // run > 4 lines
+        Input(file="big.go", old=GO_NO_COMMENT, content="package p\n\n// " + "x" * 320 + "\nfunc F() {}\n"): Warn(
+            pattern="Verbose comment"
+        ),  # single line, > 300 chars
+        Input(file="lib.rs", old="fn f() {}\n", content=RS_LONG_BLOCK): Warn(pattern="Verbose comment"),
+        Input(file="lib.rs", old="pub fn f() {}\n", content=RS_LONG_DOC): Warn(
+            pattern="Verbose comment"
+        ),  # long rustdoc run also warns (strict threshold, by design)
+        Input(file="m.py", old="x = 1\n", content=PY_LONG_RUN): Warn(pattern="Verbose comment"),
+        # Diff-gating: a pre-existing long run re-saved unchanged does not fire.
+        Input(file="svc.go", old=GO_EXISTING_OLD, content=GO_EXISTING_NEW): Allow(),
+        # Python docstrings are string nodes, not comments — never trip this.
+        Input(file="m.py", old="def f():\n    return 1\n", content=PY_LONG_DOCSTRING): Allow(),
+        # Write tool: pre-image comes from disk at PreToolUse.
+        Input(
+            tool="Write",
+            file=FileFixture(name="cmt_new.go", content=GO_WRITE_PLAIN),
+            content=GO_WRITE_RUN,
+        ): Warn(pattern="Verbose comment"),  # long run added to existing file
+        Input(
+            tool="Write",
+            file=FileFixture(name="cmt_pre.go", content=GO_WRITE_EXISTING_OLD),
+            content=GO_WRITE_EXISTING_NEW,
+        ): Allow(),  # run already on disk: not introduced
+    },
+)

{capt_hook-7.0.0 → capt_hook-8.1.0}/captain_hook/packs/general/models.py

@@ -732,3 +732,148 @@ Synthesis/accept-reject stays on fable.
         ): 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-7.0.0 → capt_hook-8.1.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-7.0.0 → capt_hook-8.1.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.1.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