ctrlrun 0.1.0__tar.gz → 0.2.0__tar.gz

ctrlrun-0.2.0/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Public API names are frozen in `docs/SPEC-v0.1.md` §8. Before 1.0 they may still change, and
+any change to one appears here.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.2.0] — unreleased
+
+Everything below ships. `pip install ctrlrun` still installs nothing but `pyyaml` and
+`click`; the gateway, the ACS hook and the OpenTelemetry sink live in extras.
+
+### Added
+
+- **MCP gateway** — `ctrlrun gateway --upstream <url> --alias <name>`, in `ctrlrun[gateway]`.
+  An existing MCP tool server gets CTRLRun semantics with no agent changes: `tools/call`
+  becomes an Action, everything else is relayed unchanged. The request forwarded upstream is
+  built from the action's *canonical* arguments, so what was hashed, reserved and recorded is
+  byte-for-byte what the tool receives. Serves `2026-07-28` and `2025-03-26`–`2025-11-25` in
+  passthrough. A fresh connection per intercepted call, because "the connection was never
+  established" is the only observation that proves non-execution.
+- **Reconciliation hook** — `@protect(..., reconcile=...)`. The second authority permitted to
+  move a record out of `AMBIGUOUS`, and only where its answer points. An exception, a nonsense
+  return value and a hook that is never called all mean `"unknown"`, which changes nothing.
+- **`Suspended` and `Control.resume`** — an executor may say "the remote asked for something
+  before it will finish". The record stays `EXECUTING`, the lease is extended, the
+  continuation is held, no receipt is written, and the signal reaches the caller. Built for
+  MCP elicitation; used by the ACS adapter for the same reason.
+- **`EventSink`** — a protocol receiving every `Event` and `Receipt`, called after the
+  authoritative store write. `JSONLEventSink` is the v0.1 file writer under that interface.
+  A sink that raises is logged and skipped; it can never change a decision or an outcome.
+- **`OTelEventSink`** — in `ctrlrun[otel]`. One OpenTelemetry span per action, one span event
+  per step, `ctrlrun.*` attributes. Argument values are withheld unless asked for.
+- **`WebhookApprovalProvider`** — core, over stdlib `urllib.request`. One signed POST on
+  `APPROVAL_REQUESTED`; the gateway serves the signed inbound grant/deny at
+  `POST /ctrlrun/approvals/<request_id>`. An undelivered notification is not an approval.
+- **`ctrlrun inspect <action_id>`** — one action's whole history: proposal, decision,
+  approvals, effect, receipt and the event timeline. `--json` emits `ctrlrun.inspection/v1`.
+- **Policy `schema: ctrlrun.policy/v2`** — per-action `effect:`, `resource:` and `mcp:`
+  templates, needed because a gateway call has no decorator to carry them. Where a decorator
+  and the policy disagree, the decorator wins and the mismatch is warned about once.
+- **ACS control hook** — `ctrlrun.acs.AcsControlHook`, in `ctrlrun[gateway]`. Answers the
+  OWASP Agent Control Standard's `steps/toolCallRequest` and `steps/toolCallResult`. See
+  `docs/ACS.md` for the mapping and for the four places ACS is silent. **No compliance
+  claim**: at the commit read there is no ACS reference implementation and no conformance
+  suite, so there is nothing to be conformant with.
+- **`examples/`** — four standalone failure scenarios, an ACS integration example, and nine
+  sector policy templates under `examples/policies/`.
+
+### Changed
+
+- `StateStore.append_event` returns the event as stored, where it returned `None`. Sinks must
+  be called with the `event_id` the store assigned, and the store is the only thing that knows
+  it. Callers that ignore the return value are unaffected. Recorded in `SPEC-v0.1.md` §8.
+- `SQLiteStateStore` no longer writes JSONL. `Control` does, through `JSONLEventSink`, and
+  `Control.from_file()` installs one by default — so the two files land exactly where v0.1 put
+  them and existing evidence directories are unchanged.
+- `docs/SPEC-v0.2.md` §9 amended: it forbade an ACS adapter on the reading that ACS had no
+  stable interface. The v0.1.0 schemas say otherwise, so the adapter ships. The no-claim rule
+  is untouched.
+
+### Deprecated
+
+- **`ctrlrun gateway --principal-from-client-info` — removed in 0.3. Use
+  `--principal-header`.** It takes the agent's name from `_meta["io.modelcontextprotocol/
+  clientInfo"]`, which the MCP revision says is self-reported and *"SHOULD NOT"* be relied on
+  for security decisions. It is offerable in 0.2 only because of a fact that stops being true:
+  a v0.1 policy cannot address the principal at all (`SPEC-v0.1.md` §3.2 refuses `agent_eq`
+  and every other reserved name at load), so an unauthenticated principal misattributes
+  evidence and cannot widen an outcome. v0.3's authority model makes the principal an
+  authorization input, at which point a self-reported name cannot be one. The flag warns at
+  startup and its `--help` says so.
+
+### Removed
+
+- `SQLiteStateStore.journal`, and the `EventLog` class behind it. `JSONLEventSink` is that
+  class under the sink interface, and it is `Control`'s now.
+
+### Fixed
+
+- `.gitignore` ignored `ctrlrun.yaml` unanchored, so it matched at any depth and silently kept
+  every example's policy file out of the repository. Anchored to `/ctrlrun.yaml`.
+
+### Compatibility
+
+- **A v0.1 `ctrlrun.yaml` loads unchanged.** `ctrlrun.policy/v2` is opt-in and additive; a
+  document declaring `v1` that uses a v2 key is a load-time `PolicyError` naming the key and
+  the schema it needs, because a v0.1 reader would ignore the template and execute with no
+  duplicate protection at all.
+- **The receipt schema is unchanged** — `ctrlrun.receipt/v1` still describes every receipt
+  v0.2 writes. `EFFECT_RESOLVED` gains `data.resolved_by`, and four event types join the set:
+  `RECONCILIATION_STARTED`, `RECONCILIATION_RESOLVED`, `EXECUTION_SUSPENDED`,
+  `EXECUTION_RESUMED`.
+- A database written by v0.1 is read by v0.2 without migration: the one new table
+  (`continuations`) is created on open.
+
+### Notes
+
+- The spec is written against **MCP revision 2026-07-28**, which removed the `initialize`
+  handshake, protocol-level sessions and `Mcp-Session-Id`, and made `Mcp-Method` / `Mcp-Name`
+  required request headers that servers must validate against the body. The gateway will also
+  serve `2025-03-26` through `2025-11-25` in passthrough mode, relaying session ids, `GET` SSE
+  streams and `DELETE` without interpreting them; header–body validation applies only where the
+  headers exist. Decisions come from the parsed body on every revision, so header trust is
+  never the guarantee. The deprecated `2024-11-05` HTTP+SSE transport is not served.
+- An MCP tool call held open across a multi round-trip elicitation keeps its effect reservation
+  in `EXECUTING` with an extended lease, so concurrent duplicates stay blocked for the whole
+  exchange and only the final result is mapped to an outcome. This needs the upstream to supply
+  a `requestState`, the protocol's only correlator and an optional one; without it the first
+  leg is `AMBIGUOUS`, because the alternative would let any client walk past duplicate
+  protection by inventing an `inputResponses` field.
+- A policy file using the new `effect:` / `resource:` / `mcp:` keys must declare
+  `schema: ctrlrun.policy/v2`. `ctrlrun.policy/v1` files keep loading unchanged; a `v2` file
+  will not load on 0.1.0, which is the point — 0.1.0 would ignore the effect template and
+  execute with no duplicate protection.
+- MCP tool arguments that CTRLRun cannot canonicalize — any JSON number with a fraction — will
+  be refused by the gateway, never rounded or coerced. Tools that move money through the
+  gateway need integer minor units or decimal strings in their schema.
+
+## [0.1.0] — 2026-09-03
+
+First packaged release. The v0.1 kernel is complete: every acceptance test in
+`docs/SPEC-v0.1.md` §7 passes, including the multi-process concurrency test.
+
+### Added
+
+- **Action** — canonical form, `action_hash`, deep-frozen arguments. `float` is rejected in
+  arguments: `0.1` and `0.10` are the same money and different hashes.
+- **Policy** — YAML loader with `ALLOW` / `APPROVE` / `DENY` and fail-closed defaults. An
+  unknown action is denied; there is no default-allow. See the config-breaking rule below
+  for how condition keys are validated.
+- **`@ctrlrun.protect()`** — binds a function call to an Action, evaluates it, and executes
+  from the action's canonical arguments rather than the caller's objects.
+- **Approval binding** — approvals carry the `action_hash` of what a human saw, and are
+  single-use and expiring. A mutated action cannot present an approval granted for another.
+- **Effect key and reservation** — template-resolved effect identity, reserved atomically
+  across processes via `BEGIN IMMEDIATE` and a unique constraint on `effect_key`.
+- **Effect state machine** — `NEW → RESERVED → EXECUTING → COMMITTED | FAILED | AMBIGUOUS`.
+  Only an executor raising `NotExecuted` produces `FAILED`; every other exception, timeouts
+  included, produces `AMBIGUOUS`, and only a human resolves it.
+- **Receipts and events** — portable JSONL evidence for every action.
+- **CLI** — `init`, `demo`, `approve`, `deny`, `receipts`, `effects`, `resolve`.
+- **`ctrlrun demo`** — four failure scenarios, in process, no network.
+- `SECURITY.md` and `docs/CLAIMS.md`, which maps every README claim to its code and test.
+
+### Config-breaking rules
+
+Rules that reject a policy file which an earlier build of this kernel would have loaded.
+A `ctrlrun.yaml` written before this release may need an edit; the process refuses to start
+until it gets one, which is the point.
+
+- **A condition key naming an `Action` field is now a load-time `PolicyError`.** The
+  reserved names are `action_id`, `agent`, `environment`, `principal`, `resource` and
+  `user`. `when: { environment_eq: production }` reads exactly like it scopes a rule to
+  production, and matched nothing at all — conditions address an action's *arguments*, and
+  those are not arguments. Combined with a catch-all `decision: allow` beneath it, a rule
+  that looked restrictive silently permitted everything. If a protected function genuinely
+  takes an argument by one of those names, rename the argument (SPEC-v0.1 §3.2). Only the
+  whole name is reserved: `resource_id_eq` is unaffected.
+- **A condition on an argument the action does not carry now logs a warning.** The decision
+  is unchanged — still false, still never an error, per SPEC-v0.1 §3.2 — but a typo such as
+  `amont_lte` no longer disappears in silence. Nothing to edit; expect new log output.
+
+### Notes
+
+- Requires Python ≥ 3.11. Runtime dependencies are `pyyaml` and `click`.
+- Single-host only: reservation is atomic across processes on one machine via SQLite.
+  Multi-host needs the Postgres store planned for v0.6.
+- Receipts are not signed. A database administrator can alter history (v0.6).
+- Approver identity is free text and is not authenticated (v0.3).
+- Generated ids (`act_`, `apr_`, `ctr_`) are 128 bits. An approval id is not a bearer token
+  in v0.1 — consuming one needs write access to the store — but it becomes one with the
+  webhook provider in v0.2, and an id format cannot be widened after records exist.
+- Effect key templates do not escape placeholder values, so a crafted argument can make two
+  distinct effects share one key. The result is a refusal rather than a double execution;
+  `docs/THREAT_MODEL.md` states the limit and the workaround.
+- Policy conditions address an action's arguments only. Scoping a rule by environment,
+  resource or principal arrives with the authority model in v0.3.
+
+[Unreleased]: https://github.com/CTRLRun/ctrlrun/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/CTRLRun/ctrlrun/releases/tag/v0.1.0

