typed-agent-hooks 0.1.0__tar.gz

typed_agent_hooks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typed-agent-hooks contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typed_agent_hooks-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: typed-agent-hooks
+Version: 0.1.0
+Summary: Code-first executable hooks and strict schemas for Codex and Claude Code.
+Keywords: codex,claude-code,hooks,pydantic,schemas
+Author: Nima Shoghi
+Author-email: Nima Shoghi <nimashoghi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: cyclopts>=4.23.2,<5
+Requires-Dist: pydantic>=2.8,<3
+Requires-Dist: pydantic-core
+Requires-Dist: fastmcp>=3.3,<3.4 ; extra == 'fastmcp'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/nimashoghi/typed-agent-hooks
+Provides-Extra: fastmcp
+Description-Content-Type: text/markdown
+
+# typed-agent-hooks
+
+`typed-agent-hooks` defines executable, code-first hooks for OpenAI Codex and Anthropic Claude Code. A hook's Python file owns its handlers, provider configuration, dependency environment, and executable entry point. There is no TOML manifest, import-string loader, or global installation CLI.
+
+The package provides strict provider wire models, a conservative shared semantic API, preservation-oriented config reconciliation, ordered collections of independent hook executables, and an optional FastMCP bridge.
+
+## One executable hook
+
+Put the dependencies in the executable with PEP 723 and define configuration beside the handler:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "cyclopts>=4.23.2,<5",
+#   "pydantic-core",
+#   "typed-agent-hooks==0.1.0",
+# ]
+# ///
+"""Add local project context to every submitted prompt."""
+
+import json
+from functools import partial
+
+from cyclopts import App
+from pydantic_core import to_jsonable_python
+from typed_agent_hooks import shared
+
+cli = App(result_action=[partial(json.dumps, default=to_jsonable_python, allow_nan=False), print, "return_zero"])
+hooks = shared.HookApp(name="project-context")
+
+
+@hooks.on(shared.events.PromptSubmitted, timeout=10)
+def add_project_context(event: shared.events.PromptSubmitted) -> shared.outputs.Result:
+    """Return context derived from one submitted prompt."""
+
+    return shared.outputs.AddContext(text=f"Working directory: {event.context.cwd}")
+
+
+@cli.command
+def preview(prompt: str) -> str:
+    """Preview the domain behavior without constructing a provider payload."""
+
+    return f"Would add context for {prompt!r}"
+
+
+if __name__ == "__main__":
+    hooks.main(cli)
+```
+
+Create and commit the adjacent script lockfile with `uv lock --script project_context.py`. Pin the desired TAH release in the PEP 723 declaration and refresh the lock when intentionally updating it; ordinary hook invocations then reuse the resolved installation.
+
+Make the file executable and run its ordinary domain CLI directly:
+
+```console
+./project_context.py preview "fix the tests"
+```
+
+`hooks.main(cli)` leaves ordinary arguments untouched for Cyclopts. Generated provider commands use a private `_typed-agent-hooks` protocol to invoke the same `hooks` object. That protocol is an implementation boundary, not a user-facing CLI.
+
+The Python API is direct:
+
+```python
+tool = ipi.import_path("/path/to/project_context.py")
+tool.preview("fix the tests")
+tool.hooks.render("codex", executable=tool.__file__)
+```
+
+Keep docstrings on public functions. Cyclopts uses them for CLI help, and notebook callers get the same documentation from Python.
+
+## Registration metadata
+
+`HookApp.on` accepts shared defaults plus explicit provider-only overrides:
+
+```python
+@hooks.on(
+    shared.events.ToolCallProposed,
+    timeout=20,
+    status_message="Checking tool call",
+    codex=shared.CodexOptions(matcher="Bash"),
+    claude_code=shared.ClaudeCodeOptions(matcher="Bash|Read"),
+)
+def check_tool(event: shared.events.ToolCallProposed) -> shared.outputs.Result:
+    ...
+```
+
+An app declares its enabled providers when necessary:
+
+```python
+hooks = shared.HookApp(name="codex-only", providers=("codex",))
+```
+
+Shared events that do not exist on an enabled provider fail during rendering. Provider-specific options on a disabled provider also fail. The library does not guess a lossy translation.
+
+For direct programmatic installation, call `HookApp.install` or `HookApp.uninstall`. Pass the executable explicitly so the Python call has the same information as the provider config:
+
+```python
+hooks.install(executable=__file__, provider="all", scope="project")
+```
+
+Installation replaces only commands marked with the app's stable name, preserves unrelated JSON fields and hooks, writes atomically, and reconciles every selected provider. Disabling a provider therefore removes that app's stale entries from the provider config.
+
+## Ordered collections
+
+Use a small executable installer when several hooks have independent dependencies or ownership:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "typed-agent-hooks==0.1.0",
+# ]
+# ///
+"""Install this repository's hooks in deterministic order."""
+
+from pathlib import Path
+
+from typed_agent_hooks import Collection
+
+root = Path(__file__).parent
+hooks = Collection(
+    name="project-hooks",
+    apps=(root / "first.py", root / "second.py"),
+)
+
+if __name__ == "__main__":
+    hooks.main()
+```
+
+The CLI and Python API are the same bound methods:
+
+```console
+./install.py install --scope project
+./install.py uninstall --scope project
+```
+
+```python
+installer = ipi.import_path("/path/to/install.py")
+installer.hooks.install(scope="project")
+```
+
+Collection installation executes each child in its own PEP 723 environment, validates every description before writing anything, preserves declared order, rejects duplicate names and paths, and removes members deleted from the collection.
+
+## FastMCP forwarding
+
+`typed_agent_hooks.fastmcp.attach` connects a running FastMCP server to a normal hook application. `ForwardingHooks` installs one forwarding command for every native event supported by each provider:
+
+```python
+from typed_agent_hooks.fastmcp import ForwardingHooks, attach
+
+attach(server, hooks, provider="codex", server_name="ipi")
+
+forwarding = ForwardingHooks(
+    name="ipi",
+    server_name="ipi",
+    timeout=70,
+    startup_wait=30,
+    response_timeout=35,
+)
+forwarding.install(provider="all", scope="user")
+```
+
+The dedicated `tah-fastmcp-forward` entry point is also a direct Cyclopts view of the importable `forward` function:
+
+```console
+tah-fastmcp-forward - --provider codex --server-name ipi
+```
+
+```python
+from typed_agent_hooks.fastmcp import forward
+
+output = forward(payload, provider="codex", server_name="ipi")
+```
+
+`-` means stdin only at the CLI boundary. The forwarder is fail-open: an absent, slow, dead, unsupported, or ambiguous local bridge returns no output and does not block the harness. Invalid explicit timeout arguments still fail before forwarding.
+
+The bridge requires the `fastmcp` extra. The forwarding subprocess itself imports Cyclopts and the small TAH rendezvous modules, but does not import FastMCP.
+
+## Provider schemas
+
+Provider-native schemas remain available from `typed_agent_hooks.codex` and `typed_agent_hooks.claude_code`. Wire inputs are tolerant readers: unknown provider fields are ignored while declared fields remain strictly typed. Outputs are closed and exact. Use the shared API when one semantic handler is valid for both providers; use the provider-native models when their behavior genuinely differs.
+
+## Development
+
+```console
+uv run ruff check .
+uv run ty check
+uv run pytest -q
+```

