sequential-hooks 0.1.0__tar.gz

sequential_hooks-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+.eggs/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage*
+.pytest_cache/
+.cache/
+
+# Type checker / linter caches
+.pyright/
+.mypy_cache/
+.ruff_cache/
+pyrightconfig.json
+
+# Editors
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

sequential_hooks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the sequential-hooks authors
+
+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.

sequential_hooks-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: sequential-hooks
+Version: 0.1.0
+Summary: Run coding-agent hooks in order with agent-specific response handling
+Project-URL: Documentation, https://github.com/dactylo/sequential-hooks/tree/main/docs
+Project-URL: Homepage, https://github.com/dactylo/sequential-hooks
+Project-URL: Issues, https://github.com/dactylo/sequential-hooks/issues
+Project-URL: Repository, https://github.com/dactylo/sequential-hooks
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coding-agents,hooks,orchestration,sequential
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# sequential-hooks
+
+`sequential-hooks` runs coding-agent hooks in a strict order. Without a wrapper, a host may start
+several hooks concurrently or in an undocumented order. A validator can then inspect an old tool
+input while another hook is still replacing it. Register one wrapper hook and place the former hook
+commands inside it as ordered steps.
+
+## Quick start
+
+`sequential-hooks` requires native CPython 3.13 or newer and `uv`. The project is not published to
+a package index. Install the current checkout from the repository root:
+
+```text
+uv tool install .
+```
+
+To update an existing installation after pulling changes:
+
+```text
+uv tool install --reinstall .
+```
+
+sequential-hooks has no configuration file. Choose the coding agent that will run the wrapper, then
+add the registration from its setup guide:
+
+- [Claude Code](plugins/claude/README.md)
+- [Codex](plugins/codex/README.md)
+- [Antigravity](plugins/agy/README.md)
+
+Check [compatibility](docs/compatibility.md) for the recorded host versions and known host limits,
+and [platforms](docs/platforms.md) for process handling. The guides use `first-hook`,
+`second-hook`, and `audit-hook` as sample child commands. Replace them with hooks you have
+installed and want to run in order. Move those child hooks into the wrapper and remove their
+separate registrations, or the host may still start duplicate copies concurrently.
+
+The wrapper command expects a native host payload on stdin. Configure it as a host hook rather than
+running the hook command interactively. After saving the registration, inspect it with the matching
+read-only report:
+
+```text
+sequential-hooks doctor --agent claude
+sequential-hooks doctor --agent codex
+sequential-hooks doctor --agent agy
+```
+
+Exit 0 means the findings are informational. Exit 1 means at least one warning or error needs
+action. The [troubleshooting guide](docs/troubleshooting.md) explains common findings.
+
+Antigravity requires an explicit event in each hook command. An all-neutral Antigravity pre-tool
+chain emits the host's real automatic `allow` decision; it does not preserve the ordinary
+permission prompt. Review the [Antigravity setup guide](plugins/agy/README.md) before enabling it.
+
+## How commands compose
+
+`-a, --agent` selects the installed host adapter for a coding agent. The built-in names are
+`claude`, `codex`, and `agy`; a third-party adapter installed with
+`uv tool install . --with PACKAGE` is selected by its own name. Nothing is inferred from the
+payload. See [adding a host](docs/adding-a-host.md).
+
+`-h, --help` prints help for wrapper mode; `doctor -h` and `doctor --help` print doctor help.
+
+```text
+sequential-hooks --agent codex --step-timeout 30 defsort hook --agent codex -- docwrap hook --agent codex
+```
+
+The exact `--` token separates steps and cannot be passed to a step. Each child receives its own
+literal arguments, including its own `--agent`; wrapper options are not inherited by child
+commands.
+
+Continue with the [documentation map](docs/README.md), [concepts](docs/concepts.md),
+[security](docs/security.md), or the [CLI reference](docs/reference/cli.md).

sequential_hooks-0.1.0/README.md