{ctrlrun-0.1.0 → ctrlrun-0.2.0}/MANIFEST.in

@@ -14,6 +14,12 @@ include VISION.md
 recursive-include docs *.md
 recursive-include tests *.py
 
+# `examples/` travels because T31 runs every script and loads every sector template out of
+# the source tree (SPEC-v0.2 §1.1). Without these the sdist would ship a test suite that
+# fails on a fresh checkout, which is the failure `prune internal` exists to avoid.
+recursive-include examples *.py
+recursive-include examples *.yaml
+
 # Local-only: working notes, and anything an operator's run left behind. Nothing here is
 # picked up by default — these are belt and braces, so a stray file cannot ride along.
 prune internal

{ctrlrun-0.1.0/src/ctrlrun.egg-info → ctrlrun-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrlrun
-Version: 0.1.0
+Version: 0.2.0
 Summary: Make consequential AI-agent actions safe to execute.
 Author-email: Arpan Ghoshal <contact@arpanghoshal.com>
 License-Expression: Apache-2.0
@@ -23,6 +23,12 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: mypy>=2.3; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
+Provides-Extra: gateway
+Requires-Dist: httpx>=0.27; extra == "gateway"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
 Dynamic: license-file
 
 # CTRLRun
@@ -96,6 +102,52 @@ Amounts are integer minor units — cents, not euros. Floats are rejected outrig
 
 Now the same agent can refund €100 on its own, must get a human to approve €2,000, and cannot refund €20,000 at all. Neither can it refund a negative amount, which is a charge wearing a refund's name — an upper bound alone is not a range. Unknown actions are denied. CTRLRun fails closed.
 
+## Protect an existing MCP server
+
+No agent changes. Point the client at the gateway instead of at the tool server:
+
+```bash
+pip install "ctrlrun[gateway]"
+ctrlrun gateway --upstream http://localhost:8000/mcp --alias acme --principal refund-agent
+```
+
+The gateway prints, on the line that starts it, every action in your policy that has no
+`effect:` template — because a write with no effect key is exactly the configuration this
+exists to prevent, and it should not be discovered in a receipt three weeks later:
+
+```text
+1 action(s) have no effect: template and get no reservation:
+  mcp.acme.list_payments
+That is right for a read, and wrong for anything that changes the world.
+```
+
+Tools become actions named `mcp.<alias>.<tool>`, decided by the same `ctrlrun.yaml`. Declare
+their effect and resource templates there, since a tool call has no decorator to carry them:
+
+```yaml
+schema: ctrlrun.policy/v2
+
+actions:
+  mcp.acme.create_refund:
+    effect: "refund:{payment_id}"
+    resource: "payment:{payment_id}"
+    decision: approve
+```
+
+Everything but `tools/call` is relayed untouched. A lost response over the wire blocks the
+retry exactly as it does in-process — that is the whole point of putting it here.
+
+## Two more things
+
+**Resolving an unknown outcome without a human.** `@protect(..., reconcile=...)` takes a
+function that asks the remote what happened to an effect, and it is the only thing besides a
+human permitted to move a record out of `AMBIGUOUS` — and only in the direction its answer
+points.
+
+**Exporting to your tracing backend.** `pip install "ctrlrun[otel]"` adds an
+`OTelEventSink`: one OpenTelemetry span per action, one span event per step. Argument values
+stay out of it unless you ask for them.
+
 ## What `ctrlrun demo` shows
 
 ```console
@@ -152,6 +204,8 @@ CTRLRun cannot guarantee exactly-once execution against external systems it does
 | Doc | Purpose |
 |---|---|
 | [`docs/SPEC-v0.1.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/SPEC-v0.1.md) | The v0.1 contract: models, invariants, acceptance tests |
