capt-hook 0.2.0__py3-none-any.whl

capt_hook-0.2.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: capt-hook
+Version: 0.2.0
+Summary: Declarative hook framework for Claude Code
+Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: tree-sitter>=0.24
+Requires-Dist: tree-sitter-bash>=0.23
+Requires-Dist: funcy>=2.0
+Requires-Dist: spacy>=3.7
+Requires-Dist: click>=8
+Requires-Dist: orjsonl>=1.0
+Requires-Dist: wn>=1.1.0
+Requires-Dist: lazy-object-proxy>=1.12.0
+Requires-Dist: filelock>=3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
+Requires-Dist: pyright>=1.1 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/yasyf/captain-hook
+Project-URL: Documentation, https://captain-hook.readthedocs.io
+Project-URL: Repository, https://github.com/yasyf/captain-hook
+Project-URL: Issues, https://github.com/yasyf/captain-hook/issues
+Project-URL: Changelog, https://github.com/yasyf/captain-hook/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# captain-hook
+
+[![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
+[![Docs](https://readthedocs.org/projects/captain-hook/badge/?version=latest)](https://captain-hook.readthedocs.io)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
+
+Declarative hook framework for Claude Code. Write hooks as data, test them inline, and ship them to CI in the same shape they run in production.
+
+## Install
+
+No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+
+```bash
+uvx capt-hook init
+```
+
+`uvx` fetches captain-hook into a throwaway environment and runs it, so you never add it to `pyproject.toml`. Every command below works the same way: prefix it with `uvx`.
+
+## First hook
+
+Scaffold a project and drop a hook into `.claude/hooks/`:
+
+```bash
+uvx capt-hook init
+```
+
+```python
+# .claude/hooks/my_first.py
+from captain_hook import Allow, Block, Input, block_command
+
+block_command(
+    ["git", "stash"],
+    reason="Use the team's VCS workflow for shelving changes",
+    hint="Commit a WIP change instead of stashing",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git stash pop"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+```
+
+Run the inline tests (from your project root, `--hooks` defaults to `.claude/hooks`):
+
+```bash
+capt-hook test
+```
+
+Wire the hook into Claude Code's settings:
+
+```bash
+capt-hook generate-settings > .claude/settings.local.json
+```
+
+The next time Claude tries `git stash`, captain-hook returns a deny with your reason and hint.
+
+## What problems does this solve?
+
+- **Block dangerous tool calls** before they execute (`PreToolUse`) — force-push, package-manager footguns, raw `rm -rf`.
+- **Drive the agent with feedback** that fires on patterns it actually emits — repeated failures, weakened tests, missed conventions.
+- **Enforce multi-step workflows** with stop-gates and artifact validation, so the agent can't declare "done" without running tests / writing a report / completing a checklist.
+- **Keep all of the above testable** — every hook ships with inline `tests = {...}` that `capt-hook test` runs in CI, so you catch broken hooks the same way you catch broken code.
+
+## Docs
+
+[Read the docs](https://captain-hook.readthedocs.io) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
+
+Working on captain-hook itself? See the [development guide](https://captain-hook.readthedocs.io/en/latest/development/).

capt_hook-0.2.0.dist-info/RECORD

@@ -0,0 +1,57 @@
+captain_hook/__init__.py,sha256=RL8jYrgmj2IytXDcahy5-7Fpltyb1Gn50N-Dqt4ITz4,5296
+captain_hook/__main__.py,sha256=hEH9dZ-8Pjkvo_7R0CxrFhOqoIInJsQXBS8juX5njmA,109
+captain_hook/app.py,sha256=MdVxSzsU4nbZKFSq5DmgygBK6djLL-F-Cv6fBT-aIVM,8280
+captain_hook/classifiers/__init__.py,sha256=no9aueVb1xDrZm-K_m4f0nwVER1-yKcn5t39zVRxEC8,937
+captain_hook/classifiers/conductor.py,sha256=eGLWZUVYZhBBNefGeRMyuWWYSiPjSF-957qn1boUkJw,935
+captain_hook/classifiers/droid.py,sha256=ZOKMibF_dkz_aA0Dk6c2f-YEmNEFfkXwU7D6IrGjoKI,470
+captain_hook/classifiers/native.py,sha256=m3BadgALOa5F27RbXfUev267vkikB-ILuhCpqlqjnQI,429
+captain_hook/cli.py,sha256=7ab-55C1moBo4lmGRk3yuRynDOaxpI85f9UftqTH5f8,12719
+captain_hook/command.py,sha256=VXA-nYV54TueUQHM8B360ixwldazUepl7ccFX7CnMDs,12062
+captain_hook/conditions.py,sha256=I_YDuxar0BTIAUZf0xiE_fYQUSiL2nTUQyBtl4s8-rM,5147
+captain_hook/context.py,sha256=eM33G-3cXy1ADM0WM0enLexfLeW6DoI86mpvmfy5-xM,5329
+captain_hook/dispatch.py,sha256=ApA7lpfbHCjTBbwNmeAmL0kcC9UIQj5maM4qFa05IIg,3682
+captain_hook/events.py,sha256=IO2qIw0x5egR9rKPmWtYCmrBbxQNXFU_6eK3SgJxcYI,9178
+captain_hook/file.py,sha256=Ra5GIQAtX1E1SzJeL6MBSjCX1DvmOU7ElbeFYZ7_b-s,3703
+captain_hook/llm/__init__.py,sha256=qP68o812YaLw9f7zuw6EzeqSoiMP260XsPX_xHNI58s,489
+captain_hook/llm/backends.py,sha256=QVPuBbYqkgS4x7_iGY-dqR34Z2Ny1yXWROrb8RO_cCA,5153
+captain_hook/loader.py,sha256=ARQg4QioeSM_qaMfIWJLCN4gn1Pkl8p7kU4JIDYYp-k,2050
+captain_hook/log.py,sha256=K6zoMG4GlwZxSjUeFhzU7zcJD20cLogdGnSqT_HRo-4,2041
+captain_hook/primitives/__init__.py,sha256=pHZJx8o76AcAFvbjD1RUyutHrJGWUes8YGVCZFikEH0,1452
+captain_hook/primitives/audit.py,sha256=Am4QaRNAUltJmZDd5EYrUxpb-jgjJ3s2loSFUCjhwZg,2690
+captain_hook/primitives/commands.py,sha256=tIrjj0ZP8mJDRlNLHGXPofWXdvWDdAz4D0T-wAYqiOA,1997
+captain_hook/primitives/lint.py,sha256=j_-KSx1xdAz3jvCizLAm2REmvPYtYoyYUyCy9y-5uQo,6036
+captain_hook/primitives/llm.py,sha256=3Sj1Y8ucHXWvgIGJ1AedMQh7M_-Tcg0_bwdMG7Z-04I,11630
+captain_hook/primitives/nudge.py,sha256=kcNd21q33PtEsdo8dUVWlZIxYCcHM1H2xJg0TXbn1F0,3080
+captain_hook/prompt.py,sha256=IWAiwO7p_gvqmSlyduO1zRDJ7U6ehuRx_V-9QQBeV2M,3856
+captain_hook/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+captain_hook/session.py,sha256=TcKWUBgPCkL-7hjusj9gLP0vzM2kouG1QKhNwuWwPHE,5168
+captain_hook/settings.py,sha256=X4gE2q_Pn3Pk6f23pN-N_jY9UJrpm5m7ZYzlLCfSZNA,4287
+captain_hook/signals/__init__.py,sha256=5hnfY_JIJPSUCApaELgRv6xZglqoBDe3wGHujLKup_M,2627
+captain_hook/signals/nlp.py,sha256=VG_j_wQWRqpaf8kMpKW7HkJriElvgF9hm3_yr4VNh_4,3101
+captain_hook/state.py,sha256=YLlVufek_znf71JwlbD14Mc_mr4ZjNzU7hJvo0tVwTo,7784
+captain_hook/styleguide/__init__.py,sha256=bp1nMY-VHDG8m1qWw3C4WN5uulGKHnr6Xdq3xMWVJoM,5743
+captain_hook/styleguide/query.py,sha256=FG_NeEbEpTqxZHVP4QhJx8H2RV9T1Xmqa-nDwjgKVfE,9727
+captain_hook/styleguide/scope.py,sha256=5w63viRLmrsZtzjShT80tAxFrHGHuoec73Z91eJwegc,1512
+captain_hook/styleguide/types.py,sha256=rvWI_nJxt_kz-gVz-bWodT4LoIt4_vxzMJXAx8hvOhE,2208
+captain_hook/tasks.py,sha256=DsA1fuLd0mA9ijaOFFE7tUhbEgNSvzrBWazdd7N888w,3823
+captain_hook/templates/example_hook.py.tmpl,sha256=yZ2Sv5hyPj-ImJ4B7YdpBm2YWBQyDCo2auZT-0au8iU,2528
+captain_hook/testing/__init__.py,sha256=KkhH4Ue6mG5T1GZWgX_KiejwFfRvv7dMmIm8yTaBQxU,207
+captain_hook/testing/helpers.py,sha256=xnsE980beW5nNBefGweDKTJE3X2IpV-TzrgWNUkFx7Y,14369
+captain_hook/testing/session_cache.py,sha256=lwJJiPpga7fFhjq42SFPb3ZAJuqfwQDfFFTmLDzT7vs,1670
+captain_hook/testing/types.py,sha256=vW_XeBa3Jo-U-TCCRICmheasTpa5z7zOwZ_iCUmIDFQ,2693
+captain_hook/tests/__init__.py,sha256=aHSeWHUg6RL-gOQ5oSSLTm9Ns6VzMNCbuHB-Y9xA3jQ,556
+captain_hook/tests/helpers.py,sha256=IH1mToIPnn9WW-CXqW1rs-VDGlgZdqVIXoRXBmd7c7A,12035
+captain_hook/tools.py,sha256=ApuR4J55arQLB8XkgwBRQZ4-VlgA_r0XYGsUrjHammU,1870
+captain_hook/transcript/__init__.py,sha256=tCkUuosCweaRSwUmJ8ikY7KQn7nxWi5vNl0qOZt7nGI,18372
+captain_hook/transcript/inputs.py,sha256=f-fqnr97NrbdMHhmvXLHRNxqFDNXR0gaNKb-MGLurJ4,5851
+captain_hook/transcript/models.py,sha256=4e42sksQWX4-MR6NqZW6qdq3dS7ycFSWAjOGB3eRzhI,5562
+captain_hook/types.py,sha256=CMjeb3lsX7ST5NrfW5xmMMLt0n-7QF5Dw8fEEBHW_5I,10402
+captain_hook/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+captain_hook/util/model_cache.py,sha256=FKTwxDgCV79T1yGr4oNGP1JbEkK6k5_L8m6uFV3vh7U,3028
+captain_hook/utils.py,sha256=075Nmbi6gjpiIVJV3Dy9hTW66fjh9ydAB5JyENo6OCg,806
+captain_hook/workflow.py,sha256=hCtk_DfvIAgKYFnl-K1HxORh_vEuB3eAZ1hKtrLTbY0,3935
+capt_hook-0.2.0.dist-info/licenses/LICENSE,sha256=wOpKiW0sjDlLKflCdYmZbbgmzVAcUSJ5_w7T70j6u-U,4563
+capt_hook-0.2.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+capt_hook-0.2.0.dist-info/entry_points.txt,sha256=DdwVxxc-bC71FAijHjN8BSXVkgdU_So2DT8IPLZDcco,53
+capt_hook-0.2.0.dist-info/METADATA,sha256=JE_0jd8L6vf1IHp0rRs4rgNesc3t_9pjzdV02cibNcs,4496
+capt_hook-0.2.0.dist-info/RECORD,,

capt_hook-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.19
+Root-Is-Purelib: true
+Tag: py3-none-any

capt_hook-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+capt-hook = captain_hook.cli:main
+

capt_hook-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

captain_hook/__init__.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from captain_hook.app import hook, on, register
+from captain_hook.cli import generate_settings, generate_settings_json
+from captain_hook.command import Command, CommandLine, Redirect
+from captain_hook.context import HookContext
+from captain_hook.events import (
+    BaseHookEvent,
+    NotificationEvent,
+    PostToolUseEvent,
+    PostToolUseFailureEvent,
+    PreCompactEvent,
+    PreToolUseEvent,
+    StopEvent,
+    SubagentStartEvent,
+    SubagentStopEvent,
+    ToolHookEvent,
+    UserPromptSubmitEvent,
+)
+from captain_hook.file import File, PathMatcher, categorize_files
+from captain_hook.primitives import (
+    GateVerdict,
+    NudgeVerdict,
+    PromptCheckVerdict,
+    audit,
+    block_command,
+    diff_lint,
+    gate,
+    lint,
+    llm_gate,
+    llm_nudge,
+    nudge,
+    prompt_check,
+    session_id_for,
+    styleguide,
+    warn_command,
+)
+from captain_hook.primitives.llm import llm_evaluate
+from captain_hook.prompt import Prompt, PromptMessage
+from captain_hook.session import SessionSlot, SessionStore, session_state
+from captain_hook.settings import AutoConf, HooksSettings, build_settings
+from captain_hook.signals import cite_message, extract_signal_context, resolve_signals, score_signals, transcript_texts
+from captain_hook.signals.nlp import Clause, NlpSignal, Phrase
+from captain_hook.state import EchoTracker, HookState, PrimitiveState, workflow_state
+from captain_hook.styleguide import StyleDiffRule, StyleRule, Violation
+from captain_hook.tasks import Task, Tasks
+from captain_hook.testing import Allow, Block, InlineTests, Input, TranscriptFixture, Warn
+from captain_hook.tools import EditOp, TaskOp, WriteOp
+from captain_hook.transcript import (
+    ToolUse,
+    ToolUseQuery,
+    ToolUseSequence,
+    Transcript,
+    TranscriptMessage,
+    TranscriptSlice,
+    Turn,
+)
+from captain_hook.transcript.inputs import (
+    AgentInput,
+    BashInput,
+    EditInput,
+    FileInputBase,
+    GenericInput,
+    GlobInput,
+    GrepInput,
+    InputBase,
+    ReadInput,
+    SkillInput,
+    TaskCreateInput,
+    TaskUpdateInput,
+    WriteInput,
+    parse_tool_input,
+)
+from captain_hook.transcript.models import (
+    ContentBlock,
+    TextBlock,
+    ToolResult,
+    ToolUseBlock,
+    parse_content_block,
+)
+from captain_hook.types import (
+    Action,
+    Agent,
+    Content,
+    CustomCondition,
+    Event,
+    FilePath,
+    HookResult,
+    HookSpec,
+    InPlanMode,
+    RanCommand,
+    ReadFile,
+    Signal,
+    Signals,
+    SourceEdits,
+    TCondition,
+    TestFile,
+    Tool,
+    TouchedFile,
+    UsedSkill,
+    Waiting,
+)
+from captain_hook.utils import read_json
+from captain_hook.workflow import Artifact, Step, Workflow, text_matches
+from captain_hook.workflow import workflow as workflow
+
+__all__ = [
+    # registration
+    "hook",
+    "on",
+    "register",
+    # events
+    "Action",
+    "Agent",
+    "BaseHookEvent",
+    "Content",
+    "CustomCondition",
+    "Event",
+    "FilePath",
+    "HookResult",
+    "HookSpec",
+    "InPlanMode",
+    "NotificationEvent",
+    "PostToolUseEvent",
+    "PostToolUseFailureEvent",
+    "PreCompactEvent",
+    "PreToolUseEvent",
+    "RanCommand",
+    "ReadFile",
+    "Signal",
+    "Signals",
+    "StopEvent",
+    "SubagentStartEvent",
+    "SubagentStopEvent",
+    "TCondition",
+    "TestFile",
+    "Tool",
+    "ToolHookEvent",
+    "TouchedFile",
+    "UsedSkill",
+    "UserPromptSubmitEvent",
+    "Waiting",
+    # context
+    "HookContext",
+    "SessionSlot",
+    "SessionStore",
+    "session_state",
+    "workflow_state",
+    "EchoTracker",
+    "HookState",
+    "PrimitiveState",
+    "SourceEdits",
+    # primitives
+    "audit",
+    "block_command",
+    "diff_lint",
+    "gate",
+    "GateVerdict",
+    "lint",
+    "llm_evaluate",
+    "llm_gate",
+    "llm_nudge",
+    "nudge",
+    "NudgeVerdict",
+    "prompt_check",
+    "PromptCheckVerdict",
+    "session_id_for",
+    "StyleDiffRule",
+    "StyleRule",
+    "styleguide",
+    "Violation",
+    "warn_command",
+    # signals
+    "cite_message",
+    "extract_signal_context",
+    "resolve_signals",
+    "score_signals",
+    "transcript_texts",
+    "Clause",
+    "NlpSignal",
+    "Phrase",
+    # commands / files
+    "Command",
+    "CommandLine",
+    "File",
+    "PathMatcher",
+    "categorize_files",
+    "Redirect",
+    # prompts
+    "Prompt",
+    "PromptMessage",
+    # settings / CLI
+    "AutoConf",
+    "HooksSettings",
+    "build_settings",
+    "generate_settings",
+    "generate_settings_json",
+    "read_json",
+    # tools
+    "EditOp",
+    "TaskOp",
+    "WriteOp",
+    # tasks (native task store)
+    "Task",
+    "Tasks",
+    # transcript
+    "Transcript",
+    "TranscriptMessage",
+    "TranscriptSlice",
+    "ToolUse",
+    "ToolUseQuery",
+    "ToolUseSequence",
+    "Turn",
+    "AgentInput",
+    "BashInput",
+    "ContentBlock",
+    "EditInput",
+    "FileInputBase",
+    "GenericInput",
+    "GlobInput",
+    "GrepInput",
+    "InputBase",
+    "ReadInput",
+    "SkillInput",
+    "TaskCreateInput",
+    "TaskUpdateInput",
+    "TextBlock",
+    "ToolResult",
+    "ToolUseBlock",
+    "WriteInput",
+    "parse_content_block",
+    "parse_tool_input",
+    # workflow
+    "Artifact",
+    "Step",
+    "Workflow",
+    "text_matches",
+    "workflow",
+    # testing
+    "Allow",
+    "Block",
+    "InlineTests",
+    "Input",
+    "TranscriptFixture",
+    "Warn",
+]

captain_hook/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from captain_hook.cli import main
+
+if __name__ == "__main__":
+    main()