graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/agents/langgraph/tests/unit/test_approval_ledger.py

@@ -0,0 +1,1536 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Approvals of gated API calls: the records, who decides, the ledger, and the client's side.
+
+The client's side runs a real graph (the fake model, one gated tool, an
+in-memory checkpointer) that pauses in LangGraph's `interrupt()` and resumes
+with decisions made here, the ledger being an `ApprovalStore`. Every store
+test runs in memory, in memory kept in a file (as under `langgraph dev`), and
+again on Postgres when `TEST_POSTGRES_DSN` is set (see
+`tests/integration/test_postgres.py`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import uuid
+from collections.abc import AsyncIterator, Iterator
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+os.environ.setdefault("MODEL_PROVIDER", "fake")
+
+import httpx
+import pytest
+from langchain.agents import create_agent
+from langchain.tools import ToolRuntime
+from langchain_core.tools import tool
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
+
+from {{cookiecutter.agent_directory}}.app_utils import api_client
+from {{cookiecutter.agent_directory}}.app_utils.api_client import (
+    APPROVAL_DECISION,
+    APPROVAL_INTERRUPT,
+    ApiPolicyError,
+    BoundApproval,
+    call_hash,
+    canonical_call,
+    get_client,
+    redact_fields,
+    reset_policy_cache,
+    set_approval_ledger,
+    stated_purpose,
+)
+from {{cookiecutter.agent_directory}}.app_utils.approvals import (
+    APPROVED,
+    EXPIRED,
+    PENDING,
+    REJECTED,
+    ApprovalRecord,
+    ApprovalStore,
+    LedgerUnavailable,
+    approval_digest,
+    approval_view,
+    decide_refusal,
+    decision_value,
+    dev_ledger_path,
+    digest_refusal,
+    may_decide,
+    may_view,
+    record_from_interrupt,
+    resume_principal,
+    sees_call,
+    utcnow,
+)
+from {{cookiecutter.agent_directory}}.app_utils.approvals import _as_datetime as _as_datetime
+from {{cookiecutter.agent_directory}}.app_utils.approvals import _row_of as _row_of
+from {{cookiecutter.agent_directory}}.app_utils.auth import Actor, Principal
+from {{cookiecutter.agent_directory}}.app_utils.db import Database
+from {{cookiecutter.agent_directory}}.app_utils.threads import ThreadRecord
+
+ALICE = Principal(
+    id="alice", roles=["user"], attributes={"tenant": "t1", "credentials": {"x": "s"}}
+)
+
+POLICY = """
+apis:
+  shop:
+    base_url_env: SHOP_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST]
+    approval:
+      required_for:
+        methods: [POST]
+      approvers: [requester, "role:ops"]
+      timeout_s: 60
+"""
+
+
+def _interrupt_value(**overrides: Any) -> dict[str, Any]:
+    value = {
+        "type": APPROVAL_INTERRUPT,
+        "api": "shop",
+        "method": "POST",
+        "path": "/orders/7/cancel",
+        "query": {"notify": "yes"},
+        "body": {"reason": "asked"},
+        "operation_id": "cancelOrder",
+        "tool": "cancel_order",
+        "tool_call_id": "call-1",
+        "reason": "cancel_order: the customer asked",
+        "approvers": ["requester", "role:ops"],
+        "timeout_s": 60,
+        "rule": "approval.required_for.methods ['POST']",
+        "call_hash": "h1",
+    }
+    value.update(overrides)
+    return value
+
+
+def _record(**overrides: Any) -> ApprovalRecord:
+    fields = {"interrupt_id": "i1", "thread_id": "t1", "run_id": "r1"}
+    value_overrides = {k: v for k, v in overrides.items() if k not in fields}
+    fields.update({k: v for k, v in overrides.items() if k in fields})
+    return record_from_interrupt(_interrupt_value(**value_overrides), requester=ALICE, **fields)
+
+
+ADMIN_DSN = os.environ.get("TEST_POSTGRES_DSN", "")
+# The time zone of the test databases' sessions: not UTC.
+DB_TIME_ZONE = "America/New_York"
+
+
+@pytest.fixture(params=["memory", "file", "postgres"])
+async def store(request: pytest.FixtureRequest, tmp_path: Path) -> AsyncIterator[ApprovalStore]:
+    """The store in memory, in memory kept in a file (`langgraph dev`), and on Postgres
+    when `TEST_POSTGRES_DSN` is set (a fresh database)."""
+    if request.param == "memory":
+        yield ApprovalStore(Database("memory"))
+        return
+    if request.param == "file":
+        kept = ApprovalStore(Database("memory"), path=tmp_path / ".langgraph_api" / "a.json")
+        assert await kept.load() == 0
+        yield kept
+        return
+    if not ADMIN_DSN:
+        pytest.skip("TEST_POSTGRES_DSN is not set")
+    import psycopg
+
+    name = f"gac_test_{uuid.uuid4().hex[:12]}"
+    async with await psycopg.AsyncConnection.connect(ADMIN_DSN, autocommit=True) as admin:
+        await admin.execute(f'CREATE DATABASE "{name}"')
+        # Sessions answer in a zone other than UTC (as a server set up on a laptop does).
+        await admin.execute(f"ALTER DATABASE \"{name}\" SET timezone TO '{DB_TIME_ZONE}'")
+    db = Database("postgres", urlsplit(ADMIN_DSN)._replace(path=f"/{name}").geturl())
+    await db.open()
+    try:
+        yield ApprovalStore(db)
+    finally:
+        await db.close()
+        async with await psycopg.AsyncConnection.connect(ADMIN_DSN, autocommit=True) as admin:
+            await admin.execute(f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE)')
+
+
+# --- records -------------------------------------------------------------------------
+
+
+def test_a_record_holds_the_call_and_never_shows_its_internals() -> None:
+    record = _record()
+    assert record.status == PENDING
+    assert record.expires_at - record.created_at == timedelta(seconds=60)
+    assert record.requester_hash == ALICE.hashed_id()
+    # The run context it resumes with: roles and public attributes, never credentials.
+    assert record.requester_context == {"roles": ["user"], "attributes": {"tenant": "t1"}}
+    public = record.public()
+    assert public["body"] == {"reason": "asked"} and public["query"] == {"notify": "yes"}
+    assert public["reason"] == "cancel_order: the customer asked"
+    for internal in ("call_hash", "interrupt_id", "rule", "tool_call_id", "requester_context"):
+        assert internal not in public
+    hidden = record.public(include_call=False)
+    assert "body" not in hidden and "query" not in hidden
+
+
+@pytest.mark.parametrize(("given", "kept"), [(5, 30), (100_000, 86_400), ("x", 900), (True, 900)])
+def test_the_timeout_is_kept_within_the_policy_bounds(given: Any, kept: int) -> None:
+    record = _record(timeout_s=given)
+    assert record.expires_at - record.created_at == timedelta(seconds=kept)
+
+
+def test_a_pending_record_past_its_expiry_reads_as_expired() -> None:
+    record = _record()
+    assert record.effective_status(record.expires_at - timedelta(seconds=1)) == PENDING
+    assert record.effective_status(record.expires_at) == EXPIRED
+
+
+# --- who decides ---------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("principal", "approvers", "allowed"),
+    [
+        (Principal(id="alice"), ["requester"], True),
+        (Principal(id="alice", roles=["ops"]), ["role:ops"], False),  # no self-approval
+        (Principal(id="alice", roles=["ops"]), ["requester", "role:ops"], True),
+        (Principal(id="carol", roles=["ops"]), ["role:ops"], True),
+        (Principal(id="carol", roles=["ops"]), ["requester"], False),
+        (Principal(id="bob", roles=["user"]), ["requester", "role:ops"], False),
+        (Principal(id="bob", roles=["Ops", "ops-team"]), ["role:ops"], False),
+        (Principal(id=""), ["requester"], False),
+    ],
+)
+def test_who_may_decide(principal: Principal, approvers: list[str], allowed: bool) -> None:
+    assert may_decide(principal, "alice", approvers) is allowed
+
+
+def test_who_may_see(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AUTH_READ_ACROSS_ROLES", "auditor")
+    assert may_view(Principal(id="alice"), "alice", ["role:ops"])  # the owner
+    assert may_view(Principal(id="carol", roles=["ops"]), "alice", ["role:ops"])
+    assert may_view(Principal(id="ann", roles=["auditor"]), "alice", ["role:ops"])
+    assert not may_view(Principal(id="bob"), "alice", ["role:ops"])
+
+
+def test_the_resumed_run_acts_as_the_requester_never_the_decider() -> None:
+    record = _record()
+    carol = Principal(id="carol", roles=["ops", "admin"], attributes={"credentials": {"x": "c"}})
+    acting = resume_principal(record, "alice", carol)
+    assert acting.id == "alice" and acting.roles == ["user"]
+    assert acting.attributes == {"tenant": "t1"}  # no credentials: not stored, not carol's
+    fresh = Principal(id="alice", roles=["user"], attributes={"credentials": {"x": "new"}})
+    assert resume_principal(record, "alice", fresh) is fresh
+
+
+# --- the store and the ledger -----------------------------------------------------------
+
+
+async def test_an_interrupt_asked_again_keeps_its_pending_approval(store: ApprovalStore) -> None:
+    first, created, superseded = await store.add(_record())
+    assert created and superseded == 0
+    again, created, superseded = await store.add(_record())
+    assert not created and again.approval_id == first.approval_id and superseded == 0
+    # The same interrupt asking for a different request supersedes the old one.
+    changed, created, superseded = await store.add(_record(call_hash="h2"))
+    assert created and superseded == 1 and changed.approval_id != first.approval_id
+    assert (await store.get(first.approval_id)).status == EXPIRED
+
+
+async def test_a_decision_is_taken_once(store: ApprovalStore) -> None:
+    record, _, _ = await store.add(_record())
+    results = await asyncio.gather(
+        store.decide(record.approval_id, APPROVED, "a", None),
+        store.decide(record.approval_id, REJECTED, "b", "no"),
+    )
+    winners = [r for r in results if r is not None]
+    assert len(winners) == 1
+    assert await store.decide(record.approval_id, APPROVED, "c", None) is None
+    with pytest.raises(ValueError):
+        await store.decide(record.approval_id, PENDING, "c", None)
+
+
+async def test_decided_records_drop_the_call_unless_full_capture(
+    store: ApprovalStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    record, _, _ = await store.add(_record())
+    decided = await store.decide(record.approval_id, REJECTED, "x", " wrong customer ")
+    assert decided is not None and decided.comment == "wrong customer"
+    assert "body" not in decided.payload and "query" not in decided.payload
+    assert decided.payload["reason"] == "cancel_order: the customer asked"
+    monkeypatch.setenv("TRACE_CAPTURE", "full")
+    kept, _, _ = await store.add(_record(interrupt_id="i2"))
+    decided = await store.decide(kept.approval_id, APPROVED, "x", None)
+    assert decided is not None and decided.payload["body"] == {"reason": "asked"}
+
+
+def test_times_read_from_a_database_are_kept_in_utc() -> None:
+    """A row's times in the session's zone (or naive) read as the same instant in UTC."""
+    for raw in (
+        "2026-09-28T16:17:10.165695-04:00",
+        datetime.fromisoformat("2026-09-28T16:17:10.165695-04:00"),
+        "2026-09-28T20:17:10.165695",
+    ):
+        parsed = _as_datetime(raw)
+        assert parsed is not None and parsed.isoformat() == "2026-09-28T20:17:10.165695+00:00"
+
+
+async def test_times_read_back_are_the_times_written(store: ApprovalStore) -> None:
+    """Whatever the database session's zone (the Postgres store's is not UTC), an approval
+    reads back with the very times it was written with: a relay that reads the approvals
+    ledger binds them into the decision it sends."""
+    record, _, _ = await store.add(_record())
+    got = await store.get(record.approval_id)
+    assert got is not None and got.expires_at.utcoffset() == timedelta(0)
+    for key in ("created_at", "expires_at"):
+        assert got.public()[key] == record.public()[key]
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    assert decided is not None and decided.public()["decided_at"].endswith("+00:00")
+
+
+async def test_an_expired_approval_cannot_be_decided(store: ApprovalStore) -> None:
+    record, _, _ = await store.add(_record())
+    store._clock = lambda: record.expires_at + timedelta(seconds=1)
+    assert await store.decide(record.approval_id, APPROVED, "x", None) is None
+    assert [r.approval_id for r in await store.expire_due()] == [record.approval_id]
+    assert (await store.get(record.approval_id)).status == EXPIRED
+    assert await store.expire_due() == []
+
+
+async def test_the_ledger_lets_an_approval_through_once(store: ApprovalStore) -> None:
+    record, _, _ = await store.add(_record())
+    assert (
+        await store.consume(record.approval_id, "h1", "t1")
+        == "the approval is pending, not approved"
+    )
+    await store.decide(record.approval_id, APPROVED, "x", None)
+    assert await store.consume(record.approval_id, "h2", "t1") == (
+        "the approval is for a different request"
+    )
+    assert await store.consume(record.approval_id, "h1", "t2") == (
+        "the approval belongs to another thread"
+    )
+    assert await store.consume(record.approval_id, "h1", "t1") is None
+    assert await store.consume(record.approval_id, "h1", "t1") == "the approval was already used"
+    assert await store.consume("nope", "h1", "t1") == "no such approval"
+    rejected, _, _ = await store.add(_record(interrupt_id="i3"))
+    await store.decide(rejected.approval_id, REJECTED, "x", None)
+    assert await store.consume(rejected.approval_id, "h1", "t1") == (
+        "the approval is rejected, not approved"
+    )
+
+
+async def test_listing_across_threads(
+    store: ApprovalStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    mine, _, _ = await store.add(_record())
+    other = record_from_interrupt(
+        _interrupt_value(approvers=["role:finance"]),
+        interrupt_id="i9",
+        thread_id="t9",
+        run_id="r9",
+        requester=Principal(id="dora"),
+    )
+    await store.add(other)
+    assert [r.approval_id for r in await store.visible(ALICE)] == [mine.approval_id]
+    carol = Principal(id="carol", roles=["ops"])
+    assert [r.approval_id for r in await store.visible(carol)] == [mine.approval_id]
+    assert await store.visible(Principal(id="bob")) == []
+    monkeypatch.setenv("AUTH_READ_ACROSS_ROLES", "auditor")
+    ann = Principal(id="ann", roles=["auditor"])
+    assert {r.approval_id for r in await store.visible(ann)} == {
+        mine.approval_id,
+        other.approval_id,
+    }
+    assert await store.visible(ALICE, status=APPROVED) == []
+    assert len(await store.visible(ALICE, status=PENDING)) == 1
+    assert await store.delete_for_thread("t1") == 1
+    assert await store.visible(ALICE) == []
+
+
+async def test_the_ledger_names_the_approvals_a_tool_call_asked_for(store: ApprovalStore) -> None:
+    """By the tool call (its model message and call id) or by the interrupt, on any thread."""
+    asked, _, _ = await store.add(_record(message_id="m1", tool_call_id="c1"))
+    copied = record_from_interrupt(
+        _interrupt_value(message_id="m1", tool_call_id="c1", path="/orders/8/cancel"),
+        interrupt_id="i2",
+        thread_id="t-copy",
+        run_id="r2",
+        requester=ALICE,
+    )
+    await store.add(copied)
+    # The same call id in another model message (a model that reuses ids) is another call.
+    await store.add(_record(interrupt_id="i3", message_id="m2", tool_call_id="c1"))
+    await store.decide(asked.approval_id, REJECTED, "x", None)
+    found = await store.bound_approvals(tool_call=("m1", "c1"))
+    assert sorted(found) == [
+        BoundApproval("shop", "POST", "/orders/7/cancel", REJECTED, False),
+        BoundApproval("shop", "POST", "/orders/8/cancel", PENDING, False),
+    ]
+    assert [b.path for b in await store.bound_approvals(interrupt_id="i2")] == ["/orders/8/cancel"]
+    assert await store.bound_approvals(tool_call=("m9", "c1"), interrupt_id="i9") == []
+    assert await store.bound_approvals() == []
+    # Read as a decision would be: used once sent, expired once past its expiry.
+    await store.decide(copied.approval_id, APPROVED, "x", None)
+    assert await store.consume(copied.approval_id, "h1", "t-copy") is None
+    [used] = await store.bound_approvals(interrupt_id="i2")
+    assert used.status == APPROVED and used.used
+    later, _, _ = await store.add(_record(interrupt_id="i4", message_id="m4", tool_call_id="c4"))
+    store._clock = lambda: later.expires_at + timedelta(seconds=1)
+    [expired] = await store.bound_approvals(tool_call=("m4", "c4"))
+    assert expired.status == EXPIRED and not expired.used
+
+
+# --- kept in a file (langgraph dev) -----------------------------------------------------
+
+
+def test_only_langgraph_dev_keeps_the_approvals_in_a_file(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("LANGGRAPH_RUNTIME_EDITION", raising=False)
+    monkeypatch.delenv("LANGGRAPH_DISABLE_FILE_PERSISTENCE", raising=False)
+    assert dev_ledger_path() is None
+    monkeypatch.setenv("LANGGRAPH_RUNTIME_EDITION", "postgres")
+    assert dev_ledger_path() is None
+    monkeypatch.setenv("LANGGRAPH_RUNTIME_EDITION", "inmem")
+    assert dev_ledger_path() == Path(".langgraph_api") / "agent_approvals.json"
+    # No file persistence: the dev server keeps no threads either.
+    monkeypatch.setenv("LANGGRAPH_DISABLE_FILE_PERSISTENCE", "true")
+    assert dev_ledger_path() is None
+    # A database always wins (the path is ignored).
+    assert ApprovalStore(Database("postgres", "postgresql://x/y"), path="a.json").path is None
+
+
+async def test_the_approvals_kept_in_a_file_outlive_the_process(tmp_path: Path) -> None:
+    """What a restart or a hot reload of `langgraph dev` reads back: every state, bound."""
+    path = tmp_path / ".langgraph_api" / "agent_approvals.json"
+    first = ApprovalStore(Database("memory"), path=path)
+    await first.load()
+    pending, _, _ = await first.add(_record(interrupt_id="i1", message_id="m1", tool_call_id="c1"))
+    rejected, _, _ = await first.add(_record(interrupt_id="i2", message_id="m2", tool_call_id="c2"))
+    await first.decide(rejected.approval_id, REJECTED, "x", "no")
+    sent, _, _ = await first.add(_record(interrupt_id="i3", message_id="m3", tool_call_id="c3"))
+    await first.decide(sent.approval_id, APPROVED, "x", None)
+    assert await first.consume(sent.approval_id, "h1", "t1") is None
+    unused, _, _ = await first.add(_record(interrupt_id="i4", message_id="m4", tool_call_id="c4"))
+    await first.decide(unused.approval_id, APPROVED, "x", None)
+    assert path.stat().st_mode & 0o777 == 0o600
+    assert [p.name for p in path.parent.iterdir()] == [path.name]  # no partial file left
+
+    again = ApprovalStore(Database("memory"), path=path)
+    assert await again.load() == 4
+    assert [r.approval_id for r in await again.for_thread("t1")] == [
+        unused.approval_id,
+        sent.approval_id,
+        rejected.approval_id,
+        pending.approval_id,
+    ]
+    for (message_id, call_id), status, used in (
+        (("m1", "c1"), PENDING, False),
+        (("m2", "c2"), REJECTED, False),
+        (("m3", "c3"), APPROVED, True),
+        (("m4", "c4"), APPROVED, False),
+    ):
+        [bound] = await again.bound_approvals(tool_call=(message_id, call_id))
+        assert (bound.status, bound.used) == (status, used)
+    reloaded = await again.get(pending.approval_id)
+    assert reloaded is not None
+    assert reloaded.public() == pending.public() and reloaded.call_hash == pending.call_hash
+    assert reloaded.requester_context == pending.requester_context
+    assert (await again.get(rejected.approval_id)).comment == "no"
+    assert await again.consume(sent.approval_id, "h1", "t1") == "the approval was already used"
+    # A change made after the restart is kept too; a deleted thread takes its approvals.
+    assert await again.decide(pending.approval_id, REJECTED, "y", None) is not None
+    assert await again.delete_for_thread("t1") == 4
+    third = ApprovalStore(Database("memory"), path=path)
+    assert await third.load() == 0
+
+
+@pytest.mark.parametrize("content", [b"{not json", b'{"version": 99, "approvals": []}', b"[]"])
+async def test_an_approvals_file_that_cannot_be_read_stops_the_startup(
+    tmp_path: Path, content: bytes
+) -> None:
+    path = tmp_path / "agent_approvals.json"
+    path.write_bytes(content)
+    with pytest.raises(LedgerUnavailable, match="cannot be read"):
+        await ApprovalStore(Database("memory"), path=path).load()
+
+
+async def test_while_the_file_cannot_be_written_the_store_answers_nothing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A change not in the file could be lost on a restart: nothing is answered until it is."""
+    path = tmp_path / "agent_approvals.json"
+    store = ApprovalStore(Database("memory"), path=path)
+    await store.load()
+    write = store._write
+
+    def broken(change: int, data: bytes) -> None:
+        raise OSError("disk full")
+
+    monkeypatch.setattr(store, "_write", broken)
+    with pytest.raises(LedgerUnavailable, match="could not be written"):
+        await store.add(_record(message_id="m1", tool_call_id="c1"))
+    with pytest.raises(LedgerUnavailable):
+        await store.bound_approvals(tool_call=("m1", "c1"))
+    with pytest.raises(LedgerUnavailable):
+        await store.for_thread("t1")
+    # Written again (the sweep retries it too): the store answers, and the file has it.
+    monkeypatch.setattr(store, "_write", write)
+    [bound] = await store.bound_approvals(tool_call=("m1", "c1"))
+    assert bound.status == PENDING
+    again = ApprovalStore(Database("memory"), path=path)
+    assert await again.load() == 1
+
+
+# --- the call, as bound and as shown ------------------------------------------------------
+
+
+def test_the_call_hash_binds_everything_that_decides_the_request() -> None:
+    base = dict(
+        api="shop",
+        method="post",
+        url="http://shop.test/orders/7/cancel",
+        query=httpx.QueryParams([("a", "1"), ("b", "2")]),
+        json_body={"reason": "asked", "amount": 5},
+        operation_id="cancelOrder",
+        headers=[("If-Match", "v1")],
+    )
+    digest = call_hash(canonical_call(**base))
+    reordered = {**base, "json_body": {"amount": 5, "reason": "asked"}}
+    assert call_hash(canonical_call(**reordered)) == digest
+    for change in (
+        {"method": "PUT"},
+        {"url": "http://shop.test/orders/8/cancel"},
+        {"url": "http://other.test/orders/7/cancel"},
+        {"query": httpx.QueryParams([("b", "2"), ("a", "1")])},
+        {"json_body": {"reason": "asked", "amount": 6}},
+        {"operation_id": "archiveOrder"},
+        {"headers": [("If-Match", "v2")]},
+        {"api": "other"},
+    ):
+        assert call_hash(canonical_call(**{**base, **change})) != digest, change
+    with pytest.raises(ValueError):
+        call_hash(canonical_call(**{**base, "json_body": {"x": float("nan")}}))
+
+
+def test_redacted_fields_are_masked_at_any_depth() -> None:
+    body = {"Card": "4111", "items": [{"card": "4222", "sku": "a"}], "note": {"CARD": 1}}
+    assert redact_fields(body, frozenset({"card"})) == {
+        "Card": "<redacted>",
+        "items": [{"card": "<redacted>", "sku": "a"}],
+        "note": {"CARD": "<redacted>"},
+    }
+    assert redact_fields(body, frozenset()) is body
+
+
+def test_the_stated_purpose_is_the_text_the_model_wrote_with_the_call() -> None:
+    messages = [
+        {"type": "human", "content": "cancel 7"},
+        {
+            "type": "ai",
+            "content": [{"type": "text", "text": "Cancelling order 7\x00 as asked."}],
+            "tool_calls": [{"id": "c1", "name": "cancel_order", "args": {}}],
+        },
+    ]
+    assert stated_purpose(messages, "c1") == "Cancelling order 7 as asked."
+    assert stated_purpose(messages, "c2") is None
+    long = [{"type": "ai", "content": "x" * 900, "tool_calls": [{"id": "c1"}]}]
+    assert len(stated_purpose(long, "c1")) == 500
+
+
+# --- the client's side, in a real graph -------------------------------------------------
+
+SENT: list[httpx.Request] = []
+BODY: dict[str, Any] = {}
+SECOND_CALL: list[bool] = []
+# The tool catches a refusal and tries the same call once more.
+RETRY: list[bool] = []
+
+
+def _upstream(request: httpx.Request) -> httpx.Response:
+    SENT.append(request)
+    return httpx.Response(200, json={"ok": True})
+
+
+@tool
+async def cancel_order(order_id: str, runtime: ToolRuntime[Any]) -> str:
+    """Cancel an order by its id."""
+    client = get_client("shop", transport=httpx.MockTransport(_upstream))
+
+    async def cancel() -> Any:
+        return await client.post(
+            "/orders/{order_id}/cancel",
+            operation_id="cancelOrder",
+            path_params={"order_id": order_id},
+            json_body=dict(BODY),
+        )
+
+    try:
+        data = await cancel()
+    except ApiPolicyError:
+        if not RETRY:
+            raise
+        data = await cancel()
+    if SECOND_CALL:
+        await client.post("/orders", operation_id="createOrder", json_body={"sku": "a"})
+    return json.dumps(data)
+
+
+@pytest.fixture
+def graph(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, store: ApprovalStore) -> Iterator[Any]:
+    from {{cookiecutter.agent_directory}} import agent
+    from {{cookiecutter.agent_directory}}.app_utils.model import get_model
+
+    policy = tmp_path / "api-policy.yaml"
+    policy.write_text(POLICY, encoding="utf-8")
+    monkeypatch.setenv("API_POLICY_PATH", str(policy))
+    monkeypatch.setenv("SHOP_API_BASE_URL", "http://shop.test")
+    reset_policy_cache()
+    SENT.clear()
+    SECOND_CALL.clear()
+    RETRY.clear()
+    BODY.clear()
+    BODY.update({"reason": "asked"})
+    set_approval_ledger(store)
+    yield create_agent(
+        model=get_model(),
+        tools=[cancel_order],
+        system_prompt=agent.SYSTEM_PROMPT,
+        middleware=agent.middleware(),
+        context_schema=agent.AgentContext,
+        checkpointer=InMemorySaver(),
+    )
+    set_approval_ledger(None)
+    reset_policy_cache()
+
+
+async def _run(graph: Any, thread: str, graph_input: Any) -> list[Any]:
+    """Run to the end; the interrupts it paused on (id and value)."""
+    config = {"configurable": {"thread_id": thread}}
+    async for _ in graph.astream(graph_input, config, stream_mode="updates"):
+        pass
+    state = await graph.aget_state(config)
+    return list(state.interrupts)
+
+
+async def _pause(graph: Any, thread: str, store: ApprovalStore) -> tuple[Any, ApprovalRecord]:
+    interrupts = await _run(graph, thread, {"messages": [("user", "Cancel the order for 7")]})
+    assert len(interrupts) == 1
+    record, _, _ = await store.add(
+        record_from_interrupt(
+            interrupts[0].value,
+            interrupt_id=interrupts[0].id,
+            thread_id=thread,
+            run_id="r",
+            requester=ALICE,
+        )
+    )
+    return interrupts[0], record
+
+
+async def _last_tool_result(graph: Any, thread: str) -> str:
+    state = await graph.aget_state({"configurable": {"thread_id": thread}})
+    return next(m.content for m in reversed(state.values["messages"]) if m.type == "tool")
+
+
+async def test_a_gated_call_interrupts_with_the_call_before_anything_is_sent(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    value = interrupt.value
+    assert value["type"] == APPROVAL_INTERRUPT
+    assert (value["method"], value["path"], value["body"]) == ("POST", "/orders/7/cancel", BODY)
+    assert value["tool"] == "cancel_order" and value["tool_call_id"] == "call_cancel_order"
+    assert value["message_id"]  # the model message that made the call
+    assert record.message_id == value["message_id"]
+    assert value["approvers"] == ["requester", "role:ops"] and value["timeout_s"] == 60
+    assert len(value["call_hash"]) == 64
+    assert SENT == [] and record.status == PENDING
+
+
+async def test_approved_the_call_is_sent_once(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert [(r.method, r.url.path) for r in SENT] == [("POST", "/orders/7/cancel")]
+    assert json.loads(SENT[0].content) == BODY
+    assert '"ok": true' in await _last_tool_result(graph, "t1")
+    assert (await store.get(record.approval_id)).used_at is not None
+
+
+async def test_rejected_or_expired_nothing_is_sent(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, REJECTED, "x", "not this one")
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "reject")}))
+    assert "an approver rejected it (their comment: not this one)" in await _last_tool_result(
+        graph, "t1"
+    )
+    interrupt, record = await _pause(graph, "t2", store)
+    await _run(graph, "t2", Command(resume={interrupt.id: decision_value(record, "expired")}))
+    assert "the approval request expired" in await _last_tool_result(graph, "t2")
+    assert SENT == []
+
+
+async def test_a_resume_the_store_did_not_approve_sends_nothing(graph, store) -> None:
+    """A forged resume value (the right hash, an approval still pending) is refused."""
+    interrupt, record = await _pause(graph, "t1", store)
+    forged = decision_value(record, "approve")
+    await _run(graph, "t1", Command(resume={interrupt.id: forged}))
+    assert "the approval is pending, not approved" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+
+
+async def test_a_used_approval_cannot_be_replayed_on_another_run(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    value = decision_value(decided, "approve")
+    await _run(graph, "t1", Command(resume={interrupt.id: value}))
+    assert len(SENT) == 1
+    # The same request, paused on another thread, resumed with the used approval.
+    other, _ = await _pause(graph, "t2", store)
+    await _run(graph, "t2", Command(resume={other.id: value}))
+    assert "the approval belongs to another thread" in await _last_tool_result(graph, "t2")
+    assert len(SENT) == 1
+
+
+async def test_a_request_that_changed_is_not_covered(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    BODY["reason"] = "changed"
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert "differs from the request that was approved" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+
+
+async def test_without_a_ledger_an_approval_is_not_used(graph, store) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    set_approval_ledger(None)
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert "no approvals ledger" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+
+
+async def test_a_tool_call_sends_at_most_one_approved_call(graph, store) -> None:
+    SECOND_CALL.append(True)
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    result = await _last_tool_result(graph, "t1")
+    assert "already sent an approved call" in result
+    assert [r.url.path for r in SENT] == ["/orders/7/cancel"]
+    state = await graph.aget_state({"configurable": {"thread_id": "t1"}})
+    assert not state.interrupts
+
+
+async def test_a_resume_without_a_decision_sends_nothing(graph, store) -> None:
+    interrupt, _ = await _pause(graph, "t1", store)
+    await _run(graph, "t1", Command(resume={interrupt.id: {"decision": "approve"}}))
+    assert "resumed without an approval decision" in await _last_tool_result(graph, "t1")
+    await _pause(graph, "t2", store)
+    assert SENT == []
+
+
+# --- a decision binds its call, whatever the policy says when the run resumes -----------
+
+# The policy as a new image may bring it while a call waits (POLICY gates POST).
+POLICY_CHANGES = {
+    "gate removed": POLICY.split("    approval:")[0],
+    "gate narrowed": POLICY.replace("methods: [POST]", "methods: [DELETE]"),
+    "call denied": POLICY.replace(
+        "    approval:",
+        "    denied_operations:\n      - path: /orders/{order_id}/cancel\n    approval:",
+    ),
+    "allowed_methods narrowed": POLICY.replace(
+        "allowed_methods: [GET, POST]", "allowed_methods: [GET]"
+    ),
+}
+# The policy refuses before any decision is read; else the decision (or the gate) does.
+REFUSED_BY = {
+    "call denied": "denied by denied_operations",
+    "allowed_methods narrowed": "is not in allowed_methods",
+}
+DECIDED_BY = {
+    "reject": "was not approved: an approver rejected it",
+    "expired": "was not approved: the approval request expired",
+    "approve": "approved under an approval gate the policy no longer has",
+}
+
+
+def _change_policy(tmp_path: Path, text: str) -> None:
+    (tmp_path / "api-policy.yaml").write_text(text, encoding="utf-8")
+    reset_policy_cache()
+
+
+async def _decided(store: ApprovalStore, record: ApprovalRecord, decision: str) -> ApprovalRecord:
+    if decision == "expired":
+        closed = await store.expire(record.approval_id)
+    else:
+        status = APPROVED if decision == "approve" else REJECTED
+        closed = await store.decide(record.approval_id, status, "x", None)
+    assert closed is not None
+    return closed
+
+
+@pytest.mark.parametrize("change", list(POLICY_CHANGES))
+@pytest.mark.parametrize("decision", ["reject", "expired", "approve"])
+async def test_a_decision_binds_its_call_whatever_the_policy_says_by_then(
+    graph, store, tmp_path, change: str, decision: str
+) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, decision)
+    _change_policy(tmp_path, POLICY_CHANGES[change])
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, decision)}))
+    result = await _last_tool_result(graph, "t1")
+    assert REFUSED_BY.get(change, DECIDED_BY[decision]) in result, result
+    assert SENT == []
+    assert (await store.get(record.approval_id)).used_at is None
+    state = await graph.aget_state({"configurable": {"thread_id": "t1"}})
+    assert not state.interrupts
+
+
+async def test_an_approval_still_covers_its_call_under_a_gate_with_the_same_approvers(
+    graph, store, tmp_path
+) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, "approve")
+    # Rewritten, still gating the call and asking the same approvers.
+    still_gated = POLICY.replace(
+        "        methods: [POST]", "        operations:\n          - path: /orders/{x}/cancel"
+    )
+    _change_policy(tmp_path, still_gated)
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert [(r.method, r.url.path) for r in SENT] == [("POST", "/orders/7/cancel")]
+    assert (await store.get(record.approval_id)).used_at is not None
+
+
+# --- a list of approval rules: the rule that gates the call names who decides ----------
+
+RULES_POLICY = """
+apis:
+  shop:
+    base_url_env: SHOP_API_BASE_URL
+    auth: none
+    allowed_methods: [GET, POST]
+    approval:
+      - required_for:
+          operations:
+            - {operationId: createOrder, path: /orders, methods: [POST]}
+        approvers: ["role:admin"]
+        timeout_s: 3600
+      - required_for:
+          operations:
+            - {operationId: cancelOrder, path: "/orders/{order_id}/cancel", methods: [POST]}
+        approvers: [requester]
+        timeout_s: 120
+"""
+
+
+async def test_the_approval_is_asked_of_the_rule_that_gates_the_call(
+    graph, store, tmp_path
+) -> None:
+    _change_policy(tmp_path, RULES_POLICY)
+    interrupt, record = await _pause(graph, "t1", store)
+    value = interrupt.value
+    assert (value["approvers"], value["timeout_s"]) == (["requester"], 120)
+    assert value["rule"].startswith("approval[1].required_for.operations (operationId=cancelOrder")
+    # The record keeps those approvers, and they decide: the requester, not an admin.
+    assert record.approvers == ["requester"]
+    assert record.expires_at - record.created_at == timedelta(seconds=120)
+    assert may_decide(ALICE, ALICE.id, record.approvers)
+    assert not may_decide(Principal(id="root", roles=["admin"]), ALICE.id, record.approvers)
+    decided = await _decided(store, record, "approve")
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert [(r.method, r.url.path) for r in SENT] == [("POST", "/orders/7/cancel")]
+
+
+async def test_a_rule_added_after_the_one_that_gated_the_call_keeps_its_approval(
+    graph, store, tmp_path
+) -> None:
+    _change_policy(tmp_path, RULES_POLICY)
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, "approve")
+    # A later rule covering the call too never applies to it: the approval still holds.
+    _change_policy(
+        tmp_path,
+        RULES_POLICY + '      - {required_for: {methods: [POST]}, approvers: ["role:ops"]}\n',
+    )
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert [(r.method, r.url.path) for r in SENT] == [("POST", "/orders/7/cancel")]
+
+
+async def test_rules_that_now_hand_the_call_to_other_approvers_void_its_approval(
+    graph, store, tmp_path
+) -> None:
+    """Bound at pause time: the approvers of the rule that gated the call then."""
+    _change_policy(tmp_path, RULES_POLICY)
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, "approve")
+    # A new image: a POST rule for role:admin now comes first and covers the call.
+    _change_policy(
+        tmp_path,
+        RULES_POLICY.replace(
+            "    approval:\n",
+            '    approval:\n      - {required_for: {methods: [POST]}, approvers: ["role:admin"]}\n',
+        ),
+    )
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert "approval gate that has changed since" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+    assert (await store.get(record.approval_id)).used_at is None
+
+
+async def test_a_call_a_decision_stopped_stays_stopped_in_its_tool_call(
+    graph, store, tmp_path
+) -> None:
+    RETRY.append(True)  # the tool tries the call again once it is refused
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, "reject")
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "reject")}))
+    result = await _last_tool_result(graph, "t1")
+    assert "stopped by its approval decision earlier in this tool call" in result
+    assert SENT == []
+
+
+async def test_a_call_still_waiting_pauses_again_for_its_own_approval(
+    graph, store, tmp_path
+) -> None:
+    """Another call's decision resumed the run: this one waits on, even un-gated meanwhile."""
+    interrupt, record = await _pause(graph, "t1", store)
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(record, "pending")}))
+    assert SENT == []
+    state = await graph.aget_state({"configurable": {"thread_id": "t1"}})
+    [again] = state.interrupts
+    assert again.id == interrupt.id
+    assert again.value["call_hash"] == record.call_hash
+    assert again.value["approvers"] == ["requester", "role:ops"]  # asked of the same approvers
+    kept, created, _ = await store.add(
+        record_from_interrupt(
+            again.value, interrupt_id=again.id, thread_id="t1", run_id="r2", requester=ALICE
+        )
+    )
+    assert not created and kept.approval_id == record.approval_id
+    # Its own decision then applies to it: approved, it is still not sent (no gate now).
+    decided = await _decided(store, record, "approve")
+    await _run(graph, "t1", Command(resume={again.id: decision_value(decided, "approve")}))
+    assert "approval gate the policy no longer has" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+
+
+# --- a tool call run again without a decision (LangGraph Server's own API can) ---------
+
+# What the model reads when the ledger refuses a call its tool call asked an approval for.
+BOUND_BY = {
+    "reject": "was not approved: an approver rejected it",
+    "expired": "was not approved: the approval request expired",
+    "approve": "was sent already with its approval, which is used once",
+    "pending": "was resumed without an approval decision",
+}
+
+
+async def _run_from(graph: Any, config: Any) -> None:
+    """Run the graph from the checkpoint `config` names, without input (a replay)."""
+    async for _ in graph.astream(None, config, stream_mode="updates"):
+        pass
+
+
+@pytest.mark.parametrize("decision", ["reject", "expired", "approve", "pending"])
+async def test_a_tool_call_run_again_without_its_decision_sends_nothing_more(
+    graph, store, tmp_path, decision: str
+) -> None:
+    """Continued without input, or replayed from its checkpoint, whatever the policy says."""
+    interrupt, record = await _pause(graph, "t1", store)
+    paused = (await graph.aget_state({"configurable": {"thread_id": "t1"}})).config
+    if decision != "pending":
+        decided = await _decided(store, record, decision)
+    if decision == "approve":
+        await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, decision)}))
+        assert len(SENT) == 1
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    await _run(graph, "t1", None)  # continue the thread without input
+    await _run_from(graph, paused)  # replay the paused step from its checkpoint (a fork)
+    await _run_from(graph, paused)
+    assert BOUND_BY[decision] in await _last_tool_result(graph, "t1")
+    assert len(SENT) == (1 if decision == "approve" else 0)
+
+
+async def test_a_new_tool_call_is_not_bound_by_an_earlier_one(graph, store, tmp_path) -> None:
+    """The fake model reuses its call ids: a new message makes a new tool call."""
+    interrupt, record = await _pause(graph, "t1", store)
+    decided = await _decided(store, record, "reject")
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "reject")}))
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    await _run(graph, "t1", {"messages": [("user", "Cancel the order for 7")]})
+    assert [r.url.path for r in SENT] == ["/orders/7/cancel"]
+
+
+async def test_without_the_tool_call_scope_the_task_interrupt_binds_the_call(
+    graph, store, tmp_path
+) -> None:
+    """A graph without the agent's middleware: a continued task is known by its interrupt."""
+    from {{cookiecutter.agent_directory}} import agent
+    from {{cookiecutter.agent_directory}}.app_utils.model import get_model
+
+    bare = create_agent(
+        model=get_model(),
+        tools=[cancel_order],
+        context_schema=agent.AgentContext,
+        checkpointer=InMemorySaver(),
+    )
+    _, record = await _pause(bare, "t1", store)
+    assert record.message_id is None and record.tool_call_id is None
+    await _decided(store, record, "reject")
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    with pytest.raises(ApiPolicyError, match="an approver rejected it"):
+        await _run(bare, "t1", None)
+    assert SENT == []
+
+
+class _BrokenLedger:
+    async def consume(self, *args: Any, **kwargs: Any) -> str | None:
+        return "unused"
+
+    async def bound_approvals(self, **kwargs: Any) -> list[BoundApproval]:
+        raise ConnectionError("database down")
+
+
+async def test_a_ledger_that_cannot_answer_refuses_the_call(graph, store, tmp_path) -> None:
+    _change_policy(tmp_path, POLICY_CHANGES["gate removed"])
+    set_approval_ledger(_BrokenLedger())
+    await _run(graph, "t1", {"messages": [("user", "Cancel the order for 7")]})
+    result = await _last_tool_result(graph, "t1")
+    assert "the approvals of this tool call could not be read (ConnectionError)" in result
+    assert SENT == []
+
+
+async def test_outside_an_agent_run_a_gated_call_is_refused(graph) -> None:
+    client = get_client("shop", transport=httpx.MockTransport(_upstream))
+    with pytest.raises(ApiPolicyError) as exc:
+        await client.post("/orders", operation_id="createOrder", json_body={"sku": "a"})
+    assert "possible only inside an agent run" in str(exc.value)
+    assert exc.value.reason.startswith("approval required by approval.required_for.methods")
+    assert SENT == []
+    assert api_client.approval_ledger() is not None  # the fixture's, untouched
+
+
+def test_the_decision_type_is_what_the_client_expects() -> None:
+    assert decision_value(_record(), "approve")["type"] == APPROVAL_DECISION
+    assert utcnow().tzinfo is not None
+
+
+# --- agents acting for a user (0.3): who sees and decides ------------------------------------
+
+CONCIERGE_ACTOR = Actor(id="concierge", chain=("concierge",))
+ALICE_VIA_CONCIERGE = Principal(
+    id="alice",
+    attributes={"tenant": "t1", "@actor": CONCIERGE_ACTOR.public()},
+    actor=CONCIERGE_ACTOR,
+)
+ALICE_VIA_BILLING = Principal(id="alice", actor=Actor(id="billing", chain=("billing",)))
+CONCIERGE_THREAD = ThreadRecord(thread_id="t1", principal_id="alice", actor="concierge")
+DIRECT_THREAD = ThreadRecord(thread_id="t1", principal_id="alice")
+
+
+def test_delegated_cannot_decide_direct_gate() -> None:
+    # The person decides, whichever agent started the thread; the agent never does.
+    for approvers in (["requester"], ["requester", "role:ops"]):
+        assert may_decide(Principal(id="alice"), CONCIERGE_THREAD, approvers)
+        assert decide_refusal(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, approvers) == (
+            "approval_direct_only",
+            "This approval must be decided by the person at this agent (decide_with: direct), "
+            "not relayed by agent concierge.",
+        )
+    # Another agent of the same user, or of another user, learns only that it is no approver.
+    for stranger, thread in (
+        (ALICE_VIA_BILLING, CONCIERGE_THREAD),
+        (ALICE_VIA_CONCIERGE, DIRECT_THREAD),
+        (Principal(id="bob", actor=CONCIERGE_ACTOR), CONCIERGE_THREAD),
+    ):
+        refusal = decide_refusal(stranger, thread, ["requester"])
+        assert refusal is not None and refusal[0] == "not_an_approver"
+    # A delegated principal's roles never make it a role approver.
+    ops_agent = Principal(id="carol", roles=["ops"], actor=CONCIERGE_ACTOR)
+    assert not may_decide(ops_agent, CONCIERGE_THREAD, ["role:ops"])
+    assert may_decide(Principal(id="carol", roles=["ops"]), CONCIERGE_THREAD, ["role:ops"])
+
+
+def test_who_may_see_an_agents_thread(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AUTH_READ_ACROSS_ROLES", "auditor")
+    approvers = ["requester"]
+    assert may_view(Principal(id="alice"), CONCIERGE_THREAD, approvers)  # the person
+    assert may_view(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, approvers)  # the agent that started it
+    assert sees_call(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, approvers)
+    assert not may_view(ALICE_VIA_BILLING, CONCIERGE_THREAD, approvers)
+    assert not sees_call(ALICE_VIA_BILLING, CONCIERGE_THREAD, approvers)
+    auditor_agent = Principal(id="ann", roles=["auditor"], actor=CONCIERGE_ACTOR)
+    assert not may_view(auditor_agent, CONCIERGE_THREAD, approvers)
+    assert may_view(Principal(id="ann", roles=["auditor"]), CONCIERGE_THREAD, approvers)
+
+
+def test_the_requester_actor_is_recorded() -> None:
+    record = record_from_interrupt(
+        _interrupt_value(),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE_VIA_CONCIERGE,
+    )
+    assert record.requester_actor == "concierge"
+    assert record.requester_hash == Principal(id="alice").hashed_id()
+    assert record.requester_context["attributes"]["@actor"]["id"] == "concierge"
+    assert record.public()["requester_actor"] == "concierge"
+    assert _record().public()["requester_actor"] is None
+
+
+def test_the_resumed_run_keeps_the_requesters_actor() -> None:
+    record = record_from_interrupt(
+        _interrupt_value(),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE_VIA_CONCIERGE,
+    )
+    # A role approver's decision: the requester rebuilt, actor included, no credentials.
+    carol = Principal(id="carol", roles=["ops"], attributes={"credentials": {"x": "c"}})
+    acting = resume_principal(record, CONCIERGE_THREAD, carol)
+    assert acting.id == "alice" and acting.actor == CONCIERGE_ACTOR
+    assert "credentials" not in acting.attributes
+    # The person deciding at this agent: their own principal of this request.
+    alice = Principal(id="alice", attributes={"credentials": {"x": "alice's"}})
+    assert resume_principal(record, CONCIERGE_THREAD, alice) is alice
+    # The same owner key: the principal of this request.
+    assert resume_principal(record, CONCIERGE_THREAD, ALICE_VIA_CONCIERGE) == ALICE_VIA_CONCIERGE
+
+
+# --- the user's words of the request that paused (the origin extension) ----------------------
+
+ASKED = {"text": "please cancel order 7", "truncated": False, "hops": 1}
+
+
+def _asked_record(**overrides: Any) -> ApprovalRecord:
+    """An approval of a call the concierge's request paused, with the user's words it forwarded."""
+    fields = {"interrupt_id": "i1", "thread_id": "t1", "run_id": "r1"}
+    value_overrides = {k: v for k, v in overrides.items() if k not in fields}
+    fields.update({k: v for k, v in overrides.items() if k in fields})
+    return record_from_interrupt(
+        _interrupt_value(**value_overrides), requester=ALICE_VIA_CONCIERGE, origin=ASKED, **fields
+    )
+
+
+def test_the_users_words_are_kept_with_the_approval_and_never_shown() -> None:
+    record = _asked_record()
+    assert record.payload["origin"] == ASKED
+    shown = json.dumps(
+        [record.public(), approval_view(record), decision_value(record, "approve")], default=str
+    )
+    assert "origin" not in record.public() and ASKED["text"] not in shown
+    # What the approver sees, and so the digest a relayed decision names, is the same.
+    plain = record_from_interrupt(
+        _interrupt_value(),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE_VIA_CONCIERGE,
+    )
+    assert "origin" not in plain.payload and record.display_digest == plain.display_digest
+
+
+def test_the_resumed_run_acts_on_the_words_of_the_request_that_paused() -> None:
+    record = _asked_record()
+    relayed = {"text": "yes, go ahead", "truncated": False, "hops": 1}
+    relayer = Principal(
+        id="alice",
+        attributes={
+            "@actor": CONCIERGE_ACTOR.public(),
+            "credentials": {"@subject_token": "fresh", "@origin": relayed},
+        },
+        actor=CONCIERGE_ACTOR,
+    )
+    # The agent delivering the person's decision: its fresh token, the request's words (not
+    # the words the person said when approving at the agent that asked).
+    acting = resume_principal(record, CONCIERGE_THREAD, relayer, origin=ASKED)
+    assert acting.id == "alice" and acting.actor == CONCIERGE_ACTOR
+    assert acting.attributes["credentials"] == {"@subject_token": "fresh", "@origin": ASKED}
+    assert relayer.attributes["credentials"]["@origin"] == relayed  # the decider's own: untouched
+    # No words kept with the approval (the request forwarded none): the decision's are not
+    # taken instead.
+    bare = resume_principal(record, CONCIERGE_THREAD, relayer, origin=None)
+    assert bare.attributes["credentials"] == {"@subject_token": "fresh"}
+    # A role approver: the requester rebuilt, with the request's words and no credential.
+    carol = Principal(id="carol", roles=["ops"], attributes={"credentials": {"x": "c"}})
+    rebuilt = resume_principal(record, CONCIERGE_THREAD, carol, origin=ASKED)
+    assert rebuilt.id == "alice" and rebuilt.actor == CONCIERGE_ACTOR
+    assert rebuilt.attributes["credentials"] == {"@origin": ASKED}
+    assert "credentials" not in resume_principal(record, CONCIERGE_THREAD, carol).attributes
+    # The person deciding at this agent acts with their own words.
+    alice = Principal(id="alice", attributes={"credentials": {"x": "alice's"}})
+    assert resume_principal(record, CONCIERGE_THREAD, alice, origin=ASKED) is alice
+
+
+async def test_the_users_words_go_once_the_approval_is_decided_or_expired(
+    store: ApprovalStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("TRACE_CAPTURE", "full")  # the call is kept; the words never are
+    pending, _, _ = await store.add(_asked_record())
+    assert (await store.get(pending.approval_id)).payload["origin"] == ASKED
+    decided = await store.decide(pending.approval_id, APPROVED, "x", None)
+    assert decided is not None and "origin" not in decided.payload
+    assert decided.payload["body"] == {"reason": "asked"}
+    assert "origin" not in (await store.get(pending.approval_id)).payload
+    if store.path is not None:
+        assert ASKED["text"] not in store.path.read_text(encoding="utf-8")
+    # Expired: one the run no longer waits for, one past its time, one superseded.
+    gone, _, _ = await store.add(_asked_record(interrupt_id="i2"))
+    await store.expire(gone.approval_id)
+    first, _, _ = await store.add(_asked_record(interrupt_id="i3"))
+    later, _, _ = await store.add(_asked_record(interrupt_id="i3", call_hash="h2"))
+    store._clock = lambda: later.expires_at + timedelta(seconds=1)
+    assert [r.approval_id for r in await store.expire_due()] == [later.approval_id]
+    for record in (gone, first, later):
+        kept = await store.get(record.approval_id)
+        assert kept.status == EXPIRED and "origin" not in kept.payload, kept
+    if store.path is not None:
+        assert ASKED["text"] not in store.path.read_text(encoding="utf-8")
+
+
+@pytest.mark.parametrize(("runtime", "kept"), [("fastapi", True), ("langgraph-server", False)])
+async def test_the_words_are_kept_only_where_the_resumed_run_can_use_them(
+    runtime: str, kept: bool
+) -> None:
+    """LangGraph Server never passes credentials (the words among them) to tools."""
+    from {{cookiecutter.agent_directory}}.app_utils import chat
+
+    rt = chat.ChatRuntime()
+    rt.runtime = runtime
+    rt.approvals = ApprovalStore(Database("memory"))
+    asking = Principal(
+        id="alice",
+        attributes={"@actor": CONCIERGE_ACTOR.public(), "credentials": {"@origin": ASKED}},
+        actor=CONCIERGE_ACTOR,
+    )
+    [record] = await rt._record_approvals(
+        asking, "t1", "r1", [{"id": "i1", "value": _interrupt_value()}]
+    )
+    assert (record.payload.get("origin") == ASKED) is kept
+    assert ("origin" in record.payload) is kept
+
+
+async def test_listing_follows_the_owner_key(store: ApprovalStore) -> None:
+    by_agent = record_from_interrupt(
+        _interrupt_value(),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE_VIA_CONCIERGE,
+    )
+    by_person, _, _ = await store.add(_record(interrupt_id="i2", thread_id="t2"))
+    await store.add(by_agent)
+    everything = {by_agent.approval_id, by_person.approval_id}
+    assert {r.approval_id for r in await store.visible(ALICE)} == everything
+    assert [r.approval_id for r in await store.visible(ALICE_VIA_CONCIERGE)] == [
+        by_agent.approval_id
+    ]
+    assert await store.visible(ALICE_VIA_BILLING) == []
+    # A delegated principal's roles list nothing a role of theirs could decide.
+    ops_agent = Principal(id="carol", roles=["ops"], actor=CONCIERGE_ACTOR)
+    assert await store.visible(ops_agent) == []
+    reloaded = await store.get(by_agent.approval_id)
+    assert reloaded is not None and reloaded.requester_actor == "concierge"
+
+
+# --- relayed decisions (decide_with: relayed, relayers) ----------------------------------------
+
+RELAYED = {"decide_with": "relayed", "relayers": ["concierge"]}
+
+
+def _relayed_record(**overrides: Any) -> ApprovalRecord:
+    value = _interrupt_value(approvers=["requester"], **{**RELAYED, **overrides})
+    return record_from_interrupt(
+        value, interrupt_id="i1", thread_id="t1", run_id="r1", requester=ALICE_VIA_CONCIERGE
+    )
+
+
+def test_relayed_requires_listed_actor_owner_actor_and_digest() -> None:
+    """The 2.2 table, cell by cell."""
+    record = _relayed_record()
+    rule = {"decide_with": record.decide_with, "relayers": record.relayers}
+    approvers = record.approvers
+    # Direct, the subject (whichever agent started the thread): yes, as under direct.
+    assert decide_refusal(Principal(id="alice"), CONCIERGE_THREAD, approvers, **rule) is None
+    # Direct, another subject holding a listed role: yes (a role gate is always direct).
+    carol = Principal(id="carol", roles=["ops"])
+    assert may_decide(carol, CONCIERGE_THREAD, ["requester", "role:ops"], **rule)
+    # Delegated: all of requester listed, its own thread (subject and actor), a listed relayer.
+    assert decide_refusal(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, approvers, **rule) is None
+    for principal, thread, why in (
+        (ALICE_VIA_BILLING, CONCIERGE_THREAD, "You may not decide this approval"),
+        (ALICE_VIA_CONCIERGE, DIRECT_THREAD, "You may not decide this approval"),
+        (
+            Principal(id="bob", actor=CONCIERGE_ACTOR),
+            ThreadRecord(thread_id="t1", principal_id="bob", actor="concierge"),
+            None,
+        ),
+    ):
+        refusal = decide_refusal(principal, thread, approvers, **rule)
+        if why is None:  # bob's own thread, but alice's approval rule: listed, so it may
+            assert refusal is None
+        else:
+            assert refusal is not None and refusal[0] == "not_an_approver" and why in refusal[1]
+    unlisted = {"decide_with": "relayed", "relayers": ["billing"]}
+    assert decide_refusal(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, approvers, **unlisted) == (
+        "not_an_approver",
+        "concierge may not relay decisions for this approval.",
+    )
+    # A role-only rule is never relayed (the schema refuses it; fail closed anyway).
+    refusal = decide_refusal(ALICE_VIA_CONCIERGE, CONCIERGE_THREAD, ["role:ops"], **rule)
+    assert refusal is not None and refusal[0] == "approval_direct_only"
+    # The digest: required of a relayer, checked when a direct decider sends one.
+    assert digest_refusal(ALICE_VIA_CONCIERGE, record, record.display_digest) is False
+    assert digest_refusal(ALICE_VIA_CONCIERGE, record, None) is True
+    assert digest_refusal(ALICE_VIA_CONCIERGE, record, "sha256:" + "0" * 64) is True
+    assert digest_refusal(Principal(id="alice"), record, None) is False
+    assert digest_refusal(Principal(id="alice"), record, "sha256:x") is True
+    assert digest_refusal(Principal(id="alice"), record, record.display_digest) is False
+
+
+def test_the_digest_covers_what_the_approver_sees() -> None:
+    record = _relayed_record()
+    assert record.display_digest == approval_digest(approval_view(record))
+    assert record.display_digest.startswith("sha256:") and len(record.display_digest) == 71
+    public = record.public()
+    assert public["digest"] == record.display_digest
+    assert (public["decide_with"], public["decided_via"]) == ("relayed", None)
+    assert "relayers" not in public
+    other = _relayed_record(body={"reason": "something else"})
+    assert other.display_digest != record.display_digest
+    assert _record().public()["decide_with"] == "direct"  # a gate without decide_with
+
+
+def test_how_approvers_decide_is_bound_with_the_approvers() -> None:
+    record = _relayed_record()
+    assert (record.decide_with, record.relayers) == ("relayed", ["concierge"])
+    value = decision_value(record, "approve")
+    assert (value["decide_with"], value["relayers"]) == ("relayed", ["concierge"])
+    # An interrupt from before 0.3 (no decide_with) asks for a direct decision.
+    legacy = record_from_interrupt(
+        {k: v for k, v in _interrupt_value().items() if k not in RELAYED},
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE,
+    )
+    assert (legacy.decide_with, legacy.relayers) == ("direct", [])
+    forged = _relayed_record(decide_with="any")
+    assert (forged.decide_with, forged.relayers) == ("direct", [])
+
+
+async def test_decided_via_is_recorded(store: ApprovalStore) -> None:
+    record, _, _ = await store.add(_relayed_record())
+    decided = await store.decide(
+        record.approval_id, APPROVED, Principal(id="alice").hashed_id(), None, "concierge"
+    )
+    assert decided is not None and decided.decided_via == "concierge"
+    reloaded = await store.get(record.approval_id)
+    assert reloaded is not None and reloaded.decided_via == "concierge"
+    assert reloaded.public()["decided_via"] == "concierge"
+    assert (reloaded.decide_with, reloaded.relayers) == ("relayed", ["concierge"])
+    assert reloaded.display_digest == record.display_digest
+
+
+async def test_a_version_1_approvals_file_is_read(tmp_path: Path) -> None:
+    path = tmp_path / ".langgraph_api" / "agent_approvals.json"
+    path.parent.mkdir()
+    row = {
+        k: v
+        for k, v in _row_of(_record()).items()
+        if k not in ("requester_actor", "decide_with", "relayers", "decided_via", "display_digest")
+    }
+    path.write_text(json.dumps({"version": 1, "approvals": [row]}), encoding="utf-8")
+    store = ApprovalStore(Database("memory"), path=path)
+    assert await store.load() == 1
+    [record] = await store.for_thread("t1")
+    assert (record.decide_with, record.relayers, record.requester_actor) == ("direct", [], "")
+    assert record.decided_via is None and record.display_digest is None
+    # The next write is a version-2 file.
+    await store.decide(record.approval_id, REJECTED, "x", None)
+    assert json.loads(path.read_text())["version"] == 2
+
+
+async def test_a_gate_that_starts_relaying_does_not_keep_a_direct_approval(
+    graph, store, tmp_path
+) -> None:
+    interrupt, record = await _pause(graph, "t1", store)
+    assert interrupt.value["decide_with"] == "direct" and interrupt.value["relayers"] == []
+    decided = await _decided(store, record, "approve")
+    relayed = POLICY.replace(
+        "      timeout_s: 60",
+        "      timeout_s: 60\n      decide_with: relayed\n      relayers: [concierge]",
+    )
+    _change_policy(tmp_path, relayed)
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    result = await _last_tool_result(graph, "t1")
+    assert "decide_with or relayers, differs from the policy's now" in result
+    assert SENT == []
+
+
+async def test_a_relayed_gate_binds_its_relayers(graph, store, tmp_path) -> None:
+    relayed = POLICY.replace(
+        '      approvers: [requester, "role:ops"]',
+        "      approvers: [requester]\n      decide_with: relayed\n      relayers: [concierge]",
+    )
+    _change_policy(tmp_path, relayed)
+    interrupt, record = await _pause(graph, "t1", store)
+    assert (interrupt.value["decide_with"], interrupt.value["relayers"]) == (
+        "relayed",
+        ["concierge"],
+    )
+    assert (record.decide_with, record.relayers) == ("relayed", ["concierge"])
+    decided = await _decided(store, record, "approve")
+    # Another relayer by the time the call is sent: the approval does not cover it.
+    _change_policy(tmp_path, relayed.replace("[concierge]", "[billing]"))
+    await _run(graph, "t1", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert "differs from the policy's now" in await _last_tool_result(graph, "t1")
+    assert SENT == []
+    # The same relayers: sent once.
+    _change_policy(tmp_path, relayed)
+    interrupt, record = await _pause(graph, "t2", store)
+    decided = await _decided(store, record, "approve")
+    await _run(graph, "t2", Command(resume={interrupt.id: decision_value(decided, "approve")}))
+    assert [r.url.path for r in SENT] == ["/orders/7/cancel"]
+
+
+# --- a decision relayed to another agent: `nested` and `effect` (0.3) -------------------------
+
+
+def _nested(depth: int = 2, expires_at: str = "2099-01-01T00:00:00+00:00") -> dict[str, Any]:
+    """A relayed approval chain `depth` levels deep (billing relays orders' cancel)."""
+    inner: dict[str, Any] = {
+        "agent": "orders",
+        "approval_id": "o1",
+        "call": {
+            "api": "orders_api",
+            "method": "POST",
+            "path": "/orders/7/cancel",
+            "operation_id": "cancelOrder",
+            "query": {"notify": "yes"},
+            "body": {"card": "4111"},
+        },
+        "reason": "cancel_order: asked",
+        "expires_at": expires_at,
+        "nested": None,
+    }
+    for level in range(depth - 1):
+        inner = {
+            "agent": f"hop{level}",
+            "approval_id": f"h{level}",
+            "call": {"api": "orders_agent", "method": "POST", "path": "/a2a/orders", "body": {}},
+            "reason": "relay",
+            "expires_at": expires_at,
+            "nested": inner,
+        }
+    return inner
+
+
+def _relayed_value(nested: dict[str, Any]) -> dict[str, Any]:
+    from {{cookiecutter.agent_directory}}.app_utils.api_client import approval_effect
+
+    return _interrupt_value(
+        api="billing_agent",
+        path="/a2a/billing",
+        nested=nested,
+        effect=approval_effect(nested),
+        rpc_method="SendMessage",
+        a2a_operation="approve",
+    )
+
+
+def test_a_relayed_approval_shows_the_chain_and_the_effect() -> None:
+    record = record_from_interrupt(
+        _relayed_value(_nested()), interrupt_id="i1", thread_id="t1", run_id="r1", requester=ALICE
+    )
+    public = record.public()
+    assert public["effect"]["path"] == "/orders/7/cancel"
+    assert public["effect"]["via"] == ["hop0", "orders"]
+    assert public["nested"]["nested"]["call"]["body"] == {"card": "4111"}
+    # Viewers who do not see the call (read-across roles) do not see the nested calls either.
+    hidden = record.public(include_call=False)
+    assert "body" not in hidden["nested"]["call"]
+    assert "body" not in hidden["nested"]["nested"]["call"]
+    assert "query" not in hidden["nested"]["nested"]["call"]
+    assert "body" not in hidden["effect"] and "query" not in hidden["effect"]
+    assert hidden["effect"]["path"] == "/orders/7/cancel"
+
+
+def test_a_relayed_approval_expires_before_the_one_it_decides() -> None:
+    """Never ask the person to approve what has expired where it happens: at most the
+    downstream approval's expiry less 5 s (the rule's own timeout otherwise)."""
+    now = utcnow()
+    soon = (now + timedelta(seconds=40)).isoformat()
+    record = record_from_interrupt(
+        _relayed_value(_nested(expires_at=soon)),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE,
+        now=now,
+    )
+    assert record.expires_at == now + timedelta(seconds=35)
+    later = record_from_interrupt(
+        _relayed_value(_nested(expires_at=(now + timedelta(hours=1)).isoformat())),
+        interrupt_id="i1",
+        thread_id="t1",
+        run_id="r1",
+        requester=ALICE,
+        now=now,
+    )
+    assert later.expires_at == now + timedelta(seconds=60)  # the rule's timeout_s
+
+
+async def test_decided_records_drop_the_nested_calls_unless_full_capture(
+    store: ApprovalStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    record, _, _ = await store.add(
+        record_from_interrupt(
+            _relayed_value(_nested(depth=3)),
+            interrupt_id="i1",
+            thread_id="t1",
+            run_id="r1",
+            requester=ALICE,
+        )
+    )
+    decided = await store.decide(record.approval_id, APPROVED, "x", None)
+    assert decided is not None
+    level = decided.payload["nested"]
+    for _ in range(3):
+        assert "body" not in level["call"] and "query" not in level["call"]
+        assert level["call"]["path"]  # the rest of the call stays
+        level = level["nested"]
+    assert level is None
+    effect = decided.payload["effect"]
+    assert "body" not in effect and "query" not in effect and effect["path"] == "/orders/7/cancel"
+    assert (await store.get(record.approval_id)).payload == decided.payload
+    monkeypatch.setenv("TRACE_CAPTURE", "full")
+    kept, _, _ = await store.add(
+        record_from_interrupt(
+            _relayed_value(_nested()),
+            interrupt_id="i2",
+            thread_id="t1",
+            run_id="r1",
+            requester=ALICE,
+        )
+    )
+    decided = await store.decide(kept.approval_id, APPROVED, "x", None)
+    assert decided.payload["nested"]["nested"]["call"]["body"] == {"card": "4111"}
+    assert decided.payload["effect"]["body"] == {"card": "4111"}