@@ -0,0 +1,71 @@
+# sequential-hooks
+
+`sequential-hooks` runs coding-agent hooks in a strict order. Without a wrapper, a host may start
+several hooks concurrently or in an undocumented order. A validator can then inspect an old tool
+input while another hook is still replacing it. Register one wrapper hook and place the former hook
+commands inside it as ordered steps.
+
+## Quick start
+
+`sequential-hooks` requires native CPython 3.13 or newer and `uv`. The project is not published to
+a package index. Install the current checkout from the repository root:
+
+```text
+uv tool install .
+```
+
+To update an existing installation after pulling changes:
+
+```text
+uv tool install --reinstall .
+```
+
+sequential-hooks has no configuration file. Choose the coding agent that will run the wrapper, then
+add the registration from its setup guide:
+
+- [Claude Code](plugins/claude/README.md)
+- [Codex](plugins/codex/README.md)
+- [Antigravity](plugins/agy/README.md)
+
+Check [compatibility](docs/compatibility.md) for the recorded host versions and known host limits,
+and [platforms](docs/platforms.md) for process handling. The guides use `first-hook`,
+`second-hook`, and `audit-hook` as sample child commands. Replace them with hooks you have
+installed and want to run in order. Move those child hooks into the wrapper and remove their
+separate registrations, or the host may still start duplicate copies concurrently.
+
+The wrapper command expects a native host payload on stdin. Configure it as a host hook rather than
+running the hook command interactively. After saving the registration, inspect it with the matching
+read-only report:
+
+```text
+sequential-hooks doctor --agent claude
+sequential-hooks doctor --agent codex
+sequential-hooks doctor --agent agy
+```
+
+Exit 0 means the findings are informational. Exit 1 means at least one warning or error needs
+action. The [troubleshooting guide](docs/troubleshooting.md) explains common findings.
+
+Antigravity requires an explicit event in each hook command. An all-neutral Antigravity pre-tool
+chain emits the host's real automatic `allow` decision; it does not preserve the ordinary
+permission prompt. Review the [Antigravity setup guide](plugins/agy/README.md) before enabling it.
+
+## How commands compose
+
+`-a, --agent` selects the installed host adapter for a coding agent. The built-in names are
+`claude`, `codex`, and `agy`; a third-party adapter installed with
+`uv tool install . --with PACKAGE` is selected by its own name. Nothing is inferred from the
+payload. See [adding a host](docs/adding-a-host.md).
+
+`-h, --help` prints help for wrapper mode; `doctor -h` and `doctor --help` print doctor help.
+
+```text
+sequential-hooks --agent codex --step-timeout 30 defsort hook --agent codex -- docwrap hook --agent codex
+```
+
+The exact `--` token separates steps and cannot be passed to a step. Each child receives its own
+literal arguments, including its own `--agent`; wrapper options are not inherited by child
+commands.
+
+Continue with the [documentation map](docs/README.md), [concepts](docs/concepts.md),
+[security](docs/security.md), or the [CLI reference](docs/reference/cli.md).

sequential_hooks-0.1.0/_build.py

@@ -0,0 +1,30 @@
+"""Collect bundled agent entry points for distribution metadata."""
+
+import tomllib
+from pathlib import Path
+from typing import override
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+class PluginMetadataHook(MetadataHookInterface):
+    """Include each bundled plugin's registration in the containing distribution."""
+
+    @override
+    def update(self, metadata: dict[str, object]) -> None:
+        metadata['entry-points'] = _plugin_entry_points(Path(self.root))
+
+
+def _plugin_entry_points(root: Path) -> dict[str, dict[str, str]]:
+    """Read entry points declared by the root's agent plugin directories."""
+    groups: dict[str, dict[str, str]] = {}
+    for manifest in sorted((root / 'plugins').glob('*/adapter.toml')):
+        with manifest.open('rb') as stream:
+            entries = tomllib.load(stream)['entry-points']
+        for group, targets in entries.items():
+            registered = groups.setdefault(group, {})
+            for name, target in targets.items():
+                if name in registered:
+                    raise ValueError(f'Duplicate entry point {group}:{name} in {manifest}')
+                registered[name] = target
+    return groups

sequential_hooks-0.1.0/plugins/agy/README.md