typed_agent_hooks-0.1.0/README.md

@@ -0,0 +1,191 @@
+# typed-agent-hooks
+
+`typed-agent-hooks` defines executable, code-first hooks for OpenAI Codex and Anthropic Claude Code. A hook's Python file owns its handlers, provider configuration, dependency environment, and executable entry point. There is no TOML manifest, import-string loader, or global installation CLI.
+
+The package provides strict provider wire models, a conservative shared semantic API, preservation-oriented config reconciliation, ordered collections of independent hook executables, and an optional FastMCP bridge.
+
+## One executable hook
+
+Put the dependencies in the executable with PEP 723 and define configuration beside the handler:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "cyclopts>=4.23.2,<5",
+#   "pydantic-core",
+#   "typed-agent-hooks==0.1.0",
+# ]
+# ///
+"""Add local project context to every submitted prompt."""
+
+import json
+from functools import partial
+
+from cyclopts import App
+from pydantic_core import to_jsonable_python
+from typed_agent_hooks import shared
+
+cli = App(result_action=[partial(json.dumps, default=to_jsonable_python, allow_nan=False), print, "return_zero"])
+hooks = shared.HookApp(name="project-context")
+
+
+@hooks.on(shared.events.PromptSubmitted, timeout=10)
+def add_project_context(event: shared.events.PromptSubmitted) -> shared.outputs.Result:
+    """Return context derived from one submitted prompt."""
+
+    return shared.outputs.AddContext(text=f"Working directory: {event.context.cwd}")
+
+
+@cli.command
+def preview(prompt: str) -> str:
+    """Preview the domain behavior without constructing a provider payload."""
+
+    return f"Would add context for {prompt!r}"
+
+
+if __name__ == "__main__":
+    hooks.main(cli)
+```
+
+Create and commit the adjacent script lockfile with `uv lock --script project_context.py`. Pin the desired TAH release in the PEP 723 declaration and refresh the lock when intentionally updating it; ordinary hook invocations then reuse the resolved installation.
+
+Make the file executable and run its ordinary domain CLI directly:
+
+```console
+./project_context.py preview "fix the tests"
+```
+
+`hooks.main(cli)` leaves ordinary arguments untouched for Cyclopts. Generated provider commands use a private `_typed-agent-hooks` protocol to invoke the same `hooks` object. That protocol is an implementation boundary, not a user-facing CLI.
+
+The Python API is direct:
+
+```python
+tool = ipi.import_path("/path/to/project_context.py")
+tool.preview("fix the tests")
+tool.hooks.render("codex", executable=tool.__file__)
+```
+
+Keep docstrings on public functions. Cyclopts uses them for CLI help, and notebook callers get the same documentation from Python.
+
+## Registration metadata
+
+`HookApp.on` accepts shared defaults plus explicit provider-only overrides:
+
+```python
+@hooks.on(
+    shared.events.ToolCallProposed,
+    timeout=20,
+    status_message="Checking tool call",
+    codex=shared.CodexOptions(matcher="Bash"),
+    claude_code=shared.ClaudeCodeOptions(matcher="Bash|Read"),
+)
+def check_tool(event: shared.events.ToolCallProposed) -> shared.outputs.Result:
+    ...
+```
+
+An app declares its enabled providers when necessary:
+
+```python
+hooks = shared.HookApp(name="codex-only", providers=("codex",))
+```
+
+Shared events that do not exist on an enabled provider fail during rendering. Provider-specific options on a disabled provider also fail. The library does not guess a lossy translation.
+
+For direct programmatic installation, call `HookApp.install` or `HookApp.uninstall`. Pass the executable explicitly so the Python call has the same information as the provider config:
+
+```python
+hooks.install(executable=__file__, provider="all", scope="project")
+```
+
+Installation replaces only commands marked with the app's stable name, preserves unrelated JSON fields and hooks, writes atomically, and reconciles every selected provider. Disabling a provider therefore removes that app's stale entries from the provider config.
+
+## Ordered collections
+
+Use a small executable installer when several hooks have independent dependencies or ownership:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "typed-agent-hooks==0.1.0",
+# ]
+# ///
+"""Install this repository's hooks in deterministic order."""
+
+from pathlib import Path
+
+from typed_agent_hooks import Collection
+
+root = Path(__file__).parent
+hooks = Collection(
+    name="project-hooks",
+    apps=(root / "first.py", root / "second.py"),
+)
+
+if __name__ == "__main__":
+    hooks.main()
+```
+
+The CLI and Python API are the same bound methods:
+
+```console
+./install.py install --scope project
+./install.py uninstall --scope project
+```
+
+```python
+installer = ipi.import_path("/path/to/install.py")
+installer.hooks.install(scope="project")
+```
+
+Collection installation executes each child in its own PEP 723 environment, validates every description before writing anything, preserves declared order, rejects duplicate names and paths, and removes members deleted from the collection.
+
+## FastMCP forwarding
+
+`typed_agent_hooks.fastmcp.attach` connects a running FastMCP server to a normal hook application. `ForwardingHooks` installs one forwarding command for every native event supported by each provider:
+
+```python
+from typed_agent_hooks.fastmcp import ForwardingHooks, attach
+
+attach(server, hooks, provider="codex", server_name="ipi")
+
+forwarding = ForwardingHooks(
+    name="ipi",
+    server_name="ipi",
+    timeout=70,
+    startup_wait=30,
+    response_timeout=35,
+)
+forwarding.install(provider="all", scope="user")
+```
+
+The dedicated `tah-fastmcp-forward` entry point is also a direct Cyclopts view of the importable `forward` function:
+
+```console
+tah-fastmcp-forward - --provider codex --server-name ipi
+```
+
+```python
+from typed_agent_hooks.fastmcp import forward
+
+output = forward(payload, provider="codex", server_name="ipi")
+```
+
+`-` means stdin only at the CLI boundary. The forwarder is fail-open: an absent, slow, dead, unsupported, or ambiguous local bridge returns no output and does not block the harness. Invalid explicit timeout arguments still fail before forwarding.
+
+The bridge requires the `fastmcp` extra. The forwarding subprocess itself imports Cyclopts and the small TAH rendezvous modules, but does not import FastMCP.
+
+## Provider schemas
+
+Provider-native schemas remain available from `typed_agent_hooks.codex` and `typed_agent_hooks.claude_code`. Wire inputs are tolerant readers: unknown provider fields are ignored while declared fields remain strictly typed. Outputs are closed and exact. Use the shared API when one semantic handler is valid for both providers; use the provider-native models when their behavior genuinely differs.
+
+## Development
+
+```console
+uv run ruff check .
+uv run ty check
+uv run pytest -q
+```

