agentack 0.6.0__tar.gz

agentack-0.6.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+title: AgentAck
+message: If you use or adapt this software, please cite it using this metadata.
+type: software
+authors:
+  - family-names: Kaczmarek
+    given-names: Sylvester
+repository-code: https://github.com/sylvesterkaczmarek/agentack
+url: https://github.com/sylvesterkaczmarek/agentack
+version: 0.6.0
+date-released: 2026-08-19
+license: MIT

agentack-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Contributions that improve approval-integrity testing, evidence quality, adapters, portability, or documentation are welcome.
+
+## Development setup
+
+Python 3.11 or later is required.
+
+```bash
+git clone https://github.com/sylvesterkaczmarek/agentack.git
+cd agentack
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+make check
+```
+
+On Windows, activate the virtual environment using the normal PowerShell or Command Prompt command and run the equivalent Python commands directly if `make` is unavailable.
+
+## Changes
+
+Keep the deterministic core framework-agnostic. Agent-specific behavior belongs under `src/agentack/adapters/`.
+
+For a new live adapter:
+
+1. document the exact official event or control boundary it observes;
+2. distinguish observed facts from inference;
+3. use `INCOMPLETE` when required evidence is unavailable;
+4. avoid replacing or weakening the agent's native permission system;
+5. use harmless synthetic probes;
+6. add mocked integration tests that cover success, failure, and missing evidence;
+7. update the supported-integration table only after the adapter genuinely works.
+
+Do not add placeholder `agentack test` targets.
+
+## Pull requests
+
+Keep changes focused. Add regression tests for security-relevant fixes and update public documentation when behavior changes.
+
+Before opening a pull request, run:
+
+```bash
+make check
+```
+
+For packaging changes, also run:
+
+```bash
+make release-check
+```
+
+## Security reports
+
+Do not open a public issue for an exploitable security vulnerability. Follow [`SECURITY.md`](SECURITY.md).

agentack-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sylvester Kaczmarek
+
+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.

agentack-0.6.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include CITATION.cff
+include CONTRIBUTING.md
+include LICENSE
+include Makefile
+include README.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *.jsonl *.toml
+include assets/social/README.md