@@ -0,0 +1,145 @@
+# Antigravity
+
+The Antigravity adapter chains `PreToolUse` and `PostToolUse` hooks. Antigravity may invoke an
+exact post-tool matcher for extra callbacks whose `toolCall` is explicitly null. `sequential-hooks`
+treats that exact shape as inapplicable, starts no child step, and returns the native empty
+response.
+
+Antigravity CLI 1.1.13 documents five native hook events: `PreToolUse`, `PostToolUse`,
+`PreInvocation`, `PostInvocation`, and `Stop`. The wrapper chains only `PreToolUse` and
+`PostToolUse`.
+
+Antigravity configuration may appear in `~/.gemini/config/hooks.json` or project
+`.agents/hooks.json`. `sequential-hooks` has no configuration file.
+
+Official reference: [Antigravity hooks](https://antigravity.google/docs/hooks).
+
+## Registration
+
+Antigravity uses a top-level map from hook names to event configurations. A top-level hook named
+`hooks` follows the same schema as any other name; it is not a second wrapper shape.
+
+The child commands are examples. Replace `first-hook` and `second-hook` with installed hooks that
+accept the corresponding Antigravity event payload.
+
+Antigravity configuration:
+
+```json
+{
+  "sequential-hooks": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sequential-hooks --agent agy --event PreToolUse --step-timeout 5 first-hook hook -- second-hook hook",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sequential-hooks --agent agy --event PostToolUse --step-timeout 5 first-hook hook -- second-hook hook",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Each event registration must carry its exact event because Antigravity's payload does not identify
+it. The wrapper commands are:
+
+```text
+sequential-hooks --agent agy --event PreToolUse --step-timeout 5 first-hook hook -- second-hook hook
+sequential-hooks --agent agy --event PostToolUse --step-timeout 5 first-hook hook -- second-hook hook
+```
+
+An all-neutral pre-tool chain emits `allow`. That is Antigravity's real automatic permission, not a
+neutral response. If the tool call must prompt, include a step that returns `ask` or `force_ask`,
+or do not register this chain.
+
+Use a matcher that covers only tools handled by every step. Remove separate registrations of those
+steps. Antigravity otherwise remains free to start the duplicate copies concurrently.
+
+Antigravity currently documents a 30-second command-handler default. Set an explicit outer timeout
+above the chain budget; three steps at five seconds need more than 15 seconds for startup and
+cleanup. Antigravity 1.1.8 starts the outer command with `sh -c` on macOS and Linux and `cmd /c` on
+Windows. It expands `~` and uses the directory containing `hooks.json` as the working directory.
+The wrapper starts each inner step as a literal argument vector without a shell.
+
+## Decisions and output
+
+Current Antigravity host documentation lists five native pre-tool decision values: `allow`, `ask`,
+`deny`, `force_ask`, and `deny_unless_prior_grant`. The wrapper accepts child `allow`, `ask`,
+`deny`, `force_ask`, and `neutral` decisions; `neutral` carries no permission decision and an
+all-neutral chain normalizes to final `allow`. If a native hook emits `deny_unless_prior_grant`,
+the wrapper receives that output and classifies it as malformed. The existing PreToolUse failure
+policy converts the malformed output to an unconditional fail-closed denial.
+
+The wrapper's pre-tool precedence is `deny > force_ask > ask > allow > neutral`; Antigravity
+documents the meanings but no ordering for disagreeing hooks. A deny is terminal. Equal winning
+`permissionOverrides` survive; conflicting winning arrays fail closed.
+
+The wrapper accepts silence, ASCII-whitespace-only stdout, or `{}` from a post-tool step and emits
+`{}`. Unparsable nonempty output is malformed; a nonempty JSON object is unsupported. A post-tool
+failure is reported to developer diagnostics and later steps continue because Antigravity has no
+independent feedback field.
+
+Antigravity CLI 1.1.8 on macOS may emit two extra `PostToolUse` callbacks with explicit
+`toolCall: null` around the attributable object-shaped callback. The wrapper still requires an
+integer `stepIdx`, but it starts no child for the explicit-null shape. It emits exact `{}` plus one
+line feed, writes no diagnostic, and exits `0`. A missing `toolCall` or any non-null value still
+runs the configured chain. The wrapper does not deduplicate by callback order, `stepIdx`, or
+conversation state.
+
+Controlled Antigravity CLI 1.1.8 probes confirmed project registration loading and a pre-tool
+handler on macOS. They did not establish live Linux or Windows event behavior. A separate macOS
+post-tool probe found a matcher dispatch divergence, so required post-tool chaining still needs a
+provider fix and a fresh live probe. The wrapper's post-tool response contract above applies when
+the host invokes it.
+
+## Trust and verify
+
+Treat the wrapper and every inner step as trusted code with your user authority.
+
+```text
+sequential-hooks doctor --agent agy
+```
+
+`doctor` parses the named-hook map without executing commands. Static inspection can tokenize safe
+POSIX shell text. Windows shell commands remain uninspectable because `doctor` does not evaluate
+`cmd /c` syntax. The report's enabled state follows each named hook's `enabled` value; absent
+`enabled` defaults to true, and a non-Boolean value is reported as malformed.
+
+Common corrections:
+
+- `event_missing`: add the registered event, `--event PreToolUse` or `--event PostToolUse`, to the
+  active command.
+- `wrong_event`: change the explicit event to the registered event.
+- `wrong_host`: change the wrapper to `--agent agy`.
+- `agy_chain_budget_uncontained`: set the outer timeout above the configured chain budget.
+- `duplicate_wrapper`: keep one wrapper for each event and matcher.
+- `duplicate_child_registration`: remove the separately registered child.
+
+## Configuration failures
+
+When `--agent agy` and a served `--event` precede the first syntax error, a configuration error,
+including invalid wrapper syntax or invalid native input, is answered with a generic `spawn`
+report: top-level `deny` on `PreToolUse`, or `{}` plus a developer diagnostic on `PostToolUse`. The
+latter does not block. Without a valid `--event`, or when the adapter itself cannot be loaded, the
+wrapper exits 2 with one diagnostic line and no response. Antigravity has no exit-code tier, so
+that last resort does not block; it runs no step and grants nothing. Run `doctor` to catch a
+missing or unsupported event and an unavailable adapter before a hook fires.
+
+See the [protocol reference](../../docs/reference/host-protocols.md#antigravity) and
+[security guide](../../docs/security.md).

sequential_hooks-0.1.0/plugins/agy/_sequential_hooks/__init__.py

@@ -0,0 +1 @@
+"""Provide the private Antigravity adapter implementation."""