typed_agent_hooks-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "typed-agent-hooks"
+version = "0.1.0"
+description = "Code-first executable hooks and strict schemas for Codex and Claude Code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "cyclopts>=4.23.2,<5",
+    "pydantic>=2.8,<3",
+    "pydantic-core",
+]
+keywords = [
+    "codex",
+    "claude-code",
+    "hooks",
+    "pydantic",
+    "schemas",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Nima Shoghi"
+email = "nimashoghi@gmail.com"
+
+[project.optional-dependencies]
+fastmcp = ["fastmcp>=3.3,<3.4"]
+
+[project.urls]
+Repository = "https://github.com/nimashoghi/typed-agent-hooks"
+
+[project.scripts]
+tah-fastmcp-forward = "typed_agent_hooks.fastmcp.shim:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.15",
+    "ty>=0.0.50,<0.1",
+    "fastmcp>=3.3,<3.4",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[tool.ty.environment]
+python-version = "3.10"
+python-platform = "linux"
+root = ["./src"]
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.ty.terminal]
+output-format = "concise"

typed_agent_hooks-0.1.0/pyproject.toml.orig

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "typed-agent-hooks"
+version = "0.1.0"
+description = "Code-first executable hooks and strict schemas for Codex and Claude Code."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Nima Shoghi", email = "nimashoghi@gmail.com" }]
+dependencies = [
+  "cyclopts>=4.23.2,<5",
+  "pydantic>=2.8,<3",
+  "pydantic-core",
+]
+keywords = ["codex", "claude-code", "hooks", "pydantic", "schemas"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# Server-side FastMCP bridge (HookBridge.attach). The forwarding process does
+# not require this extra.
+fastmcp = ["fastmcp>=3.3,<3.4"]
+
+[project.urls]
+Repository = "https://github.com/nimashoghi/typed-agent-hooks"
+
+[project.scripts]
+tah-fastmcp-forward = "typed_agent_hooks.fastmcp.shim:app"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.15", "ty>=0.0.50,<0.1", "fastmcp>=3.3,<3.4"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ty.environment]
+python-version = "3.10"
+# rendezvous targets Linux APIs (geteuid/AF_UNIX/SO_PEERCRED); without the pin
+# ty infers the host OS and flags them on Windows/macOS dev machines.
+python-platform = "linux"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.terminal]
+output-format = "concise"

typed_agent_hooks-0.1.0/src/typed_agent_hooks/__init__.py

@@ -0,0 +1,28 @@
+"""Code-first hook APIs for Codex, Claude Code, and shared semantics."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import claude_code, codex, shared
+    from .collection import Collection
+
+__all__ = ["Collection", "claude_code", "codex", "shared"]
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    """Load public surfaces only when a caller selects them."""
+
+    if name == "Collection":
+        from .collection import Collection
+
+        globals()[name] = Collection
+        return Collection
+    if name in {"claude_code", "codex", "shared"}:
+        module = import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

typed_agent_hooks-0.1.0/src/typed_agent_hooks/claude_code/__init__.py

@@ -0,0 +1,15 @@
+"""Claude Code-specific schemas, outputs, and configuration."""
+
+from . import config, events, outputs
+from .events import EVENT_NAMES, INPUT_ADAPTER, parse_input
+from .outputs import render_output
+
+__all__ = [
+    "EVENT_NAMES",
+    "INPUT_ADAPTER",
+    "config",
+    "events",
+    "outputs",
+    "parse_input",
+    "render_output",
+]