+| [`docs/SPEC-v0.2.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/SPEC-v0.2.md) | The v0.2 delta: gateway, sinks, reconciliation, webhooks |
+| [`docs/ACS.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ACS.md) | The OWASP Agent Control Standard: what maps, and where it is silent |
 | [`docs/ARCHITECTURE.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ARCHITECTURE.md) | Kernel design and key decisions |
 | [`docs/ROADMAP.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ROADMAP.md) | v0.1 → v1.0 |
 | [`docs/THREAT_MODEL.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/THREAT_MODEL.md) | What CTRLRun defends against and what it doesn't |

{ctrlrun-0.1.0 → ctrlrun-0.2.0}/README.md

@@ -69,6 +69,52 @@ Amounts are integer minor units — cents, not euros. Floats are rejected outrig
 
 Now the same agent can refund €100 on its own, must get a human to approve €2,000, and cannot refund €20,000 at all. Neither can it refund a negative amount, which is a charge wearing a refund's name — an upper bound alone is not a range. Unknown actions are denied. CTRLRun fails closed.
 
+## Protect an existing MCP server
+
+No agent changes. Point the client at the gateway instead of at the tool server:
+
+```bash
+pip install "ctrlrun[gateway]"
+ctrlrun gateway --upstream http://localhost:8000/mcp --alias acme --principal refund-agent
+```
+
+The gateway prints, on the line that starts it, every action in your policy that has no
+`effect:` template — because a write with no effect key is exactly the configuration this
+exists to prevent, and it should not be discovered in a receipt three weeks later:
+
+```text
+1 action(s) have no effect: template and get no reservation:
+  mcp.acme.list_payments
+That is right for a read, and wrong for anything that changes the world.
+```
+
+Tools become actions named `mcp.<alias>.<tool>`, decided by the same `ctrlrun.yaml`. Declare
+their effect and resource templates there, since a tool call has no decorator to carry them:
+
+```yaml
+schema: ctrlrun.policy/v2
+
+actions:
+  mcp.acme.create_refund:
+    effect: "refund:{payment_id}"
+    resource: "payment:{payment_id}"
+    decision: approve
+```
+
+Everything but `tools/call` is relayed untouched. A lost response over the wire blocks the
+retry exactly as it does in-process — that is the whole point of putting it here.
+
+## Two more things
+
+**Resolving an unknown outcome without a human.** `@protect(..., reconcile=...)` takes a
+function that asks the remote what happened to an effect, and it is the only thing besides a
+human permitted to move a record out of `AMBIGUOUS` — and only in the direction its answer
+points.
+
+**Exporting to your tracing backend.** `pip install "ctrlrun[otel]"` adds an
+`OTelEventSink`: one OpenTelemetry span per action, one span event per step. Argument values
+stay out of it unless you ask for them.
+
 ## What `ctrlrun demo` shows
 
 ```console
@@ -125,6 +171,8 @@ CTRLRun cannot guarantee exactly-once execution against external systems it does
 | Doc | Purpose |
 |---|---|
 | [`docs/SPEC-v0.1.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/SPEC-v0.1.md) | The v0.1 contract: models, invariants, acceptance tests |
+| [`docs/SPEC-v0.2.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/SPEC-v0.2.md) | The v0.2 delta: gateway, sinks, reconciliation, webhooks |
+| [`docs/ACS.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ACS.md) | The OWASP Agent Control Standard: what maps, and where it is silent |
 | [`docs/ARCHITECTURE.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ARCHITECTURE.md) | Kernel design and key decisions |
 | [`docs/ROADMAP.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/ROADMAP.md) | v0.1 → v1.0 |
 | [`docs/THREAT_MODEL.md`](https://github.com/CTRLRun/ctrlrun/blob/main/docs/THREAT_MODEL.md) | What CTRLRun defends against and what it doesn't |

ctrlrun-0.2.0/docs/ACS.md

@@ -0,0 +1,205 @@
+# CTRLRun and the Agent Control Standard
+
+What was read, what maps, what does not, and how the adapter is built.
+
+## What was read
+
+The [Agent Control Standard](https://agentcontrolstandard.org/), a project of the OWASP GenAI
+Security Project, in
+[`GenAI-Security-Project/agent-control-standard`](https://github.com/GenAI-Security-Project/agent-control-standard)
+at commit **`c7ad162f69386daac94b89073e3b751e8cdf28b2`** (2026-08-11, *"Raise the Python floor
+to unblock Dependabot security updates"*). The repository was at release **v0.1.1**, with the
+specification version decoupled from the release version at commit `1af1f92` (2026-08-11) and
+tracked separately at **v0.1.0**. Code is Apache-2.0; documentation is CC BY-SA 4.0.
+
+Specifically:
+
+| File | What it gave |
+|---|---|
+| `specification/ACS/acs_schema.json` | the v0.1.0 aggregator; 22 hooks; `oneOf` a RequestEnvelope or a ResponseEnvelope |
+| `specification/v0.1.0/request-envelope.json` | JSON-RPC 2.0; method namespaces; `AcsParams` and its `metadata` identity fields |
+| `specification/v0.1.0/response-envelope.json` | `AcsResult`, and the five decisions |
+| `specification/v0.1.0/hooks/tool-call-request.json` | `steps/toolCallRequest` — `tool`, `arguments`, `operation`, `capability`, `intent` |
+| `specification/v0.1.0/hooks/tool-call-result.json` | `steps/toolCallResult` — `exit_status`, `outputs`, `request_id_ref`, `duration_ms` |
+| `specification/v0.1.0/ask-details.json` | what an `ask` decision must carry |
+| `CONTRIBUTING.md` | DCO required (`git commit -s`); spec changes open a Discussion first; no CLA |
+
+Two things the repository does **not** have at that commit, both of which shaped this work:
+
+- **No reference implementation.** The README's roadmap places a Guardian Agent sample and
+  FastMCP instrumentation at v1. There is a `pyproject.toml`, but it serves the docs and
+  version-sync tooling. So there is nothing to conform *to* except the schemas, and this
+  adapter is written against them directly.
+- **No `examples/` directory**, and so no house format for a community example. `examples/acs/`
+  therefore follows CTRLRun's own convention.
+
+## What ACS defines
+
+Three layers: **Instrument** (runtime hooks and the Guardian Agent pattern), **Trace**
+(OpenTelemetry and OCSF with agent-specific conventions), and **Inspect** (CycloneDX, SPDX and
+SWID for a dynamic Agent BOM). Only Instrument is relevant here.
+
+The wire format is JSON-RPC 2.0. A host fires a hook as a request whose `method` is
+`steps/<hookName>`; a Guardian answers with an `AcsResult` carrying one of five decisions:
+
+```text
+allow · deny · modify · ask · defer
+```
+
+`deny` requires `reasoning`. `modify` requires `reasoning` and `modifications`. `ask` requires
+`reasoning` and `ask_details`. `defer` requires `reasoning` and `defer_details`.
+
+Of the 22 hooks, CTRLRun answers **two**, and it is worth being explicit that it declines the
+other twenty: `SessionStart`, `SessionEnd`, `AgentTrigger`, `TurnStart`, `TurnEnd`,
+`UserMessage`, `AgentResponse`, `KnowledgeRetrieval`, `MemoryContextRetrieval`, `MemoryStore`,
+`PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `SkillRegister`, `SkillLoad`,
+`SkillUnload`, `SystemPing`, `AgbomSnapshot`, `AgbomChanged`. Those are checkpoints about what
+the model is thinking, remembering or composed of. CTRLRun's product rule is that it decides
+actions that can affect the real world, and nothing else — so an unanswered method returns a
+JSON-RPC error in ACS's reserved range rather than an opinion.
+
+## The mapping, hook by hook
+
+### `steps/toolCallRequest` → build the Action, decide it, take the reservation
+
+| ACS field | CTRLRun |
+|---|---|
+| `params.metadata.agent_id` | `Principal.agent` |
+| `params.metadata.user_context.user_id` | `Principal.user` |
+| `params.metadata.environment` | `Action.environment` (ACS's enum passes through; v0.1 §2.1 takes any non-empty string) |
+| `payload.tool.name`, `payload.tool.provider`, `payload.operation` | `Action.name`, as `<prefix>.<provider>.<tool>[.<operation>]` |
+| `payload.arguments` | `Action.arguments`, unwrapped from `{name: {value, provenance}}` to `{name: value}` |
+| — *(ACS has no resource field)* | `Action.resource`, from the policy's `resource:` template (SPEC-v0.2 §3) |
+| `params.request_id` | the continuation that joins this hook to its result |
+
+`operation` is part of the name because two verbs on one tool are two actions, and a policy has
+to be able to say different things about `create` and `void`.
+
+The decision maps out:
+
+| CTRLRun | ACS |
+|---|---|
+| `ALLOW` | `allow` |
+| `DENY` | `deny` + `reasoning` + `reason_codes` |
+| `APPROVE` (`ApprovalRequired`) | `ask` + `reasoning` + `ask_details` |
+| `DuplicateEffect` | `deny`, `reason_codes: ["ctrlrun.duplicate_effect", <state>]` |
+| `AmbiguousEffect` | `deny`, `reason_codes: ["ctrlrun.ambiguous_effect"]` |
+| `ApprovalMismatch` | `deny`, `reason_codes: ["ctrlrun.blocked", <reason>]` |
+
+`ask_details` carries `approver` (`{type: "human", id}`), a `question` naming the request id a
+human answers with `ctrlrun approve`, and `timeout_seconds`. All three are required by
+`ask-details.json`.
+
+`ask_details.intent_extension` is **not** used. It grants capabilities for `this_request` or
+`session`, which is an authority model — CTRLRun has none until v0.3, and a grant it cannot
+represent is one it must not claim to honour.
+
+### `steps/toolCallResult` → close the reservation
+
+ACS describes this hook as *"fires after tool execution, before results reach the agent,
+serving as an output redaction checkpoint"*. CTRLRun redacts nothing, so it always answers
+`allow`; the work is the outcome it records.
+
+`exit_status` is `success | failure | timeout | blocked`. **ACS does not say what any of them
+means for the side effect.** This is the fail-closed reading, and it is the same one
+SPEC-v0.2 §6.8 applies to MCP:
+
+| `exit_status` | Effect state | Why |
+|---|---|---|
+| `success` | `COMMITTED` | the only status that asserts the effect happened |
+| `blocked` | `FAILED` | a control refused it before dispatch — this is what `NotExecuted` means |
+| `failure` | `AMBIGUOUS` | a tool that failed *after* acting and one that failed *before* send the same string |
+| `timeout` | `AMBIGUOUS` | the same, and the case this library exists for |
+| `failure` **with** `mcp.not_executed_on_error: true` | `FAILED` | an operator's per-tool assertion (SPEC-v0.2 §3.1) |
+
+A result whose `request_id_ref` matches no held reservation — a restarted Guardian, a result
+fired twice, one arriving out of order — is logged and nothing is written about an effect.
+Guessing which call it meant is how a duplicate gets committed.
+
+## Where ACS is silent
+
+These are not criticisms of ACS; they are the seam. ACS governs *whether an action may
+proceed*. It has almost nothing to say about *what happened afterwards*, because that is not
+what the Instrument layer was built for.
+
+**1. No effect identity.** `params.request_id` is a per-hook-invocation UUID and
+`request_id_ref` links a result to its request. Neither identifies the *effect*: two calls that
+would refund the same payment get two unrelated UUIDs. There is no idempotency key, no
+`capability`-plus-argument identity, nothing an implementer could use to recognise that a retry
+is a repeat. CTRLRun supplies one from the policy's `effect:` template.
+
+**2. `exit_status` is a status of the call, not an outcome of the effect.** Four values, and
+the vocabulary itself carries the confusion: `timeout` sits alongside `failure` as though both
+were kinds of not-working. The distinction that matters — *did the side effect land?* — has no
+representation. A conformant Guardian reading `timeout` has no way to say "unknown, and a
+retry is unsafe until a human resolves it".
+
+**3. Nothing binds an approval to the exact action.** `ask_details` carries a question and an
+approver. What comes back is a decision on *the request*, and `intent_extension` can widen a
+capability for the session. Neither pins the approval to a canonical form of the arguments, so
+nothing in ACS prevents an agent from getting `refund(2000)` approved and then calling
+`refund(5000)`. CTRLRun binds to `action_hash`, which covers the principal, the arguments, the
+resource and the environment.
+
+**4. No terminal unknown state.** ACS's decisions are about the future of a call. There is no
+way for a Guardian to record that an effect's outcome is unresolved and that *no* further call
+on that effect may proceed until a human says which way it went. `AMBIGUOUS` has no ACS
+counterpart, and it is the state most of CTRLRun's design exists to protect.
+
+**5. The Guardian does not execute.** ACS is advisory by construction — the platform runs the
+tool. That is a reasonable separation, but it means a Guardian cannot make reserve-and-execute
+atomic. The best available is what this adapter does: reserve at the request hook, close at the
+result hook, and accept that a platform which never fires the result hook leaves a reservation
+to lease-expire into `AMBIGUOUS` by the ordinary path of v0.1 §5.3 E3.
+
+## The adapter's design
+
+`ctrlrun.acs.AcsControlHook`, in `ctrlrun[gateway]` — it needs no new dependency, and it is
+kept out of core for the same reason the gateway is: `import ctrlrun` must not grow.
+
+The shape is forced by the seam above. ACS is advisory and CTRLRun is executing, so one action
+is split across two hooks and the reservation is held between them. That is exactly the shape
+`Suspended` and `Control.resume` were built for in SPEC-v0.2 §6.9 — a reservation held across a
+round trip the kernel does not control — so the adapter reuses them rather than reaching for
+the store itself:
+
+```text
+steps/toolCallRequest
+  → Action ← envelope metadata + payload + policy templates
+  → Control.execute(action, executor=raise Suspended(request_id), effect_key)
+      · policy decided, approval consumed, effect reserved, EXECUTION_STARTED
+      · executor suspends: no outcome, no receipt, lease extended, continuation held
+  → allow | deny | ask
+
+steps/toolCallResult
+  → Control.resume(request_id_ref, executor=report(exit_status))
+      · the same outcome mapping execute uses (v0.1 §5.5)
+      · commit / fail / ambiguous, one receipt, same action_id and attempt
+  → allow
+```
+
+`Control` remains the only module that composes the others (ARCHITECTURE §6). The adapter
+translates two vocabularies and decides nothing.
+
+**What it does not do.** It does not use `modify` — CTRLRun refuses or permits an action as
+proposed, and rewriting an agent's arguments is a different product. It does not use `defer`.
+It does not answer the other twenty hooks. It makes no claim of conformance: the schemas are
+`v0.1.0`, the repository is a public preview, there is no reference implementation to test
+against, and there is no conformance suite. **The words "ACS-compatible" do not appear in this
+repository's README, docstrings or CLI output**, and should not until something exists to be
+compatible *with*.
+
+## What the OTel attributes would have to become
+
+SPEC-v0.2 §8's sink emits `ctrlrun.*` attributes. ACS's Trace layer extends OpenTelemetry with
+its own agent conventions and maps security events to OCSF; `acs_schema.json` carries
+`TraceOtelMapping` and `TraceOcsfMapping` definitions for that purpose.
+
+Aligning would mean renaming `ctrlrun.action.name`, `ctrlrun.principal.agent`,
+`ctrlrun.decision` and the rest onto ACS's conventions. The cost is not the rename: it is that
+receipts already written carry the old names, and a receipt is evidence that has to outlive the
+tool that wrote it. Any alignment is therefore additive — emit both, deprecate neither — or it
+is a schema version bump on the receipt, which SPEC-v0.2 §11 explicitly does not do.
+
+That work is not in this release, and the mapping table is deliberately not written yet: it
+would be a compliance claim with nothing behind it.

{ctrlrun-0.1.0 → ctrlrun-0.2.0}/docs/ARCHITECTURE.md

@@ -86,7 +86,7 @@ A retry is a new proposal (`action_id`) for the same logical effect (`effect_key
 ### 4.4 AMBIGUOUS is a first-class terminal state
 A timeout after a request was sent is not a failure. The remote may have committed. Frameworks that map timeout → failed → retry are how double refunds happen. CTRLRun refuses to guess: `AMBIGUOUS` blocks retries until a human resolves it.
 
-*Trade-off:* this creates operational work (someone must run `ctrlrun resolve`). That is the correct place for the work to land. v0.2+ adds `QUERY_STATE` reconciliation for executors that can check the remote side.
+*Trade-off:* this creates operational work (someone must run `ctrlrun resolve`). That is the correct place for the work to land. v0.2 adds a `reconcile` hook (`SPEC-v0.2.md` §2) for executors that can ask the remote what happened: it is the second — and only other — authority permitted to move a record out of `AMBIGUOUS`, and only where its answer points. An answer it cannot give is `"unknown"`, which changes nothing.
 
 ### 4.5 The executor opts into FAILED
 Only `NotExecuted` maps to `FAILED`. Every other exception is `AMBIGUOUS`. The library cannot know whether an arbitrary exception fired before or after the side effect; the executor author can. Making the safe outcome the default means a lazy integration is a safe integration.
@@ -135,16 +135,29 @@ Pragmas: `journal_mode=WAL`, `busy_timeout=5000`, `synchronous=NORMAL`.
 | Module | Owns | Must not know about |
 |---|---|---|
 | `action.py` | model, canonicalization, hash | policy, storage |
-| `policy.py` | YAML → rules → Decision | approvals, effects |
+| `policy.py` | YAML → rules → Decision; `effect:`/`resource:` templates | approvals, effect *state* |
 | `approval.py` | request/grant/consume, providers | executors |
 | `effect.py` | key templating, state enum, transition rules | SQLite |
-| `state.py` | `StateStore` protocol + SQLite/in-memory impls | policy, decorator |
-| `control.py` | `Control` orchestration, decorator, context | CLI |
-| `receipt.py` | Receipt/Event models, JSONL writer | everything else |
+| `state.py` | `StateStore` protocol + SQLite/in-memory impls | policy, decorator, sinks |
+| `control.py` | `Control` orchestration, decorator, context, suspend/resume | CLI |
+| `receipt.py` | Receipt/Event models, `EventSink`, JSONL sink | everything else |
 | `cli/` | click commands, demo | internals beyond `Control` |
 
 Dependencies point downward only. `Control` is the only module that composes the others.
 
+The gateway (v0.2) does not change this. It builds an Action and calls `Control` — including
+`Control.resume` for an elicitation's second leg — rather than reserving and committing for
+itself. A gateway that owned the reservation would be a second module composing the others,
+and a second implementation of SPEC-v0.1 §5.5's asymmetry, which is the one rule in this
+codebase that must not drift.
+
+One exception, added in v0.2 and worth stating rather than discovering: `policy.py` imports the
+template grammar (`template_placeholders`) from `effect.py`, because SPEC-v0.2 §3.1 requires an
+`effect:` / `resource:` template to be validated when the policy loads and the grammar is
+security-critical enough that a second copy of it is worse than the import. Policy still knows
+nothing of effect state — no records, no transitions, no reservations — and `effect.py` does not
+import `policy.py`, so there is no cycle.
+
 ## 7. What changes after v0.1 (and what doesn't)
 
 Stable from v0.1 onward: the four public concepts, the action canonical form (versioned), the effect state machine, fail-closed defaults, the executor outcome mapping.

{ctrlrun-0.1.0 → ctrlrun-0.2.0}/docs/CLAIMS.md

@@ -8,7 +8,7 @@ removed from the README in the same commit — the README is not allowed to desc
 that no longer ships. If you find a row here that does not hold against the version you
 installed, that is a bug: please open an issue.
 
-Regenerated for: **v0.1.0**. Line numbers refer to that tag.
+Regenerated for: **v0.2.0**. Line numbers refer to that tag.
 
 ## The opening paragraph
 
@@ -32,6 +32,35 @@ Regenerated for: **v0.1.0**. Line numbers refer to that tag.
 | "records what actually happened" | `ReceiptResult` — `receipt.py:44`; `Event` and JSONL `append_event` — `receipt.py:222` | `test_T11_every_demo_receipt_carries_every_field_in_the_spec`, `test_T11_every_demo_receipt_parses_back_into_a_Receipt` |
 | "Autonomy belongs to the action, not the agent." | `Policy.evaluate(action)` — `policy.py:233` — passes only the action's **name and arguments** to `_ActionPolicy.evaluate` (`policy.py:164`), whose signature has no principal in it. A rule cannot read who is acting even by accident. `agent_eq` and `user_eq` are refused at load (`policy.py:50`) rather than silently matching nothing. | `test_T6_an_action_name_is_matched_exactly`, `test_a_condition_naming_an_action_field_is_refused_at_load` |
 
+
+## What v0.2 adds to the README
+
+Every sentence the README gained in this release, mapped the same way.
+
+| Claim | Code | Proof |
+|---|---|---|
+| "Point the client at the gateway instead of at the tool server" | `Gateway.handle` — `gateway/server.py:135`; `serve` — `gateway/server.py:892` | `test_T19_the_upstream_receives_the_canonical_arguments` |
+| "No agent changes" | `tools/call` is intercepted and every other method relayed unchanged — `gateway/mcp.py:84` | `test_a_non_intercepted_method_is_relayed_with_no_ctrlrun_outcome` |
+| "The gateway prints … every action in your policy that has no `effect:` template" | `_announce_actions_without_an_effect` — `cli/main.py` | Shown in the README block; produced by `Policy.effect_template` — `policy.py:281` |
+| "Tools become actions named `mcp.<alias>.<tool>`" | `Gateway._intercept` — `gateway/server.py` | `test_T19_the_action_is_named_for_the_alias_and_the_tool` |
+| "Declare their effect and resource templates there" | `Policy.effect_template` / `resource_template` — `policy.py:281`; `McpOptions` — `policy.py:187` | `test_T16_a_v2_document_loads_and_exposes_its_templates`, `test_T16_a_decorator_and_a_policy_template_produce_the_same_action_hash` |
+| "Everything but `tools/call` is relayed untouched" | `parse_request(...).intercept` — `gateway/mcp.py:84` | `test_every_other_method_is_relayed_not_intercepted` |
+| "A lost response over the wire blocks the retry exactly as it does in-process" | `classify` — `gateway/outcome.py:144`, translated into v0.1 §5.5's own vocabulary by the gateway's executor | `test_T23_the_identical_call_sent_again_is_refused_and_the_upstream_called_once` |
+| "the only thing besides a human permitted to move a record out of `AMBIGUOUS`" | `Control._reconciled` — `control.py:713`; `RECONCILED_STATES` — `effect.py` | `test_T13_a_hook_answering_not_executed_moves_the_record_to_failed`, `test_T14_a_hook_answering_committed_refuses_the_retry_as_a_duplicate` |
+| "and only in the direction its answer points" | `"unknown"` is absent from `RECONCILED_STATES` — `effect.py` | `test_T15_a_hook_that_cannot_answer_leaves_the_record_ambiguous` |
+| "one OpenTelemetry span per action, one span event per step" | `OTelEventSink` — `otel.py:45` | `test_T29_one_action_produces_one_span_named_for_the_action`, `test_T29_every_event_becomes_a_span_event_named_by_its_type` |
+| "Argument values stay out of it unless you ask for them" | `OTelEventSink(arguments=...)` — `otel.py:45` | `test_T29_argument_values_are_not_attributes_by_default` |
+
+### Two claims the README deliberately does not make
+
+- **Nothing about ACS conformance.** `ctrlrun.acs.AcsControlHook` (`acs.py:74`) exists and is
+  tested (T51–T55), but at the ACS commit read there is no reference implementation and no
+  conformance suite. "ACS-compatible" appears nowhere in the README, in docstrings, or in CLI
+  output. `docs/ACS.md` says what was read and where the standard is silent.
+- **Nothing about exactly-once execution.** Unchanged from v0.1, and still the honest line:
+  CTRLRun guarantees it will not *knowingly* execute the same logical effect twice, and that
+  it will never treat an unknown outcome as a failure.
+
 ## Two claims stated as limits
 
 The README also makes two negative claims. They matter as much as the positive ones.