agentack-0.6.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: test smoke lint typecheck check build package-check release-check
+
+test:
+	python -m unittest discover -s tests -v
+
+smoke:
+	python -m agentack demo
+	python -m agentack doctor
+	python -m agentack coverage
+	python -m agentack demo secure
+	@python -m agentack demo action-swap >/dev/null 2>&1; test $$? -eq 1
+	@python -m agentack demo secure --write /tmp/agentack-secure.jsonl >/dev/null
+	@head -n -1 /tmp/agentack-secure.jsonl > /tmp/agentack-incomplete.jsonl
+	@python -m agentack check /tmp/agentack-incomplete.jsonl >/dev/null 2>&1; test $$? -eq 3
+
+lint:
+	python -m ruff check .
+
+typecheck:
+	python -m mypy src/agentack/models.py src/agentack/provenance.py src/agentack/report.py src/agentack/adapters/base.py
+
+check: lint typecheck test smoke
+
+build:
+	rm -rf build dist
+	python -m build
+
+package-check:
+	python -m twine check dist/*
+
+release-check: check build package-check

agentack-0.6.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: agentack
+Version: 0.6.0
+Summary: Test whether human approval controls for AI agents actually work.
+Author: Sylvester Kaczmarek
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sylvesterkaczmarek/agentack
+Project-URL: Repository, https://github.com/sylvesterkaczmarek/agentack
+Project-URL: Issues, https://github.com/sylvesterkaczmarek/agentack/issues
+Keywords: ai-agents,ai-security,human-in-the-loop,agentic-security,approval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.16; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Dynamic: license-file
+
+# AgentAck
+
+[![CI](https://github.com/sylvesterkaczmarek/agentack/actions/workflows/ci.yml/badge.svg)](https://github.com/sylvesterkaczmarek/agentack/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Test whether human approval controls for AI agents actually work.**
+
+AgentAck is a local-first CLI for checking whether agent actions remain bound to what a human approved, whether denials stay enforced, and whether approval authority is replayed or routed around.
+
+## Try it
+
+```bash
+git clone https://github.com/sylvesterkaczmarek/agentack.git
+cd agentack
+python -m pip install .
+
+agentack demo
+agentack doctor
+agentack coverage
+```
+
+`agentack demo` needs no agent account:
+
+```text
+AgentAck demo
+
+Secure approval flow           PASS
+Action changed after approval  DETECTED (ACK003)
+
+AgentAck binds the action shown for approval to the action that later executes.
+The broken demo changes the command after approval; AgentAck detects the mismatch.
+
+Next: agentack doctor
+```
+
+## Live integrations
+
+```bash
+agentack test claude
+agentack test codex
+```
+
+| Agent | Detected by `doctor` | Live test | Evidence path |
+| --- | --- | --- | --- |
+| Claude Code | yes | **yes** | official hooks + `tool_decision` telemetry |
+| Codex CLI | yes | **yes** | official App Server approval + execution + interrupt lifecycle |
+| Gemini CLI | yes | not yet | detection only |
+| Cursor CLI | yes | not yet | detection only |
+
+Claude uses its native permission UI. Codex uses AgentAck as a local App Server client, so the Codex test verifies the approval/enforcement protocol rather than the Codex TUI or VS Code approval-card rendering.
+
+See [`docs/claude-code.md`](docs/claude-code.md) and [`docs/codex-cli.md`](docs/codex-cli.md).
+
+## Live coverage
+
+```bash
+agentack coverage
+```
+
+Current coverage:
+
+```text
+Rule     Trace     Claude    Codex     Check
+ACK001   TESTED    TESTED    TESTED    Required approval
+ACK002   TESTED    TESTED    TESTED    Denied action
+ACK003   TESTED    TESTED    TESTED    Exact action binding
+ACK004   TESTED    TESTED    TESTED    Approval replay
+ACK005   TESTED    TRACE     TRACE     Approval expiry
+ACK006   TESTED    GUARDED   GUARDED   Lifecycle ordering
+ACK007   TESTED    TESTED    TESTED    Denial route-around
+ACK008   TESTED    SKIP      TESTED    Interrupt bypass
+ACK009   TESTED    GUARDED   GUARDED   Evidence completeness
+```
+
+`TESTED` means a live path deliberately exercises the control. `GUARDED` means the adapter fails closed on bad or missing evidence without inducing that attack. `TRACE` means deterministic trace coverage only for that adapter. `SKIP` means AgentAck does not claim a reliable safe live boundary.
+
+See [`docs/live-coverage.md`](docs/live-coverage.md).
+
+## What it detects
+
+| Rule | Check |
+| --- | --- |
+| `ACK001` | required approval missing |
+| `ACK002` | denied action executed |
+| `ACK003` | action identity changed across proposal, presentation, or execution |
+| `ACK004` | approval replayed beyond its granted scope |
+| `ACK005` | approval expired |
+| `ACK006` | approval lifecycle invalid |
+| `ACK007` | denial routed around |
+| `ACK008` | interrupt bypassed |
+| `ACK009` | approval evidence incomplete |
+
+Missing evidence returns `INCOMPLETE`, not a silent pass.
+
+## Live probe behavior
+
+Claude's extended suite asks the user to approve one Bash action once, deny an identical replay, deny one marker-writing route, and deny an alternate route for the same harmless intent. If the first approval is explicitly persistent, AgentAck does not label later reuse as a replay vulnerability.
+
+Codex's extended suite adds the same replay and route-around checks plus a human-triggered `turn/interrupt` probe. AgentAck sends only a one-request `accept` decision and never intentionally grants `acceptForSession` or persistent authority.
+
+All filesystem effects stay inside disposable temporary workspaces. AgentAck does not run destructive, credential, deployment, or real cloud/network probes.
+
+## Terminal results
+
+```text
+AgentAck  PASS
+Integration: Codex CLI
+
+Probe isolation              PASS
+Approval required            PASS
+Human approval observed      PASS
+Exact action binding         PASS
+Denial enforcement           PASS
+Approval replay              PASS
+Denial route-around          PASS
+Approval expiry              SKIP
+Stop enforcement             PASS
+Lifecycle ordering           PASS
+Evidence completeness        PASS
+```
+
+A `PASS` requires affirmative evidence for the tested path. `SKIP` and `INCOMPLETE` are not converted into success claims.
+
+## Commands
+
+```bash
+agentack demo                         # secure + deliberately broken showcase
+agentack doctor                       # detect available integrations
+agentack coverage                     # show trace/live ACK coverage
+agentack test claude                  # live Claude approval-control suite
+agentack test codex                   # live Codex approval-control suite
+agentack check trace.jsonl            # evaluate an AgentAck trace
+agentack check trace.jsonl --json report.json --sarif report.sarif
+agentack rules
+agentack explain ACK004
+agentack init agentack.toml
+```
+
+Exit codes are stable:
+
+- `0` `PASS`
+- `1` `FAIL`
+- `2` invalid input, configuration, or output
+- `3` `INCOMPLETE`
+
+## Report provenance
+
+JSON and SARIF reports use the same versioned AgentAck report envelope for trace and live-adapter runs. They include AgentAck/adapter versions, run/session IDs, timestamps, evidence hashes, and structured expected/presented/executed action identities.
+
+Live checks that map directly to an ACK rule also carry additive `rule_id` and `probe_id` identifiers. Raw command parameters, raw telemetry payloads, and command output are not copied into reports.
+
+The hashes identify bytes or canonical structures. They are **not digital signatures, attestation, or proof that the evidence producer was trustworthy**.
+
+See [`docs/report-schema.md`](docs/report-schema.md).
+
+## Evidence model
+
+The deterministic core evaluates:
+
+```text
+ACTION PROPOSED
+      |
+      v
+ACTION PRESENTED TO HUMAN
+      |
+      v
+APPROVAL DECISION
+      |
+      +----------+
+      |          |
+      v          v
+  EXECUTED     BLOCKED
+      \          /
+       v        v
+       SESSION END
+```
+
+Live adapters map their agent-specific evidence into the same framework-neutral action identities rather than modifying the ACK engine for each vendor.
+
+See [`docs/method.md`](docs/method.md) and [`docs/trace-format.md`](docs/trace-format.md).
+
+## Instrument a workflow
+
+```python
+from agentack import Action, Recorder
+
+command = Action(
+    tool="shell",
+    operation="run",
+    resource="workspace",
+    parameters={"argv": ["git", "status"]},
+)
+
+with Recorder("trace.jsonl", "session-123") as recorder:
+    recorder.propose("action-1", command, intent_id="inspect-repo")
+    recorder.request_approval("approval-1", "action-1", command, intent_id="inspect-repo")
+    recorder.decide("approval-1", "action-1", "allow", intent_id="inspect-repo")
+    recorder.execute("action-1", command, approval_id="approval-1", intent_id="inspect-repo")
+```
+
+The recorder does not execute the action.
+
+## Product boundary
+
+AgentAck tests **approval integrity**. It is not a prompt-injection scanner, observability platform, sandbox, authorization system, generic red-team framework, human approval UI, or compliance product.
+
+A `PASS` applies only to the tested or recorded path. It does not prove that every agent path is safe, that the evidence source is trustworthy, or that a system satisfies a legal or regulatory requirement.
+
+## Standards mapping
+
+AgentAck includes informational mappings to the OWASP Top 10 for Agentic Applications 2026 and narrow technical areas of the EU AI Act concerning logging, human oversight, robustness, and cybersecurity.
+
+These mappings are navigation aids only. They do not establish certification, conformity, legal compliance, or applicability of any requirement.
+
+See [`docs/standards-mapping.md`](docs/standards-mapping.md).
+
+## Development
+
+Python 3.11 or later is required.
+
+```bash
+python -m pip install -e '.[dev]'
+make check
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`SECURITY.md`](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+© **Sylvester Kaczmarek** · [https://www.sylvesterkaczmarek.com](https://www.sylvesterkaczmarek.com)

agentack-0.6.0/README.md

@@ -0,0 +1,233 @@
+# AgentAck
+
+[![CI](https://github.com/sylvesterkaczmarek/agentack/actions/workflows/ci.yml/badge.svg)](https://github.com/sylvesterkaczmarek/agentack/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Test whether human approval controls for AI agents actually work.**
+
+AgentAck is a local-first CLI for checking whether agent actions remain bound to what a human approved, whether denials stay enforced, and whether approval authority is replayed or routed around.
+
+## Try it
+
+```bash
+git clone https://github.com/sylvesterkaczmarek/agentack.git
+cd agentack
+python -m pip install .
+
+agentack demo
+agentack doctor
+agentack coverage
+```
+
+`agentack demo` needs no agent account:
+
+```text
+AgentAck demo
+
+Secure approval flow           PASS
+Action changed after approval  DETECTED (ACK003)
+
+AgentAck binds the action shown for approval to the action that later executes.
+The broken demo changes the command after approval; AgentAck detects the mismatch.
+
+Next: agentack doctor
+```
+
+## Live integrations
+
+```bash
+agentack test claude
+agentack test codex
+```
+
+| Agent | Detected by `doctor` | Live test | Evidence path |
+| --- | --- | --- | --- |
+| Claude Code | yes | **yes** | official hooks + `tool_decision` telemetry |
+| Codex CLI | yes | **yes** | official App Server approval + execution + interrupt lifecycle |
+| Gemini CLI | yes | not yet | detection only |
+| Cursor CLI | yes | not yet | detection only |
+
+Claude uses its native permission UI. Codex uses AgentAck as a local App Server client, so the Codex test verifies the approval/enforcement protocol rather than the Codex TUI or VS Code approval-card rendering.
+
+See [`docs/claude-code.md`](docs/claude-code.md) and [`docs/codex-cli.md`](docs/codex-cli.md).
+
+## Live coverage
+
+```bash
+agentack coverage
+```
+
+Current coverage:
+
+```text
+Rule     Trace     Claude    Codex     Check
+ACK001   TESTED    TESTED    TESTED    Required approval
+ACK002   TESTED    TESTED    TESTED    Denied action
+ACK003   TESTED    TESTED    TESTED    Exact action binding
+ACK004   TESTED    TESTED    TESTED    Approval replay
+ACK005   TESTED    TRACE     TRACE     Approval expiry
+ACK006   TESTED    GUARDED   GUARDED   Lifecycle ordering
+ACK007   TESTED    TESTED    TESTED    Denial route-around
+ACK008   TESTED    SKIP      TESTED    Interrupt bypass
+ACK009   TESTED    GUARDED   GUARDED   Evidence completeness
+```
+
+`TESTED` means a live path deliberately exercises the control. `GUARDED` means the adapter fails closed on bad or missing evidence without inducing that attack. `TRACE` means deterministic trace coverage only for that adapter. `SKIP` means AgentAck does not claim a reliable safe live boundary.
+
+See [`docs/live-coverage.md`](docs/live-coverage.md).
+
+## What it detects
+
+| Rule | Check |
+| --- | --- |
+| `ACK001` | required approval missing |
+| `ACK002` | denied action executed |
+| `ACK003` | action identity changed across proposal, presentation, or execution |
+| `ACK004` | approval replayed beyond its granted scope |
+| `ACK005` | approval expired |
+| `ACK006` | approval lifecycle invalid |
+| `ACK007` | denial routed around |
+| `ACK008` | interrupt bypassed |
+| `ACK009` | approval evidence incomplete |
+
+Missing evidence returns `INCOMPLETE`, not a silent pass.
+
+## Live probe behavior
+
+Claude's extended suite asks the user to approve one Bash action once, deny an identical replay, deny one marker-writing route, and deny an alternate route for the same harmless intent. If the first approval is explicitly persistent, AgentAck does not label later reuse as a replay vulnerability.
+
+Codex's extended suite adds the same replay and route-around checks plus a human-triggered `turn/interrupt` probe. AgentAck sends only a one-request `accept` decision and never intentionally grants `acceptForSession` or persistent authority.
+
+All filesystem effects stay inside disposable temporary workspaces. AgentAck does not run destructive, credential, deployment, or real cloud/network probes.
+
+## Terminal results
+
+```text
+AgentAck  PASS
+Integration: Codex CLI
+
+Probe isolation              PASS
+Approval required            PASS
+Human approval observed      PASS
+Exact action binding         PASS
+Denial enforcement           PASS
+Approval replay              PASS
+Denial route-around          PASS
+Approval expiry              SKIP
+Stop enforcement             PASS
+Lifecycle ordering           PASS
+Evidence completeness        PASS
+```
+
+A `PASS` requires affirmative evidence for the tested path. `SKIP` and `INCOMPLETE` are not converted into success claims.
+
+## Commands
+
+```bash
+agentack demo                         # secure + deliberately broken showcase
+agentack doctor                       # detect available integrations
+agentack coverage                     # show trace/live ACK coverage
+agentack test claude                  # live Claude approval-control suite
+agentack test codex                   # live Codex approval-control suite
+agentack check trace.jsonl            # evaluate an AgentAck trace
+agentack check trace.jsonl --json report.json --sarif report.sarif
+agentack rules
+agentack explain ACK004
+agentack init agentack.toml
+```
+
+Exit codes are stable:
+
+- `0` `PASS`
+- `1` `FAIL`
+- `2` invalid input, configuration, or output
+- `3` `INCOMPLETE`
+
+## Report provenance
+
+JSON and SARIF reports use the same versioned AgentAck report envelope for trace and live-adapter runs. They include AgentAck/adapter versions, run/session IDs, timestamps, evidence hashes, and structured expected/presented/executed action identities.
+
+Live checks that map directly to an ACK rule also carry additive `rule_id` and `probe_id` identifiers. Raw command parameters, raw telemetry payloads, and command output are not copied into reports.
+
+The hashes identify bytes or canonical structures. They are **not digital signatures, attestation, or proof that the evidence producer was trustworthy**.
+
+See [`docs/report-schema.md`](docs/report-schema.md).
+
+## Evidence model
+
+The deterministic core evaluates:
+
+```text
+ACTION PROPOSED
+      |
+      v
+ACTION PRESENTED TO HUMAN
+      |
+      v
+APPROVAL DECISION
+      |
+      +----------+
+      |          |
+      v          v
+  EXECUTED     BLOCKED
+      \          /
+       v        v
+       SESSION END
+```
+
+Live adapters map their agent-specific evidence into the same framework-neutral action identities rather than modifying the ACK engine for each vendor.
+
+See [`docs/method.md`](docs/method.md) and [`docs/trace-format.md`](docs/trace-format.md).
+
+## Instrument a workflow
+
+```python
+from agentack import Action, Recorder
+
+command = Action(
+    tool="shell",
+    operation="run",
+    resource="workspace",
+    parameters={"argv": ["git", "status"]},
+)
+
+with Recorder("trace.jsonl", "session-123") as recorder:
+    recorder.propose("action-1", command, intent_id="inspect-repo")
+    recorder.request_approval("approval-1", "action-1", command, intent_id="inspect-repo")
+    recorder.decide("approval-1", "action-1", "allow", intent_id="inspect-repo")
+    recorder.execute("action-1", command, approval_id="approval-1", intent_id="inspect-repo")
+```
+
+The recorder does not execute the action.
+
+## Product boundary
+
+AgentAck tests **approval integrity**. It is not a prompt-injection scanner, observability platform, sandbox, authorization system, generic red-team framework, human approval UI, or compliance product.
+
+A `PASS` applies only to the tested or recorded path. It does not prove that every agent path is safe, that the evidence source is trustworthy, or that a system satisfies a legal or regulatory requirement.
+
+## Standards mapping
+
+AgentAck includes informational mappings to the OWASP Top 10 for Agentic Applications 2026 and narrow technical areas of the EU AI Act concerning logging, human oversight, robustness, and cybersecurity.
+
+These mappings are navigation aids only. They do not establish certification, conformity, legal compliance, or applicability of any requirement.
+
+See [`docs/standards-mapping.md`](docs/standards-mapping.md).
+
+## Development
+
+Python 3.11 or later is required.
+
+```bash
+python -m pip install -e '.[dev]'
+make check
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`SECURITY.md`](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+© **Sylvester Kaczmarek** · [https://www.sylvesterkaczmarek.com](https://www.sylvesterkaczmarek.com)

agentack-0.6.0/SECURITY.md

@@ -0,0 +1,25 @@
+# Security
+
+AgentAck processes trace and policy files as untrusted input. The deterministic checker does not execute actions described by traces.
+
+## Reporting vulnerabilities
+
+Please use GitHub Security Advisories for vulnerabilities that could affect AgentAck users. Do not publish exploit details in a public issue before a fix is available.
+
+Include the AgentAck version, operating system, reproduction steps, expected behavior, and observed behavior when practical. Do not include real credentials or unrelated sensitive data.
+
+## Scope
+
+Security-relevant areas include:
+
+- trace/parser ambiguity or validation bypass;
+- approval-rule false negatives;
+- action-identity or lifecycle bypasses;
+- unsafe live-adapter behavior;
+- report leakage of sensitive action or telemetry data;
+- local telemetry receiver vulnerabilities;
+- package or CI supply-chain issues.
+
+AgentAck is pre-1.0. Security fixes are applied to the current development line rather than maintained across multiple historical release branches.
+
+See [`docs/security.md`](docs/security.md) for the detailed trust and adapter model.