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

graph_agents_cli/api/cmd_api.py

@@ -0,0 +1,2480 @@
+# 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.
+
+"""graph-agents-cli api commands: evolve the project's outbound API access policy.
+
+``api-policy.yaml`` belongs to the project and changes over the agent's life:
+``create`` only seeds it (``--api-policy``) or leaves it out, and these
+commands add, widen, narrow and remove access afterwards. Each mutating
+command loads the current file with the rules the runtime enforces, applies
+one change, validates the result, prints a unified diff of every file it
+touches and writes them atomically (``--dry-run`` stops after the diff).
+Comments and key order are kept. Widening access is a reviewed change
+(CODEOWNERS covers the file); the runtime still refuses anything outside the
+policy, whatever a tool declares. ``api approval`` sets the calls that wait
+for a human approval before they are sent (an API's ``approval`` block);
+loosening that gate is reviewed like widening access.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+from rich.markup import escape
+from rich.table import Table
+
+from graph_agents_cli._api_policy import (
+    A2A_APPROVE,
+    A2A_KEY,
+    A2A_OPERATION_KEY,
+    A2A_OPERATIONS,
+    ALLOW_ACTORLESS_KEY,
+    ANY_METHOD,
+    APPROVAL_KEY,
+    AUTH_MODES,
+    DECIDE_DIRECT,
+    DECIDE_RELAYED,
+    DEFAULT_APPROVAL_TIMEOUT_S,
+    DEFAULT_FORWARD_HEADER,
+    DEFAULT_TIMEOUTS_MS,
+    DESCRIPTION_KEY,
+    DESCRIPTION_MAX_CHARS,
+    EXCHANGE_KEY,
+    HEADER_AUTH_MODES,
+    HTTP_METHODS,
+    MAX_APPROVAL_TIMEOUT_S,
+    MAX_RESPONSE_BYTES_LIMIT,
+    MIN_APPROVAL_TIMEOUT_S,
+    POLICY_FILENAME,
+    PROTOCOL_A2A,
+    PROTOCOL_HTTP,
+    PROTOCOL_KEY,
+    PROTOCOLS,
+    REQUESTER_APPROVER,
+    ROLE_APPROVER_PREFIX,
+    RPC_METHOD_KEY,
+    RPC_PROTOCOLS,
+    api_protocol,
+    approval_notes,
+    approval_rule_label,
+    approval_rules,
+    auth_policy_findings,
+    denial_match,
+    describe_deciders,
+    effective_approval,
+    effective_approval_rules,
+    ensure_no_legacy_api_policy,
+    forward_runtime_problem,
+    gate_payload,
+    parse_policy_yaml,
+    policy_errors,
+    rule_conflicts,
+    rule_deciders,
+    rule_never_applies,
+    summarize,
+    uses_exchange,
+)
+from graph_agents_cli._click import LazyGroup
+from graph_agents_cli._output import Console, print_table
+from graph_agents_cli._project import ProjectConfig, chdir_project_root, read_project_config
+from graph_agents_cli.api import _changes as ch
+from graph_agents_cli.api._files import (
+    Plan,
+    env_example_add,
+    env_example_remove,
+    print_diff,
+    read_text,
+    sync_manifest,
+    values_add,
+    values_exchange_add,
+    values_exchange_remove,
+    values_remove,
+)
+from graph_agents_cli.dev import policy_check
+from graph_agents_cli.scaffold.utils.keyedit import EditError, YamlText, block_lines
+
+REVIEW_NOTE = (
+    "Widening access is a reviewed change: open a pull request, where CODEOWNERS "
+    "approves api-policy.yaml."
+)
+GATE_REVIEW_NOTE = (
+    "Loosening an approval gate is a reviewed change, like widening access: open a pull "
+    "request, where CODEOWNERS approves api-policy.yaml."
+)
+NEXT_STEPS = (
+    "Next: declare each call in the tool's API_CALLS, run `graph-agents-cli api check` (or "
+    "`graph-agents-cli lint`), add eval cases for the new behaviour, then open a pull request."
+)
+
+
+@click.group("api", cls=LazyGroup)
+def api_group() -> None:
+    """Declare and change the outbound APIs tools may call (api-policy.yaml).
+
+    The policy belongs to the project and evolves with the agent: add an API,
+    then widen or narrow its access as tools need it. There is no default
+    access: read-only (GET, HEAD) and read-write (GET, HEAD, POST, PUT, PATCH,
+    DELETE) are written into the file as those methods, and custom takes
+    --methods. Every change is validated with the rules the agent
+    enforces, keeps comments and key order, prints a unified diff and writes
+    atomically; --dry-run prints the diff only. The manifest (api_policy,
+    secrets.keys), .env.example and the chart's values.yaml follow the change.
+
+    `api approval` makes chosen calls wait for a human approval before they
+    are sent (requester confirmation, or role:<name> approvers for a second
+    person's review; --add-rule gives other calls of the API other
+    approvers); approval never widens access.
+
+    A JSON-RPC API (`add --protocol jsonrpc`), or another agent over A2A
+    (`--protocol a2a --a2a-path /a2a/<name>`), is judged by the request each
+    POST sends, read from its body: allow, deny and gate it by --rpc-method,
+    and an agent's approve decisions by --a2a-operation(s) approve.
+
+    \b
+    Exit codes:
+      0  changed, or nothing to change
+      1  check: a declared call is refused
+      2  usage error
+      3  invalid result, invalid api-policy.yaml (check too), or not in a project
+    """
+
+
+def _dry_run_option(function: Callable[..., Any]) -> Callable[..., Any]:
+    return click.option(
+        "--dry-run",
+        "dry_run",
+        is_flag=True,
+        default=False,
+        help="Print the diff only; write nothing.",
+    )(function)
+
+
+def _operation_options(function: Callable[..., Any]) -> Callable[..., Any]:
+    function = click.option(
+        "--path", "path", default=None, help="The operation's path template (with --method)."
+    )(function)
+    function = click.option(
+        "--method", "method", default=None, help="The operation's HTTP method (with --path)."
+    )(function)
+    return click.argument("operation_id", required=False)(function)
+
+
+def _entry_options(function: Callable[..., Any]) -> Callable[..., Any]:
+    """allow / deny: OPERATION_ID, --method M --path P, or both (the entry pins all three)."""
+    function = click.option(
+        "--path",
+        "path",
+        default=None,
+        help="The operation's path template (with --method; also with OPERATION_ID).",
+    )(function)
+    function = click.option(
+        "--method",
+        "method",
+        default=None,
+        help="The operation's HTTP method (with --path; also with OPERATION_ID).",
+    )(function)
+    return click.argument("operation_id", required=False)(function)
+
+
+# ---------------------------------------------------------------------------
+# The project and its policy
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Project:
+    root: Path
+    config: ProjectConfig
+    text: str | None  # api-policy.yaml, None when absent
+    document: dict[str, Any] | None
+
+    def api(self, name: str) -> dict[str, Any]:
+        if self.document is None:
+            raise ch.ApiCommandError(
+                f"this project has no {POLICY_FILENAME}: declare an API first with "
+                "`graph-agents-cli api add`"
+            )
+        api = self.document["apis"].get(name)
+        if api is None:
+            declared = ", ".join(sorted(self.document["apis"]))
+            raise ch.ApiCommandError(
+                f"API {name!r} is not declared in {POLICY_FILENAME} (declared: {declared})"
+            )
+        return api
+
+    def editor(self) -> YamlText:
+        assert self.text is not None
+        try:
+            return YamlText(self.text)
+        except EditError as exc:
+            raise ch.ApiCommandError(f"{POLICY_FILENAME} cannot be edited safely: {exc}") from exc
+
+
+def _load_project() -> _Project:
+    chdir_project_root()
+    return load_project_at(Path.cwd())
+
+
+def load_project_at(root: Path) -> _Project:
+    """The project whose root is ``root``, read without changing directory (``system`` reads
+    several); an invalid policy is an ``ApiCommandError`` (exit 3)."""
+    ensure_no_legacy_api_policy(root)
+    config = read_project_config(str(root))
+    text = read_text(root / POLICY_FILENAME)
+    document = None
+    if text is not None:
+        data, errors = parse_policy_yaml(text)
+        errors = errors or policy_errors(data)
+        if errors:
+            lines = "\n".join(f"  - {error}" for error in errors)
+            raise ch.ApiCommandError(
+                f"{POLICY_FILENAME} is invalid; fix it first (graph-agents-cli api check):\n{lines}"
+            )
+        document = dict(data)
+    return _Project(root, config, text, document)
+
+
+def _validate(project: _Project, document: dict[str, Any]) -> None:
+    errors = policy_errors(document)
+    if not errors:
+        problem = forward_runtime_problem(summarize(document), project.config.runtime)
+        if problem:
+            errors.append(problem)
+    if errors:
+        lines = "\n".join(f"  - {error}" for error in errors)
+        raise ch.ApiCommandError(
+            f"The change would make {POLICY_FILENAME} invalid; nothing was written:\n{lines}"
+        )
+
+
+# The order of an API's keys in the schema: a key an edit adds goes after the
+# last key before it in this order, so files stay laid out the same way.
+_API_KEY_ORDER = (
+    DESCRIPTION_KEY,
+    PROTOCOL_KEY,
+    A2A_KEY,
+    "base_url_env",
+    "auth",
+    "token_env",
+    "forward_header",
+    "forward_audience",
+    EXCHANGE_KEY,
+    "allowed_methods",
+    ch.ALLOWED,
+    ch.DENIED,
+    "openapi",
+    "timeouts_ms",
+    "pagination",
+    "limits",
+    "approval",
+)
+
+
+def _after(api: dict[str, Any], key: str) -> str | None:
+    """The existing key of ``api`` a new ``key`` goes after (None: at the end)."""
+    index = _API_KEY_ORDER.index(key)
+    return next((k for k in reversed(_API_KEY_ORDER[:index]) if k in api), None)
+
+
+def _edit(action: Callable[[], None], what: str) -> None:
+    try:
+        action()
+    except EditError as exc:
+        raise ch.ApiCommandError(
+            f"{POLICY_FILENAME} cannot be edited safely ({exc}); nothing was written. "
+            f"Make the change by hand: {what}."
+        ) from exc
+
+
+def _specs(root: Path, document: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
+    specs: dict[str, dict[str, Any]] = {}
+    for name, api in ((document or {}).get("apis") or {}).items():
+        if api.get("openapi"):
+            try:
+                specs[name] = ch.load_spec(root, str(api["openapi"]))
+            except ch.ApiCommandError:
+                continue
+    return specs
+
+
+def _call_effects(
+    project: _Project, before: dict[str, Any] | None, after: dict[str, Any] | None, api: str
+) -> list[str]:
+    """How the change affects the calls the project's tools declare for ``api``."""
+    tools = project.root / project.config.agent_directory / policy_check.TOOLS_SUBDIR
+    calls, _problems = policy_check.collect_declared_calls(tools)
+    specs_before, specs_after = _specs(project.root, before), _specs(project.root, after)
+    lines = []
+    for call in calls:
+        if call.api != api:
+            continue
+        was_result = policy_check.check_call(call, before, specs_before)
+        now_result = policy_check.check_call(call, after, specs_after)
+        was, now = was_result.status, now_result.status
+        label = f"{call.tool}: {call.method} {call.operation}"
+        gate, old_gate = now_result.gate, was_result.gate
+        waits = f" (approvers: {', '.join(gate.approvers)}{_rule_of(gate)})" if gate else ""
+        if was == policy_check.STATUS_ALLOWED and now != policy_check.STATUS_ALLOWED:
+            lines.append(f"now refused: {label}")
+        elif was != policy_check.STATUS_ALLOWED and now == policy_check.STATUS_ALLOWED:
+            lines.append(f"now allowed: {label}{waits}")
+        elif now == policy_check.STATUS_ALLOWED and gate is not None and old_gate is None:
+            lines.append(f"now gated: {label}{waits}")
+        elif now == policy_check.STATUS_ALLOWED and gate is None and old_gate is not None:
+            lines.append(f"no longer gated: {label} (sent without an approval)")
+        elif (
+            now == policy_check.STATUS_ALLOWED
+            and gate is not None
+            and old_gate is not None
+            and set(gate.approvers) != set(old_gate.approvers)
+        ):
+            gained = [a for a in gate.approvers if a not in old_gate.approvers]
+            kind = f"new approver(s) {', '.join(gained)}" if gained else "fewer approvers"
+            lines.append(
+                f"approvers change ({kind}): {label}: now {', '.join(gate.approvers)}"
+                f"{_rule_of(gate)}, was {', '.join(old_gate.approvers)}{_rule_of(old_gate)}"
+            )
+        elif (
+            now == policy_check.STATUS_ALLOWED
+            and gate is not None
+            and old_gate is not None
+            and gate.deciders() != old_gate.deciders()
+        ):
+            relayed = gate.decide_with == DECIDE_RELAYED
+            was_relayed = old_gate.decide_with == DECIDE_RELAYED
+            gained = [r for r in gate.relayers if not was_relayed or r not in old_gate.relayers]
+            kind = (
+                f"new relayer(s) {', '.join(gained)}"
+                if relayed and gained
+                else "fewer relayers"
+                if relayed
+                else "now decided directly"
+            )
+            lines.append(
+                f"relaying changes ({kind}): {label}: now "
+                f"{_deciders_of(gate)}{_rule_of(gate)}, was "
+                f"{_deciders_of(old_gate)}{_rule_of(old_gate)}"
+            )
+    return lines
+
+
+def _deciders_of(gate: Any) -> str:
+    """``requester; relayed by concierge`` for a gate (its approvers, and relayers when any)."""
+    return describe_deciders(
+        {"approvers": gate.approvers, "decide_with": gate.decide_with, "relayers": gate.relayers}
+    )
+
+
+def _rule_of(gate: Any) -> str:
+    """``; rule approval[1]`` when the gate comes from a list of approval rules, else ``""``."""
+    return f"; rule {APPROVAL_KEY}[{gate.index}]" if gate.index is not None else ""
+
+
+_EFFECT_STYLES = {
+    "now refused": "red",
+    "no longer gated": "yellow",
+    "approvers change (new": "yellow",
+    "relaying changes (new": "yellow",
+}
+
+
+def _finish(
+    project: _Project,
+    plan: Plan,
+    *,
+    dry_run: bool,
+    api: str,
+    before: dict[str, Any] | None,
+    after: dict[str, Any] | None,
+    widens: bool | None,
+    notes: list[str] | None = None,
+    next_steps: bool = True,
+    verdict: tuple[str, str] | None = None,
+    effects: list[str] | None = None,
+) -> None:
+    """Show the change and write it. ``widens=None``: the change allows nothing yet.
+
+    ``verdict`` (text, style) replaces the line saying whether access widens:
+    ``api approval`` changes who waits for a human, not what is allowed.
+    ``effects``: the change's effect on the declared calls, when already computed.
+    """
+    console = Console()
+    if not plan.effective:
+        console.print("Nothing to change.")
+        return
+    print_diff(plan.diff())
+    for line in plan.summaries():
+        console.print(escape(line), style="bold", highlight=False)
+    click.echo()
+    for note in notes or []:
+        console.print(f"Note: {escape(note)}", style="yellow", highlight=False)
+    if effects is None:
+        effects = _call_effects(project, before, after, api)
+    if effects:
+        console.print("Effect on the calls your tools declare:")
+        for line in effects:
+            style = next((v for k, v in _EFFECT_STYLES.items() if line.startswith(k)), "green")
+            console.print(f"  {escape(line)}", style=style, highlight=False)
+    if verdict is not None:
+        console.print(escape(verdict[0]), style=verdict[1], highlight=False)
+    elif widens is None:
+        console.print(
+            f"No effect on access to {api} yet (see the notes above); what would make it "
+            f"take effect widens access. {REVIEW_NOTE}",
+            style="yellow",
+        )
+    elif widens:
+        console.print(f"This widens access to {api}. {REVIEW_NOTE}", style="yellow")
+    else:
+        console.print(f"This narrows or keeps access to {api} (always safe).", style="dim")
+    if dry_run:
+        console.print("Dry run: nothing was written.", style="yellow")
+    else:
+        plan.write()
+        written = ", ".join(change.path for change in plan.effective)
+        console.print(f"Wrote {escape(written)}.", style="green")
+    if plan.left_for_you:
+        console.print("Left for you:", style="bold")
+        for item in plan.left_for_you:
+            console.print(f"  - {escape(item)}", highlight=False)
+    if next_steps and not dry_run:
+        console.print(NEXT_STEPS, style="dim")
+
+
+# ---------------------------------------------------------------------------
+# add / remove
+# ---------------------------------------------------------------------------
+
+
+def _policy_header(config: ProjectConfig) -> list[str]:
+    name = config.project_name or "this project"
+    agent = config.agent_directory or "app"
+    return [
+        f"# Outbound API access policy for {name}.",
+        "#",
+        "# Every external API the agent's tools may call, and how. Owned by the project;",
+        "# change it with `graph-agents-cli api ...` or by hand, in a reviewed pull request",
+        "# (CODEOWNERS covers this file). There is no default access: each API lists its",
+        "# methods (and optionally its operations) explicitly.",
+        f"# {agent}/app_utils/api_client.py refuses, before sending, any call outside this",
+        "# file; `graph-agents-cli lint` checks every tool's API_CALLS against it.",
+    ]
+
+
+def _openapi_reference(
+    project: _Project, plan: Plan, name: str, source: Path
+) -> tuple[str, dict[str, Any]]:
+    """Where the project keeps the spec (copied under openapi/<api>/ unless already inside)."""
+    from graph_agents_cli.dev.policy_check import load_openapi
+    from graph_agents_cli.scaffold.utils.openapi_seed import FALLBACK_DIR, _keepable
+
+    try:
+        spec = load_openapi(source)
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        raise ch.ApiCommandError(
+            f"--openapi {source}: not a readable OpenAPI spec ({exc})"
+        ) from exc
+    try:
+        relative = source.resolve().relative_to(project.root.resolve())
+    except ValueError:
+        relative = None
+    kept = _keepable(relative) if relative is not None else None
+    if kept is not None:
+        return kept, spec
+    target = f"{FALLBACK_DIR}/{name}/{source.name}"
+    text = read_text(source) or ""  # copied as stored, line endings included
+    existing = read_text(project.root / target)
+    if existing is not None and existing != text:
+        raise ch.ApiCommandError(
+            f"{target} already exists with other content; move it, or pass a spec inside "
+            "the project"
+        )
+    lines = len(text.splitlines())
+    plan.set_text(
+        target,
+        existing,
+        text,
+        summary=f"new file, a copy of {source} ({lines} lines; not shown)",
+    )
+    return target, spec
+
+
+@api_group.command("add")
+@click.argument("name")
+@click.option(
+    "--base-url-env",
+    "base_url_env",
+    required=True,
+    help="Environment variable holding the API's base URL (e.g. ORDERS_API_BASE_URL).",
+)
+@click.option(
+    "--auth",
+    "auth",
+    type=click.Choice(list(AUTH_MODES)),
+    required=True,
+    help=(
+        "none, bearer (a token from --token-env), forward (the caller's own credential) or "
+        "exchange (a token the issuer mints for --audience in exchange for the caller's, "
+        "RFC 8693)."
+    ),
+)
+@click.option(
+    "--token-env", "token_env", default=None, help="--auth bearer: variable holding the token."
+)
+@click.option(
+    "--forward-header",
+    "forward_header",
+    default=None,
+    help=(
+        "--auth forward or exchange: header the credential is sent in (default "
+        f"{DEFAULT_FORWARD_HEADER})."
+    ),
+)
+@click.option(
+    "--audience",
+    "audience",
+    default=None,
+    help=(
+        "--auth exchange (required): the audience the issuer mints the token for (the target's "
+        "AUTH_JWT_AUDIENCE). --auth forward: forward_audience, the audience the caller's own "
+        "token must name to be forwarded (jwt)."
+    ),
+)
+@click.option(
+    "--scope",
+    "scope",
+    default=None,
+    help="--auth exchange: the scopes to ask for, space separated (least privilege).",
+)
+@click.option(
+    "--resource",
+    "resource",
+    default=None,
+    help="--auth exchange: the target's resource indicator, an absolute URI (RFC 8707).",
+)
+@click.option(
+    "--allow-actorless",
+    "allow_actorless",
+    is_flag=True,
+    default=False,
+    help=(
+        "--auth exchange: accept exchanged tokens that name no actor (exchange.allow_actorless; "
+        "refused by default). Only when the agent behind the API sets AUTH_JWT_DIRECT_CLIENTS "
+        "and lists this agent as client:<its client id> in AUTH_ALLOWED_ACTORS."
+    ),
+)
+@click.option(
+    "--protocol",
+    "protocol",
+    type=click.Choice(list(PROTOCOLS)),
+    default=None,
+    help=(
+        "http (the default), jsonrpc (a JSON-RPC 2.0 API) or a2a (another agent over A2A 1.0 "
+        "JSON-RPC, with --a2a-path): jsonrpc and a2a judge each POST by the JSON-RPC request "
+        "it sends, read from its body."
+    ),
+)
+@click.option(
+    "--a2a-path",
+    "a2a_path",
+    default=None,
+    metavar="PATH",
+    help="--protocol a2a (required): the agent's A2A endpoint, a literal path such as /a2a/orders.",
+)
+@click.option(
+    "--description",
+    "description",
+    default=None,
+    metavar="TEXT",
+    help=f"What the API is for (1-{DESCRIPTION_MAX_CHARS} characters).",
+)
+@click.option(
+    "--access",
+    "access",
+    type=click.Choice(list(ch.ACCESS_CHOICES)),
+    required=True,
+    help=(
+        "Required, no default: read-only (GET, HEAD), read-write (GET, HEAD, POST, PUT, PATCH, "
+        "DELETE) or custom (--methods)."
+    ),
+)
+@click.option("--methods", "methods", default=None, help='--access custom: e.g. GET,POST (or "*").')
+@click.option(
+    "--openapi",
+    "openapi",
+    type=click.Path(exists=True, dir_okay=False, resolve_path=True, path_type=Path),
+    default=None,
+    help="The API's OpenAPI spec (copied under openapi/<name>/ unless inside the project).",
+)
+@click.option(
+    "--max-calls-per-run",
+    type=click.IntRange(min=1),
+    default=None,
+    metavar="N",
+    help="Limit: calls to this API within one agent run.",
+)
+@click.option(
+    "--rate-per-minute",
+    type=click.IntRange(min=1),
+    default=None,
+    metavar="N",
+    help="Limit: calls per minute, per process (replica).",
+)
+@click.option(
+    "--max-response-bytes",
+    type=click.IntRange(min=1, max=MAX_RESPONSE_BYTES_LIMIT),
+    default=None,
+    metavar="N",
+    help="Limit: the most an answer may hold, in bytes (larger answers are discarded).",
+)
+@click.option(
+    "--connect-timeout-ms",
+    type=click.IntRange(min=1),
+    default=None,
+    metavar="N",
+    help="Connect timeout (default 2000).",
+)
+@click.option(
+    "--read-timeout-ms",
+    type=click.IntRange(min=1),
+    default=None,
+    metavar="N",
+    help="Read timeout (default 5000).",
+)
+@_dry_run_option
+def cmd_add(
+    name: str,
+    base_url_env: str,
+    auth: str,
+    token_env: str | None,
+    forward_header: str | None,
+    audience: str | None,
+    scope: str | None,
+    resource: str | None,
+    allow_actorless: bool,
+    protocol: str | None,
+    a2a_path: str | None,
+    description: str | None,
+    access: str,
+    methods: str | None,
+    openapi: Path | None,
+    max_calls_per_run: int | None,
+    rate_per_minute: int | None,
+    max_response_bytes: int | None,
+    connect_timeout_ms: int | None,
+    read_timeout_ms: int | None,
+    dry_run: bool,
+) -> None:
+    """Declare an API with an explicit access choice (creates api-policy.yaml when absent).
+
+    With --protocol a2a (another agent), every message that approves one of that agent's
+    pending approvals is denied (denied_operations: a2a_operation: approve) when POST is
+    allowed: an agent never decides a person's approvals on its own. To relay the person's
+    decision instead, gate it (api approval NAME --a2a-operations approve --approvers
+    requester), then lift the denial (api revoke NAME --a2a-operation approve --from denied).
+    """
+    allowed_methods = ch.access_methods(access, ch.parse_methods(methods))
+    if protocol == PROTOCOL_A2A and not a2a_path:
+        raise click.UsageError(
+            "--protocol a2a needs --a2a-path (the agent's A2A endpoint, such as /a2a/orders)"
+        )
+    if protocol != PROTOCOL_A2A and a2a_path:
+        raise click.UsageError("--a2a-path goes with --protocol a2a only")
+    if protocol == PROTOCOL_A2A and auth == "none":
+        raise click.UsageError(
+            "--protocol a2a needs a credential: --auth bearer, forward or exchange (an agent's "
+            "A2A endpoint authenticates its callers)"
+        )
+    if auth == "bearer" and not token_env:
+        raise click.UsageError("--auth bearer needs --token-env (the variable holding the token)")
+    if auth != "bearer" and token_env:
+        raise click.UsageError("--token-env goes with --auth bearer only")
+    if auth not in HEADER_AUTH_MODES and forward_header:
+        raise click.UsageError("--forward-header goes with --auth forward or exchange only")
+    if auth == "exchange" and not audience:
+        raise click.UsageError(
+            "--auth exchange needs --audience (the audience the issuer mints the token for: "
+            "the target's AUTH_JWT_AUDIENCE)"
+        )
+    if auth not in HEADER_AUTH_MODES and audience:
+        raise click.UsageError("--audience goes with --auth exchange or forward only")
+    if auth != "exchange" and (scope or resource or allow_actorless):
+        raise click.UsageError(
+            "--scope, --resource and --allow-actorless go with --auth exchange only"
+        )
+    project = _load_project()
+    if project.document is not None and name in project.document["apis"]:
+        raise ch.ApiCommandError(
+            f"API {name!r} is already declared; change it with `graph-agents-cli api access`, "
+            "`allow`, `deny`, `revoke` or `limits`"
+        )
+    plan = Plan(project.root)
+    api: dict[str, Any] = {}
+    if description is not None:
+        api[DESCRIPTION_KEY] = description
+    if protocol not in (None, PROTOCOL_HTTP):
+        api[PROTOCOL_KEY] = protocol
+    if a2a_path:
+        api[A2A_KEY] = {"path": a2a_path}
+    api.update({"base_url_env": base_url_env, "auth": auth})
+    if token_env:
+        api["token_env"] = token_env
+    if forward_header:
+        api["forward_header"] = forward_header
+    if auth == "forward" and audience:
+        api["forward_audience"] = audience
+    if auth == "exchange":
+        exchange: dict[str, Any] = {"audience": audience}
+        if scope:
+            exchange["scope"] = scope
+        if resource:
+            exchange["resource"] = resource
+        if allow_actorless:
+            exchange[ALLOW_ACTORLESS_KEY] = True
+        api[EXCHANGE_KEY] = exchange
+    api["allowed_methods"] = allowed_methods
+    holds_approve = protocol == PROTOCOL_A2A and "POST" in ch.effective_methods(allowed_methods)
+    if holds_approve:
+        # Fail closed: this agent must not decide the other agent's approvals on its own.
+        api[ch.DENIED] = [{A2A_OPERATION_KEY: A2A_APPROVE}]
+    if openapi is not None:
+        api["openapi"], _spec = _openapi_reference(project, plan, name, openapi)
+    if connect_timeout_ms or read_timeout_ms:
+        defaults = dict(DEFAULT_TIMEOUTS_MS)
+        api["timeouts_ms"] = {
+            "connect": connect_timeout_ms or defaults["connect"],
+            "read": read_timeout_ms or defaults["read"],
+        }
+    limits = ch.new_limits(
+        None, max_calls_per_run or "keep", rate_per_minute or "keep", max_response_bytes or "keep"
+    )
+    if limits:
+        api["limits"] = limits
+    document = ch.with_api(project.document, name, api)
+    _validate(project, document)
+    matrix_errors, matrix_notes = auth_policy_findings(
+        {"apis": {name: api}}, project.config.auth_policy
+    )
+    if matrix_errors:
+        lines = "\n".join(f"  - {error}" for error in matrix_errors)
+        raise ch.ApiCommandError(
+            f"{name} cannot work in this project; nothing was written:\n{lines}"
+        )
+
+    if project.text is None:
+        lines = [*_policy_header(project.config), "apis:", *block_lines({name: api}, 2)]
+        text = "\n".join(lines) + "\n"
+        if YamlText(text).data != document:
+            raise ch.ApiCommandError("could not write a new api-policy.yaml (internal check)")
+    else:
+        editor = project.editor()
+        _edit(lambda: editor.set(("apis", name), api), f"add apis.{name}")
+        text = editor.text
+    plan.set_text(POLICY_FILENAME, project.text, text)
+    sync_manifest(plan, project.config, document=document, previous=project.document)
+    env_example_add(plan, name, api)
+    values_add(plan, project.config, document, name)
+    values_exchange_add(plan, project.config, document, name)
+    _add_todos(plan, project.config, name, api, first_exchange=not _exchanges(project.document))
+    notes = [
+        f"{name} allows {ch.describe_methods(allowed_methods)}, every operation.",
+        *matrix_notes,
+    ]
+    if holds_approve:
+        notes.append(
+            f"messages to {name} that approve one of its pending approvals are denied "
+            "(denied_operations: a2a_operation: approve): this agent never decides them on its "
+            "own. To relay the person's decision instead, gate them, then lift the denial: "
+            f"graph-agents-cli api approval {name} --a2a-operations approve --approvers "
+            f"requester; graph-agents-cli api revoke {name} --a2a-operation approve --from denied"
+        )
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=True,
+        notes=notes,
+    )
+
+
+def _exchanges(document: dict[str, Any] | None) -> bool:
+    """Whether the policy has an ``auth: exchange`` API."""
+    return document is not None and uses_exchange(summarize(document))
+
+
+def _add_todos(
+    plan: Plan,
+    config: ProjectConfig,
+    name: str,
+    api: dict[str, Any],
+    *,
+    first_exchange: bool = True,
+) -> None:
+    variable = api["base_url_env"]
+    if api_protocol(api) in RPC_PROTOCOLS:
+        plan.left_for_you.append(
+            f'declare each POST to {name} in API_CALLS with its "rpc_method" (the JSON-RPC '
+            "method it sends: the client reads it from the body and judges the call by it)"
+        )
+    where = "in .env (local runs)"
+    if config.deployment_target == "kubernetes":
+        where += (
+            " and per environment in the chart's values-<env>.yaml env: (values.yaml holds "
+            "a placeholder); only base URLs and tokens differ between environments"
+        )
+    plan.left_for_you.append(f"set {variable} {where}")
+    if api["auth"] == "bearer" and config.deployment_target == "kubernetes":
+        plan.left_for_you.append(
+            f"put {api['token_env']} in .env and in .env.<env>, then run "
+            "`graph-agents-cli secrets apply --env <env>`"
+        )
+    elif api["auth"] == "bearer":
+        plan.left_for_you.append(
+            f"put {api['token_env']} in .env (local runs) and in the environment the agent runs in"
+        )
+    elif api["auth"] == "forward" and api.get("forward_audience"):
+        plan.left_for_you.append(
+            f"have the issuer mint the users' tokens for audience {api['forward_audience']} too "
+            "(the caller's own token is forwarded only when its aud names it), or make the auth "
+            f"policy give callers attributes['credentials']['{name}']"
+        )
+    elif api["auth"] == "forward":
+        plan.left_for_you.append(
+            f"make the auth policy give callers attributes['credentials']['{name}'] "
+            "(the credential forwarded to the API)"
+        )
+    elif api["auth"] == EXCHANGE_KEY:
+        audience = api[EXCHANGE_KEY]["audience"]
+        if first_exchange:
+            where = "in .env" + (
+                " and in the chart's values-<env>.yaml env:"
+                if config.deployment_target == "kubernetes"
+                else ""
+            )
+            plan.left_for_you.append(
+                f"set TOKEN_EXCHANGE_URL (the issuer's token endpoint) and TOKEN_EXCHANGE_CLIENT_ID "
+                f"(this agent's client there) {where}; put TOKEN_EXCHANGE_CLIENT_SECRET in .env"
+                + (
+                    " and in .env.<env>, then run `graph-agents-cli secrets apply --env <env>`"
+                    if config.deployment_target == "kubernetes"
+                    else " and in the environment the agent runs in"
+                )
+            )
+        plan.left_for_you.append(
+            f"at the issuer, let this agent's client exchange users' tokens for audience "
+            f"{audience} (and name it in the exchanged token's act claim)"
+        )
+        if api[EXCHANGE_KEY].get(ALLOW_ACTORLESS_KEY) is True:
+            plan.left_for_you.append(
+                f"on the agent behind {name}: AUTH_JWT_AUDIENCE includes {audience}; set "
+                "AUTH_JWT_DIRECT_CLIENTS=<the clients people sign in with>, and list this agent "
+                "in AUTH_ALLOWED_ACTORS as client:<its client id> (and as its act id, if the "
+                "issuer names one). exchange.allow_actorless lets this agent send tokens that "
+                "name no actor: without those settings, that agent reads this agent's calls as "
+                "the person's own, and this agent could decide the person's approvals there"
+            )
+        else:
+            plan.left_for_you.append(
+                f"on the agent behind {name}: AUTH_JWT_AUDIENCE includes {audience}, and "
+                "AUTH_ALLOWED_ACTORS includes this agent's client id"
+            )
+            plan.left_for_you.append(
+                "check that the issuer names this agent in the exchanged token's act claim "
+                "(some issuers, Keycloak among them, add none; decode one to see): this agent "
+                f"refuses a token that names no actor, so calls to {name} fail. The opt-in "
+                f"exchange.allow_actorless: true (api add --allow-actorless) needs, on the agent "
+                f"behind {name}, AUTH_JWT_DIRECT_CLIENTS=<the clients people sign in with> and "
+                "this agent in AUTH_ALLOWED_ACTORS as client:<its client id>"
+            )
+
+
+@api_group.command("remove")
+@click.argument("name")
+@_dry_run_option
+def cmd_remove(name: str, dry_run: bool) -> None:
+    """Remove an API (the last one removes api-policy.yaml)."""
+    project = _load_project()
+    api = project.api(name)
+    assert project.document is not None
+    document = copy.deepcopy(project.document)
+    del document["apis"][name]
+    plan = Plan(project.root)
+    after: dict[str, Any] | None = document
+    if not document["apis"]:
+        after = None
+        plan.set_text(POLICY_FILENAME, project.text, None)
+    else:
+        editor = project.editor()
+        _edit(lambda: editor.delete(("apis", name)), f"delete apis.{name}")
+        plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    sync_manifest(plan, project.config, document=after, previous=project.document)
+    others = list(document["apis"].values())
+    keep = {str(o["base_url_env"]) for o in others} | {
+        str(o["token_env"]) for o in others if o.get("token_env")
+    }
+    env_example_remove(plan, name, api, keep, document["apis"])
+    if api["base_url_env"] not in keep:
+        values_remove(
+            plan, project.config, api["base_url_env"], {str(o["base_url_env"]) for o in others}
+        )
+    if api["auth"] == EXCHANGE_KEY and not _exchanges(document if others else None):
+        values_exchange_remove(plan, project.config)
+    if api.get("openapi"):
+        plan.left_for_you.append(f"delete {api['openapi']} if nothing else uses it")
+    notes = []
+    if after is None:
+        notes.append(
+            f"{name} was the only API: {POLICY_FILENAME} goes, so every outbound call is refused"
+        )
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=after,
+        widens=False,
+        notes=notes,
+        next_steps=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# access / allow / deny / revoke / limits
+# ---------------------------------------------------------------------------
+
+
+@api_group.command("access")
+@click.argument("name")
+@click.argument("access", type=click.Choice(list(ch.ACCESS_CHOICES)))
+@click.option("--methods", "methods", default=None, help='custom: e.g. GET,POST (or "*").')
+@_dry_run_option
+def cmd_access(name: str, access: str, methods: str | None, dry_run: bool) -> None:
+    """Set the HTTP methods an API allows (read-only, read-write, or custom --methods)."""
+    new_methods = ch.access_methods(access, ch.parse_methods(methods))
+    project = _load_project()
+    api = project.api(name)
+    old_methods = [str(m).upper() for m in api["allowed_methods"]]
+    if sorted(old_methods) == sorted(new_methods):
+        Console().print(f"{name} already allows {ch.describe_methods(old_methods)}.")
+        return
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    document["apis"][name]["allowed_methods"] = new_methods
+    _validate(project, document)
+    editor = project.editor()
+    _edit(
+        lambda: editor.set(("apis", name, "allowed_methods"), new_methods),
+        f"set apis.{name}.allowed_methods to {new_methods}",
+    )
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    before_set = set(ch.effective_methods(old_methods))
+    after_set = set(ch.effective_methods(new_methods))
+    notes = [f"{name}: {ch.describe_methods(old_methods)} -> {ch.describe_methods(new_methods)}"]
+    for entry in api.get(ch.ALLOWED) or []:
+        pinned = {str(m).upper() for m in entry.get("methods") or []}
+        if pinned and not pinned & after_set:
+            notes.append(
+                f"allowed_operations entry {ch.describe_entry(entry)} has no effect while "
+                f"{', '.join(sorted(pinned))} is not allowed"
+            )
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=bool(after_set - before_set),
+        notes=notes,
+    )
+
+
+def _entry_for(
+    project: _Project, api: dict[str, Any], ref: ch.OperationRef, methods: list[str]
+) -> tuple[dict[str, Any], list[str]]:
+    spec = ch.load_spec(project.root, str(api["openapi"])) if api.get("openapi") else None
+    return ch.build_entry(ref, methods, spec, str(api.get("openapi") or ""))
+
+
+@api_group.command("allow")
+@click.argument("name")
+@_entry_options
+@click.option(
+    "--methods", "methods", default=None, help="Limit the entry to these methods (e.g. GET,PUT)."
+)
+@click.option(
+    "--rpc-method",
+    "rpc_method",
+    default=None,
+    metavar="M",
+    help=(
+        "A JSON-RPC API (protocol jsonrpc or a2a): the JSON-RPC method of the request, with "
+        "--method POST --path P (OPERATION_ID optional); A2A 1.0 names under a2a."
+    ),
+)
+@_dry_run_option
+def cmd_allow(
+    name: str,
+    operation_id: str | None,
+    method: str | None,
+    path: str | None,
+    methods: str | None,
+    rpc_method: str | None,
+    dry_run: bool,
+) -> None:
+    """Allow one operation (an allowed_operations entry, by OPERATION_ID and/or --method/--path).
+
+    An entry pins every field given, and all of them must match a call: pin
+    the method (--methods, or --method with --path) and, without an OpenAPI
+    spec, the path, so the entry allows exactly the declared call. With the
+    API's openapi spec recorded, OPERATION_ID must exist there and its
+    method and path are filled in. On a JSON-RPC API, --rpc-method M --method
+    POST --path P allows the requests with that JSON-RPC method (read from the
+    body) at that endpoint.
+    """
+    if rpc_method is not None and methods:
+        raise click.UsageError("--rpc-method takes --method POST --path P, not --methods")
+    ref = ch.OperationRef.from_options(
+        operation_id, method, path, combine=True, rpc_method=rpc_method, endpoint=True
+    )
+    extra = ch.parse_methods(methods)
+    project = _load_project()
+    api = project.api(name)
+    entry, warnings = _entry_for(project, api, ref, extra)
+    entries = api.get(ch.ALLOWED)
+    if entries is not None and any(ch.same_entry(e, entry) for e in entries):
+        Console().print(f"{name} already allows {ch.describe_entry(entry)}.")
+        return
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    document["apis"][name][ch.ALLOWED] = [*(entries or []), entry]
+    _validate(project, document)
+    editor = project.editor()
+    _edit(
+        lambda: editor.append(("apis", name, ch.ALLOWED), entry, after=_after(api, ch.ALLOWED)),
+        f"add {entry} to apis.{name}.allowed_operations",
+    )
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    notes = list(warnings)
+    creating = entries is None
+    allowed = ch.effective_methods(api["allowed_methods"])
+    if creating:
+        notes.append(
+            f"{name} had no allowed_operations, so every operation with "
+            f"{', '.join(allowed)} was allowed. This creates the list: from now on only the "
+            f"listed operations are allowed (before: any operation; after: only "
+            f"{ch.describe_entry(entry)}). This narrows access."
+        )
+    entry_methods = [str(m).upper() for m in entry.get("methods") or []] or allowed
+    outside = [m for m in entry_methods if m not in allowed]
+    denied_for: set[str] = set()
+    if outside:
+        wanted = ",".join(m for m in HTTP_METHODS if m in {*allowed, *outside})
+        notes.append(
+            f"{', '.join(outside)} is not in {name}'s allowed_methods: the entry has no effect "
+            f"for it until `graph-agents-cli api access {name} custom --methods {wanted}`"
+        )
+    for denial in api.get(ch.DENIED) or []:
+        refused = {
+            m
+            for m in entry_methods
+            if denial_match(
+                denial,
+                m,
+                entry.get("operationId"),
+                entry.get("path"),
+                rpc_method=entry.get(RPC_METHOD_KEY),
+            )
+            == ""
+        }
+        if refused:
+            denied_for |= refused
+            notes.append(
+                f"denied_operations entry {ch.describe_entry(denial)} still refuses it "
+                "(denials win)"
+            )
+    if entry.get("path") is None and not ref.rpc:
+        # An allow by label alone: the tool chooses the label, the entry does not say where.
+        pinned = "no path" if entry.get("methods") else "no path and no method"
+        notes.append(
+            f"the entry pins {pinned}: a call labelled {entry['operationId']} is allowed on any "
+            f"path with {', '.join(entry_methods)}; to allow exactly one call, pin its endpoint "
+            f"too (graph-agents-cli api allow {name} {entry['operationId']} --method M --path P)"
+        )
+    # The entry allows a call only with a method the API allows that no denial refuses.
+    effective = [m for m in entry_methods if m in allowed and m not in denied_for]
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=False if creating else (True if effective else None),
+        notes=notes,
+    )
+
+
+def _rpc_options(function: Callable[..., Any]) -> Callable[..., Any]:
+    """deny / revoke: ``--rpc-method M`` and ``--a2a-operation approve|reject``."""
+    function = click.option(
+        "--a2a-operation",
+        "a2a_operation",
+        type=click.Choice(list(A2A_OPERATIONS)),
+        default=None,
+        help=(
+            "protocol a2a: the messages that approve (or reject) a pending approval of the "
+            "agent behind the API, whatever their path, label or spelling."
+        ),
+    )(function)
+    return click.option(
+        "--rpc-method",
+        "rpc_method",
+        default=None,
+        metavar="M",
+        help=(
+            "A JSON-RPC API (protocol jsonrpc or a2a): the requests with this JSON-RPC method "
+            "(read from the body; letter case ignored), whatever their path or label."
+        ),
+    )(function)
+
+
+@api_group.command("deny")
+@click.argument("name")
+@_entry_options
+@_rpc_options
+@_dry_run_option
+def cmd_deny(
+    name: str,
+    operation_id: str | None,
+    method: str | None,
+    path: str | None,
+    rpc_method: str | None,
+    a2a_operation: str | None,
+    dry_run: bool,
+) -> None:
+    """Deny one operation (a denied_operations entry, by OPERATION_ID and/or --method/--path).
+
+    A denial with a path refuses every call to that path (with its method),
+    whatever operation id the call names. A denial by OPERATION_ID alone
+    knows only that label: with the API's openapi spec recorded, the id's
+    method and path are filled in; without one, give --method M --path P
+    too so the denial holds whatever a call is labelled. On a JSON-RPC API,
+    --rpc-method M refuses every request with that method, and
+    --a2a-operation approve every message that approves a pending approval
+    of the agent behind the API (read from the body, whatever the label).
+    """
+    ref = ch.OperationRef.from_options(
+        operation_id,
+        method,
+        path,
+        combine=True,
+        rpc_method=rpc_method,
+        a2a_operation=a2a_operation,
+    )
+    project = _load_project()
+    api = project.api(name)
+    entry, warnings = _entry_for(project, api, ref, [])
+    entries = api.get(ch.DENIED) or []
+    if any(ch.same_entry(e, entry) for e in entries):
+        Console().print(f"{name} already denies {ch.describe_entry(entry)}.")
+        return
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    document["apis"][name][ch.DENIED] = [*entries, entry]
+    _validate(project, document)
+    editor = project.editor()
+    _edit(
+        lambda: editor.append(("apis", name, ch.DENIED), entry, after=_after(api, ch.DENIED)),
+        f"add {entry} to apis.{name}.denied_operations",
+    )
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    notes = list(warnings)
+    if entry.get("operationId") is not None and entry.get("path") is None and not ref.rpc:
+        notes.append(
+            "a denial by operationId alone knows only that label: it refuses the calls that "
+            "name it, and also refuses every call that names no operation_id (fail closed), "
+            "but a call to the same endpoint under another operation_id gets past it. Pin "
+            f"the endpoint too (graph-agents-cli api deny {name} {entry['operationId']} "
+            "--method M --path P, or record the API's openapi spec, which fills them in)"
+        )
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=False,
+        notes=notes,
+    )
+
+
+@api_group.command("revoke")
+@click.argument("name")
+@_operation_options
+@_rpc_options
+@click.option(
+    "--from",
+    "from_list",
+    type=click.Choice(["allowed", "denied"]),
+    default=None,
+    help="The list to remove the entry from (needed when both have a match).",
+)
+@_dry_run_option
+def cmd_revoke(
+    name: str,
+    operation_id: str | None,
+    method: str | None,
+    path: str | None,
+    rpc_method: str | None,
+    a2a_operation: str | None,
+    from_list: str | None,
+    dry_run: bool,
+) -> None:
+    """Remove the allowed or denied entries naming an operation (OPERATION_ID or --method/--path).
+
+    On a JSON-RPC API, --rpc-method M and/or --a2a-operation approve|reject name
+    the entries that pin them (with OPERATION_ID, the one also naming it).
+    """
+    if (rpc_method is not None or a2a_operation is not None) and (method or path):
+        raise click.UsageError(
+            "--rpc-method and --a2a-operation name entries by what they pin: give no --method "
+            "or --path with them"
+        )
+    ref = ch.OperationRef.from_options(
+        operation_id, method, path, rpc_method=rpc_method, a2a_operation=a2a_operation
+    )
+    project = _load_project()
+    api = project.api(name)
+    keys = {"allowed": ch.ALLOWED, "denied": ch.DENIED}
+    # What an entry without `methods` covers: an allowed one, the API's methods;
+    # a denial, every method (it keeps denying a method allowed later).
+    every = {
+        "allowed": ch.effective_methods(api["allowed_methods"]),
+        "denied": list(HTTP_METHODS),
+    }
+    matches = {
+        label: ch.plan_revocations(api.get(key) or [], ref, every[label])
+        for label, key in keys.items()
+        if from_list in (None, label)
+    }
+    found = [label for label, plans in matches.items() if plans]
+    if not found:
+        where = f"{from_list} operations" if from_list else "allowed or denied operations"
+        raise ch.ApiCommandError(f"no {where} entry of {name} names {ref.describe()}")
+    if len(found) > 1:
+        raise ch.ApiCommandError(
+            f"{ref.describe()} is named in both allowed_operations and denied_operations of "
+            f"{name}: pass --from allowed or --from denied"
+        )
+    label = found[0]
+    key = keys[label]
+    revocations = matches[label]
+    entries = [dict(e) for e in api.get(key) or []]
+    for revocation in revocations:  # last index first
+        if revocation.remaining_methods is None:
+            del entries[revocation.index]
+        else:
+            entries[revocation.index]["methods"] = revocation.remaining_methods
+    if key == ch.ALLOWED and not entries:
+        raise ch.ApiCommandError(
+            f"that would remove the last allowed_operations entry of {name}; without the list "
+            "every operation within allowed_methods is allowed, which widens access. Narrow "
+            f"with `graph-agents-cli api access {name} ...`, or remove the API with "
+            f"`graph-agents-cli api remove {name}`"
+        )
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    # The last denial takes its key with it (an empty list says nothing).
+    drop_key = key == ch.DENIED and not entries
+    if drop_key:
+        del document["apis"][name][key]
+    else:
+        document["apis"][name][key] = entries
+    _validate(project, document)
+    editor = project.editor()
+
+    def apply() -> None:
+        if drop_key:
+            editor.delete(("apis", name, key))
+            return
+        for revocation in revocations:
+            if revocation.remaining_methods is None:
+                editor.remove_item(("apis", name, key), revocation.index)
+            else:
+                editor.set(
+                    ("apis", name, key, revocation.index, "methods"), revocation.remaining_methods
+                )
+
+    _edit(apply, f"in apis.{name}.{key}: " + "; ".join(r.describe() for r in revocations))
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    notes = [f"{key}: {r.describe()}" for r in reversed(revocations)]
+    if any(r.remaining_methods and not r.entry.get("methods") for r in revocations):
+        notes.append(
+            f"an entry without methods covered every method; it now lists the others, so "
+            f"only {ref.method} is revoked"
+        )
+    if key == ch.DENIED:
+        notes.append("lifting a denial widens access: make sure the operation should be allowed")
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=key == ch.DENIED,
+        notes=notes,
+    )
+
+
+@api_group.command("limits")
+@click.argument("name")
+@click.option(
+    "--max-calls-per-run",
+    "max_calls",
+    default=None,
+    metavar="N|none",
+    help="Calls to this API within one agent run (none removes the limit).",
+)
+@click.option(
+    "--rate-per-minute",
+    "rate",
+    default=None,
+    metavar="N|none",
+    help="Calls per minute, per process (replica); none removes the limit.",
+)
+@click.option(
+    "--max-response-bytes",
+    "max_bytes",
+    default=None,
+    metavar="N|none",
+    help=(
+        f"The most an answer may hold, in bytes (1-{MAX_RESPONSE_BYTES_LIMIT}; larger answers "
+        "are discarded); none removes the cap."
+    ),
+)
+@_dry_run_option
+def cmd_limits(
+    name: str, max_calls: str | None, rate: str | None, max_bytes: str | None, dry_run: bool
+) -> None:
+    """Set or clear an API's limits (max calls per run, rate per minute, answer size)."""
+    if max_calls is None and rate is None and max_bytes is None:
+        raise click.UsageError(
+            "give --max-calls-per-run, --rate-per-minute and/or --max-response-bytes (N or none)"
+        )
+    max_calls_value = ch.parse_limit(max_calls, "--max-calls-per-run")
+    rate_value = ch.parse_limit(rate, "--rate-per-minute")
+    max_bytes_value = ch.parse_limit(max_bytes, "--max-response-bytes")
+    project = _load_project()
+    api = project.api(name)
+    current = api.get("limits")
+    new = ch.new_limits(current, max_calls_value, rate_value, max_bytes_value)
+    if new == (dict(current) if current else None):
+        Console().print(f"{name}'s limits are already {ch.describe_limits(current)}.")
+        return
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    if new is None:
+        document["apis"][name].pop("limits", None)
+    else:
+        document["apis"][name]["limits"] = new
+    _validate(project, document)
+    editor = project.editor()
+    if new is None:
+        _edit(lambda: editor.delete(("apis", name, "limits")), f"delete apis.{name}.limits")
+    else:
+        _edit(
+            lambda: editor.set(("apis", name, "limits"), new, after=_after(api, "limits")),
+            f"set apis.{name}.limits: {new}",
+        )
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+    notes = [f"{name} limits: {ch.describe_limits(current)} -> {ch.describe_limits(new)}"]
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=ch.limits_widen(current, new),
+        notes=notes,
+        next_steps=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# approval
+# ---------------------------------------------------------------------------
+
+
+def _parse_approvers(value: str) -> list[str]:
+    """``requester, role:ops`` -> ``["requester", "role:ops"]`` (repeats dropped, order kept)."""
+    items = [item.strip() for item in value.split(",") if item.strip()]
+    if not items:
+        raise click.UsageError("--approvers needs requester and/or role:<name>")
+    for item in items:
+        role = item[len(ROLE_APPROVER_PREFIX) :] if item.startswith(ROLE_APPROVER_PREFIX) else None
+        if item != REQUESTER_APPROVER and not (
+            role and len(role) <= 256 and not any(c.isspace() or c == "," for c in role)
+        ):
+            raise click.UsageError(
+                f"--approvers: {item!r} is not an approver (requester, or role:<name> with a "
+                "role name of 1-256 characters without spaces or commas)"
+            )
+    return list(dict.fromkeys(items))
+
+
+def _parse_relayers(value: str) -> list[str]:
+    """``concierge, billing`` -> ``["concierge", "billing"]``: the agents' actor ids."""
+    items = [item.strip() for item in value.split(",") if item.strip()]
+    if not items:
+        raise click.UsageError("--relayers needs at least one agent id")
+    for item in items:
+        if len(item) > 256 or any(c.isspace() or ord(c) < 32 or ord(c) == 127 for c in item):
+            raise click.UsageError(
+                f"--relayers: {item!r} is not an agent id (1-256 characters without spaces, "
+                "commas or control characters)"
+            )
+    return list(dict.fromkeys(items))
+
+
+def _parse_a2a_operations(value: str) -> list[str]:
+    """``approve, reject`` -> ``["approve", "reject"]`` (repeats dropped, order kept)."""
+    items = [item.strip() for item in value.split(",") if item.strip()]
+    if not items:
+        raise click.UsageError("--a2a-operations needs approve and/or reject (or none)")
+    for item in items:
+        if item not in A2A_OPERATIONS:
+            raise click.UsageError(f"--a2a-operations: {item!r} is not approve or reject")
+    return list(dict.fromkeys(items))
+
+
+def _a2a_gate_entries(current: list[Any], operations: list[str]) -> list[dict[str, Any]]:
+    """``required_for.operations`` entries for the A2A decisions ``operations``: the rule's own
+    entry for each, kept as written, else ``{a2a_operation: <it>}``."""
+    entries = []
+    for operation in operations:
+        existing = next(
+            (e for e in current if isinstance(e, dict) and e.get(A2A_OPERATION_KEY) == operation),
+            None,
+        )
+        entries.append(dict(existing) if existing is not None else {A2A_OPERATION_KEY: operation})
+    return entries
+
+
+def _parse_operation_ids(value: str) -> list[str]:
+    items = [item.strip() for item in value.split(",") if item.strip()]
+    if not items:
+        raise click.UsageError("--operations needs at least one operationId (or none)")
+    for item in items:
+        if any(c.isspace() for c in item):
+            raise click.UsageError(f"--operations: {item!r} contains whitespace")
+    return list(dict.fromkeys(items))
+
+
+def _gate_entries(
+    project: _Project, api: dict[str, Any], operation_ids: list[str], current: list[Any]
+) -> tuple[list[dict[str, Any]], list[str]]:
+    """``required_for.operations`` entries for ``operation_ids``, and notes.
+
+    An entry the block already has for an id is kept as it is (with any path
+    or methods pinned by hand). With the API's openapi spec a new entry also
+    pins the operation's method and path, so the gate holds for every call to
+    that endpoint whatever label a tool gives it; an entry that knew only the
+    operationId (written before the spec was recorded) gets the path too,
+    keeping its methods (none: every method), so it gates at least what it did.
+    """
+    spec_name = str(api.get("openapi") or "")
+    spec = ch.load_spec(project.root, spec_name) if spec_name else None
+    entries: list[dict[str, Any]] = []
+    notes: list[str] = []
+    labels_only: list[str] = []
+    for op_id in operation_ids:
+        existing = next(
+            (e for e in current if isinstance(e, dict) and e.get("operationId") == op_id), None
+        )
+        if existing is not None:
+            if existing.get("path") is None and spec is not None:
+                pinned, warnings = ch.build_entry(
+                    ch.OperationRef(operation_id=op_id), [], spec, spec_name
+                )
+                if pinned.get("path") is not None:
+                    pinned.pop("methods", None)
+                    if existing.get("methods") is not None:
+                        pinned["methods"] = list(existing["methods"])
+                    entries.append(pinned)
+                    notes.extend(warnings)
+                    notes.append(
+                        f"the gate on {op_id} is now pinned to its endpoint from the openapi spec "
+                        f"({ch.describe_entry(pinned)}): a call to it under another label waits "
+                        "for approval too"
+                    )
+                    continue
+            entries.append(dict(existing))
+            if existing.get("path") is None:
+                labels_only.append(op_id)
+            continue
+        entry, warnings = ch.build_entry(
+            ch.OperationRef(operation_id=op_id), [], spec, str(api.get("openapi") or "")
+        )
+        entries.append(entry)
+        notes.extend(warnings)
+        if entry.get("path") is None:
+            labels_only.append(op_id)
+    if labels_only:
+        notes.append(
+            f"the gate on {', '.join(labels_only)} knows only the operationId: it holds for "
+            "the calls that name it and for calls that name no operation_id (fail closed), but "
+            "not for a call to the same endpoint under another label. Record the API's openapi "
+            "spec (which pins the endpoint), or add path and methods to the entry by hand"
+        )
+    return entries, notes
+
+
+def _gated_methods(block: Mapping[str, Any] | None) -> set[str]:
+    if not block:
+        return set()
+    methods = [str(m).upper() for m in block["required_for"].get("methods") or []]
+    return set(HTTP_METHODS) if ANY_METHOD in methods else set(methods)
+
+
+def _gate_entry_covers(new: Mapping[str, Any], old: Mapping[str, Any]) -> bool:
+    """Whether gate entry ``new`` gates every call ``old`` did.
+
+    The same entry, or ``old`` (an operationId alone) pinned to its endpoint
+    with no fewer methods: a gate entry fails closed like a denial, so adding
+    a path only gates more calls.
+    """
+    if ch.same_entry(old, new):
+        return True
+    if old.get("path") is not None or old.get("operationId") is None:
+        return False
+    if new.get("operationId") != old.get("operationId"):
+        return False
+    new_methods = new.get("methods")
+    if new_methods is None:
+        return True
+    old_methods = old.get("methods")
+    return old_methods is not None and {str(m).upper() for m in new_methods} >= {
+        str(m).upper() for m in old_methods
+    }
+
+
+def _gate_loosening(before: Mapping[str, Any] | None, after: Mapping[str, Any] | None) -> list[str]:
+    """How the change loosens one rule (effective rules): empty when it tightens or keeps it.
+
+    Loosening: a call that waited may go out without a human (a method or an
+    operation no longer gated, the block removed), someone new may approve, an
+    agent may now relay the requester's decision (``decide_with: relayed``, or
+    a new relayer), or a pending approval stays open longer. Moving back to
+    ``direct`` narrows the gate.
+    """
+    if before is None:
+        return []
+    if after is None:
+        return ["no call waits for an approval any more"]
+    reasons = []
+    ungated = [m for m in HTTP_METHODS if m in _gated_methods(before) - _gated_methods(after)]
+    if ungated:
+        reasons.append(f"{', '.join(ungated)} calls no longer wait as such")
+    old_ops = before["required_for"].get("operations") or []
+    new_ops = after["required_for"].get("operations") or []
+    dropped = [o for o in old_ops if not any(_gate_entry_covers(n, o) for n in new_ops)]
+    if dropped:
+        reasons.append(
+            "no longer gated as written: " + "; ".join(ch.describe_entry(e) for e in dropped)
+        )
+    added = [a for a in after["approvers"] if a not in before["approvers"]]
+    if added:
+        reasons.append(f"new approver(s) {', '.join(added)}")
+    if after.get("decide_with") == DECIDE_RELAYED:
+        if before.get("decide_with") != DECIDE_RELAYED:
+            reasons.append(
+                "agents may now relay the requester's decision (decide_with: relayed, by "
+                f"{', '.join(after.get('relayers') or [])})"
+            )
+        else:
+            relayers = [r for r in after.get("relayers") or [] if r not in before["relayers"]]
+            if relayers:
+                reasons.append(f"new relayer(s) {', '.join(relayers)}")
+    if after["timeout_s"] > before["timeout_s"]:
+        reasons.append(
+            f"pending approvals wait longer ({before['timeout_s']} -> {after['timeout_s']} s)"
+        )
+    return reasons
+
+
+def _entry_methods(entry: Mapping[str, Any]) -> set[str]:
+    """The methods a gate entry covers (none pinned: every method)."""
+    return {str(m).upper() for m in entry.get("methods") or []} or set(HTTP_METHODS)
+
+
+def _newly_covered(
+    before: Mapping[str, Any] | None, after: Mapping[str, Any]
+) -> tuple[set[str], list[Mapping[str, Any]]]:
+    """What rule ``after`` gates that ``before`` did not: methods, and operation entries."""
+    methods = _gated_methods(after) - _gated_methods(before)
+    old_ops = (before or {}).get("required_for", {}).get("operations") or []
+    entries = [
+        entry
+        for entry in after["required_for"].get("operations") or []
+        if not _entry_methods(entry) <= _gated_methods(before)
+        and not any(_gate_entry_covers(old, entry) for old in old_ops)
+    ]
+    return methods, entries
+
+
+def _may_overlap(
+    methods: set[str], entries: list[Mapping[str, Any]], rule: Mapping[str, Any]
+) -> bool:
+    """Whether a call gated by ``methods`` or ``entries`` may also be one ``rule`` covers.
+
+    Conservative: entries overlap unless their methods are disjoint.
+    """
+    rule_methods = _gated_methods(rule)
+    rule_entries = rule["required_for"].get("operations") or []
+    covered = set(methods) | {m for e in entries for m in _entry_methods(e)}
+    if covered & rule_methods:
+        return True
+    return any(covered & _entry_methods(e) for e in rule_entries)
+
+
+def _order_loosening(
+    rules: list[dict[str, Any]], index: int, before: Mapping[str, Any] | None
+) -> list[str]:
+    """Calls rule ``index`` now covers first that a later rule, with other approvers, gated.
+
+    The first rule in file order that covers a call gates it, so a rule that
+    starts covering more takes those calls from the rules after it: whoever it
+    names and they do not may then decide them.
+    """
+    after = rules[index]
+    methods, entries = _newly_covered(before, after)
+    if not methods and not entries:
+        return []
+    reasons = []
+    for later in rules[index + 1 :]:
+        gained = [a for a in after["approvers"] if a not in later["approvers"]]
+        if after.get("decide_with") == DECIDE_RELAYED:
+            later_relayers = (
+                later.get("relayers") or [] if later.get("decide_with") == DECIDE_RELAYED else []
+            )
+            gained += [f"relayer {r}" for r in after["relayers"] if r not in later_relayers]
+        if gained and _may_overlap(methods, entries, later):
+            reasons.append(
+                f"{after['rule']} now comes first for calls {later['rule']} may have gated "
+                f"(approved by {describe_deciders(later)}): {', '.join(gained)} may decide "
+                "them"
+            )
+    return reasons
+
+
+def _conflicts(api: Mapping[str, Any]) -> set[tuple[str, Any, Any]]:
+    """The rule conflicts of ``api`` (``rule_conflicts``) as comparable facts.
+
+    Each is an operationId named without a path, the deciders of its rule
+    (``rule_deciders``) and those of a later rule that may also cover a call
+    naming no operation id.
+    """
+    rules = approval_rules(api)
+    return {
+        (str(entry["operationId"]), rule_deciders(rules[index]), rule_deciders(rules[j]))
+        for index, entries, later in rule_conflicts(api)
+        for entry in entries
+        for j in later
+    }
+
+
+def _approver_notes(
+    project: _Project, approvers: list[str], rule: Mapping[str, Any] | None = None
+) -> list[str]:
+    roles = [a for a in approvers if a.startswith(ROLE_APPROVER_PREFIX)]
+    notes = []
+    if rule is not None and rule.get("decide_with") == DECIDE_RELAYED:
+        relayers = ", ".join(str(r) for r in rule.get("relayers") or [])
+        notes.append(
+            f"relayed: the agents {relayers} may deliver the requester's decision from another "
+            "agent (with the requester's own token, only on threads they started, naming the "
+            "approval's digest); list them in AUTH_ALLOWED_ACTORS too. Keep decide_with: "
+            "direct for calls the person should confirm at this agent themselves"
+        )
+        if project.config.auth_policy == "shared-bearer":
+            notes.append(
+                "under the shared-bearer auth policy no caller is an agent acting for a user, so "
+                "no decision is ever relayed; use jwt or custom"
+            )
+    if REQUESTER_APPROVER in approvers and not roles:
+        notes.append(
+            "requester confirms their own calls: the person whose run it is sees each gated "
+            "call before it is sent. For a second person's review (four-eyes), list "
+            "role:<name> approvers without requester"
+        )
+    elif REQUESTER_APPROVER not in approvers:
+        notes.append(
+            "requester is not an approver: another principal than the one who started the run, "
+            f"holding {' or '.join(roles)}, must decide each gated call (four-eyes)"
+        )
+    if roles and project.config.auth_policy == "shared-bearer":
+        notes.append(
+            "under the shared-bearer auth policy every caller is the one principal 'shared', so "
+            "only requester approvals can be decided (a role: approver must be another "
+            "principal); use the jwt or custom policy for per-user principals and roles"
+        )
+    return notes
+
+
+def _rules_listing(api: Mapping[str, Any]) -> str:
+    """Each approval rule of ``api`` on its own line: ``  approval[1]: ...; approved by ...``."""
+    return "\n".join(
+        f"  {rule['rule']}: {_describe_rule(rule)}" for rule in effective_approval_rules(api)
+    )
+
+
+def _add_rule_command(
+    name: str,
+    methods: str | None,
+    operations: str | None,
+    approvers: list[str],
+    timeout_s: int | None,
+    a2a_operations: str | None = None,
+) -> str:
+    """The ``api approval --add-rule`` command that gates the given calls for ``approvers``."""
+    parts = ["graph-agents-cli", "api", "approval", name, "--add-rule"]
+    if methods is not None and methods.strip().lower() != "none":
+        parts += ["--methods", methods]
+    if operations is not None and operations.strip().lower() != "none":
+        parts += ["--operations", operations]
+    if a2a_operations is not None and a2a_operations.strip().lower() != "none":
+        parts += ["--a2a-operations", a2a_operations]
+    parts += ["--approvers", ",".join(approvers)]
+    if timeout_s is not None:
+        parts += ["--timeout-s", str(timeout_s)]
+    return " ".join(parts)
+
+
+def _set_decide_with(
+    new_rule: dict[str, Any],
+    old_rule: Mapping[str, Any] | None,
+    decide_with: str | None,
+    relayer_list: list[str] | None,
+) -> None:
+    """Put the rule's ``decide_with`` and ``relayers`` in ``new_rule``: the old rule's, with
+    the options given applied (``direct`` drops both keys: absent means direct)."""
+    old = old_rule or {}
+    for key in ("decide_with", "relayers"):
+        if key in old:
+            new_rule[key] = copy.deepcopy(old[key])
+    if decide_with == DECIDE_DIRECT:
+        new_rule.pop("relayers", None)
+        if old.get("decide_with") != DECIDE_DIRECT:
+            new_rule.pop("decide_with", None)
+    elif decide_with == DECIDE_RELAYED:
+        new_rule["decide_with"] = DECIDE_RELAYED
+    if relayer_list is not None:
+        if new_rule.get("decide_with") != DECIDE_RELAYED:
+            raise click.UsageError(
+                "--relayers needs --decide-with relayed (the rule decides directly)"
+            )
+        new_rule["relayers"] = relayer_list
+    if new_rule.get("decide_with") == DECIDE_RELAYED and not new_rule.get("relayers"):
+        raise click.UsageError(
+            "--decide-with relayed needs --relayers: the agents, by actor id, that may relay "
+            "the requester's decision"
+        )
+
+
+def _edit_rule(
+    editor: YamlText, base: tuple[Any, ...], old: Mapping[str, Any], new: Mapping[str, Any]
+) -> None:
+    """Rewrite approval rule ``old`` at ``base`` into ``new``, key by key (comments stay)."""
+    old_rf, new_rf = old["required_for"], new["required_for"]
+    # New keys first: a mapping must keep a key while another is deleted.
+    for key in ("methods", "operations"):
+        if key in new_rf and old_rf.get(key) != new_rf[key]:
+            editor.set((*base, "required_for", key), new_rf[key])
+    for key in ("methods", "operations"):
+        if key not in new_rf and key in old_rf:
+            editor.delete((*base, "required_for", key))
+    for key in ("approvers", "timeout_s", "decide_with", "relayers"):
+        if key in new and old.get(key) != new[key]:
+            editor.set((*base, key), new[key])
+    for key in ("relayers", "decide_with"):
+        if key not in new and key in old:
+            editor.delete((*base, key))
+
+
+@api_group.command("approval")
+@click.argument("name")
+@click.option(
+    "--methods",
+    "methods",
+    default=None,
+    metavar="M,...|none",
+    help='Gate every call with these methods (e.g. POST,PATCH,DELETE, or "*"); none clears it.',
+)
+@click.option(
+    "--operations",
+    "operations",
+    default=None,
+    metavar="OP,...|none",
+    help=(
+        "Gate these operations by operationId (the API's openapi spec pins their method and "
+        "path); none clears it."
+    ),
+)
+@click.option(
+    "--a2a-operations",
+    "a2a_operations",
+    default=None,
+    metavar="approve[,reject]|none",
+    help=(
+        "protocol a2a: gate the messages that approve (or reject) a pending approval of the "
+        "agent behind the API, whatever their path, label or spelling; none clears it."
+    ),
+)
+@click.option(
+    "--approvers",
+    "approvers",
+    default=None,
+    metavar="A,...",
+    help="Who decides: requester and/or role:<name> (e.g. requester, or role:ops for four-eyes).",
+)
+@click.option(
+    "--timeout-s",
+    "timeout_s",
+    type=click.IntRange(MIN_APPROVAL_TIMEOUT_S, MAX_APPROVAL_TIMEOUT_S),
+    default=None,
+    metavar="N",
+    help=(
+        f"Seconds a pending approval waits before it expires, which rejects the call "
+        f"({MIN_APPROVAL_TIMEOUT_S}-{MAX_APPROVAL_TIMEOUT_S}; default "
+        f"{DEFAULT_APPROVAL_TIMEOUT_S})."
+    ),
+)
+@click.option(
+    "--decide-with",
+    "decide_with",
+    type=click.Choice([DECIDE_DIRECT, DECIDE_RELAYED]),
+    default=None,
+    help=(
+        "How the requester decides: direct (the default: with their own credentials, at this "
+        "agent) or relayed (the agents --relayers names may deliver the requester's decision "
+        "from another agent; a loosening, reviewed like one)."
+    ),
+)
+@click.option(
+    "--relayers",
+    "relayers",
+    default=None,
+    metavar="ID,...",
+    help=(
+        "With --decide-with relayed: the agents, by actor id (the act.sub of their exchanged "
+        "tokens, usually their client ids), that may relay the requester's decision."
+    ),
+)
+@click.option(
+    "--add-rule",
+    "add_rule",
+    is_flag=True,
+    default=False,
+    help=(
+        "Add a rule after the existing ones, for calls other approvers decide (needs "
+        "--approvers, and --methods and/or --operations)."
+    ),
+)
+@click.option(
+    "--rule",
+    "rule_index",
+    type=click.IntRange(min=0),
+    default=None,
+    metavar="N",
+    help=(
+        "Change, or --remove, rule N of a list of rules: approval[N], numbered from 0 in file "
+        "order as `api show` prints them (0 is also a single approval block)."
+    ),
+)
+@click.option(
+    "--remove",
+    "remove",
+    is_flag=True,
+    default=False,
+    help=(
+        "Remove the approval block, every rule of it (the API's calls are sent without waiting "
+        "for a human), or with --rule N that one rule."
+    ),
+)
+@_dry_run_option
+def cmd_approval(
+    name: str,
+    methods: str | None,
+    operations: str | None,
+    a2a_operations: str | None,
+    approvers: str | None,
+    timeout_s: int | None,
+    decide_with: str | None,
+    relayers: str | None,
+    add_rule: bool,
+    rule_index: int | None,
+    remove: bool,
+    dry_run: bool,
+) -> None:
+    """Require a human approval before some of an API's calls are sent (or --remove it).
+
+    A gated call is still allowed by the rest of the policy first (approval
+    never widens access; denials still win). The run pauses before sending it
+    and an approver decides: requester (the principal who started the run
+    confirms) and/or role:<name> (a principal holding that role; list roles
+    without requester for a second person's review). Approving sends exactly
+    the call shown, once; rejecting or expiry sends nothing.
+
+    \b
+    Each option given replaces that part of the rule and keeps the rest:
+      --methods POST,DELETE        every call with those methods
+      --operations cancelOrder     calls to those operations
+      --a2a-operations approve     (protocol a2a) messages that approve one
+                                   of the called agent's pending approvals
+      --approvers requester        who decides (required for a new rule)
+      --timeout-s 900              how long a pending approval waits
+      --decide-with relayed --relayers concierge
+                                   let the agent concierge deliver the
+                                   requester's decision (default: direct)
+
+    \b
+    Different approvers for different calls: add a rule, and name one to
+    change or remove by its number (api show lists them):
+      --add-rule --operations createOrder --approvers role:admin
+      --rule 1 --approvers role:admin,role:ops
+      --rule 1 --remove
+    The approval block then holds a list of rules, and a call is gated by the
+    FIRST rule in file order that covers it, with that rule's approvers; a
+    later rule that also covers it does not apply to it (lint and api show
+    name the rule each declared call waits for).
+    """
+    changing = (methods, operations, a2a_operations, approvers, timeout_s, decide_with, relayers)
+    if add_rule and rule_index is not None:
+        raise click.UsageError(
+            "--add-rule adds a new rule and --rule N changes an existing one: give one of them"
+        )
+    if remove and add_rule:
+        raise click.UsageError("--remove and --add-rule: give one of them")
+    if remove and any(option is not None for option in changing):
+        raise click.UsageError("--remove takes no other option (but --rule N)")
+    if not remove and all(option is None for option in changing):
+        raise click.UsageError(
+            "give --methods, --operations and/or --a2a-operations, --approvers, --timeout-s, "
+            "--decide-with, --relayers, or --remove"
+        )
+    new_methods = None
+    if methods is not None and methods.strip().lower() != "none":
+        new_methods = ch.parse_methods(methods)
+    operation_ids = None
+    if operations is not None and operations.strip().lower() != "none":
+        operation_ids = _parse_operation_ids(operations)
+    a2a_list = None
+    if a2a_operations is not None and a2a_operations.strip().lower() != "none":
+        a2a_list = _parse_a2a_operations(a2a_operations)
+    approver_list = _parse_approvers(approvers) if approvers is not None else None
+    relayer_list = _parse_relayers(relayers) if relayers is not None else None
+    if relayer_list is not None and decide_with == DECIDE_DIRECT:
+        raise click.UsageError(
+            "--relayers is only for --decide-with relayed (direct: nobody relays)"
+        )
+    if add_rule:
+        if approver_list is None:
+            raise click.UsageError("--add-rule needs --approvers (requester and/or role:<name>)")
+        if new_methods is None and operation_ids is None and a2a_list is None:
+            raise click.UsageError(
+                "--add-rule needs --methods, --operations and/or --a2a-operations (the calls the "
+                "new rule gates)"
+            )
+
+    project = _load_project()
+    api = project.api(name)
+    raw = api.get(APPROVAL_KEY)
+    rules = approval_rules(api)
+    listed = isinstance(raw, list)
+    before_rules = effective_approval_rules(api)
+    if remove and raw is None:
+        Console().print(f"{name} has no approval block: no call waits for an approval.")
+        return
+    if add_rule:
+        index = len(rules)
+    elif rule_index is not None:
+        if not rules:
+            raise ch.ApiCommandError(
+                f"{name} has no approval rules: add one without --rule (the first rule is the "
+                "approval block itself)"
+            )
+        if rule_index >= len(rules):
+            raise ch.ApiCommandError(
+                f"{name} has {len(rules)} approval rule(s), so --rule takes 0 to "
+                f"{len(rules) - 1}:\n{_rules_listing(api)}"
+            )
+        index = rule_index
+    elif listed and len(rules) > 1 and not remove:
+        raise click.UsageError(
+            f"{name}'s approval is a list of {len(rules)} rules: name the one to change with "
+            "--rule N, add one with --add-rule, or remove them all with --remove:\n"
+            f"{_rules_listing(api)}"
+        )
+    else:
+        index = 0
+    whole = remove and (rule_index is None or len(rules) == 1)
+    becomes_list = listed or (add_rule and raw is not None)
+    label = f"{APPROVAL_KEY}[{index}]" if becomes_list else APPROVAL_KEY
+    rule_flag = f" --rule {index}" if listed else ""
+    old_rule = rules[index] if index < len(rules) else None
+    notes: list[str] = []
+    new_rule: dict[str, Any] | None
+    if remove:
+        new_rule = None
+    else:
+        required_for = dict(old_rule["required_for"]) if old_rule is not None else {}
+        if methods is not None:
+            if new_methods is None:
+                required_for.pop("methods", None)
+            else:
+                required_for["methods"] = new_methods
+        # --operations sets the rule's other entries and --a2a-operations its entries for
+        # A2A decisions; each keeps the other's.
+        current = list(required_for.get("operations") or [])
+        decisions = [e for e in current if isinstance(e, dict) and A2A_OPERATION_KEY in e]
+        others = [e for e in current if not (isinstance(e, dict) and A2A_OPERATION_KEY in e)]
+        if operations is not None:
+            if operation_ids is None:
+                others = []
+            else:
+                others, entry_notes = _gate_entries(project, api, operation_ids, others)
+                notes.extend(entry_notes)
+        if a2a_operations is not None:
+            decisions = [] if a2a_list is None else _a2a_gate_entries(decisions, a2a_list)
+        if operations is not None or a2a_operations is not None:
+            if others or decisions:
+                required_for["operations"] = [*others, *decisions]
+            else:
+                required_for.pop("operations", None)
+        required_for = {k: required_for[k] for k in ("methods", "operations") if k in required_for}
+        what = "approval block" if label == APPROVAL_KEY else f"approval rule {label}"
+        if not required_for:
+            raise ch.ApiCommandError(
+                f"the {what} of {name} would gate nothing (it needs --methods, --operations "
+                f"and/or --a2a-operations); remove it with `graph-agents-cli api approval "
+                f"{name}{rule_flag} --remove`"
+            )
+        if approver_list is None and old_rule is None:
+            raise click.UsageError(
+                "--approvers is required for a new approval block (requester and/or role:<name>)"
+            )
+        new_rule = {
+            "required_for": required_for,
+            "approvers": (
+                approver_list if approver_list is not None else list(old_rule["approvers"])
+            ),
+        }
+        if timeout_s is not None:
+            new_rule["timeout_s"] = timeout_s
+        elif old_rule is not None and "timeout_s" in old_rule:
+            new_rule["timeout_s"] = old_rule["timeout_s"]
+        _set_decide_with(new_rule, old_rule, decide_with, relayer_list)
+        if old_rule is not None and new_rule == dict(old_rule):
+            Console().print(f"{name}'s {what} already says that.")
+            return
+        same = next((i for i, rule in enumerate(rules) if dict(rule) == new_rule), None)
+        if add_rule and same is not None:
+            Console().print(
+                f"{name} already has that approval rule ({approval_rule_label(api, same)})."
+            )
+            return
+
+    document = copy.deepcopy(project.document)
+    assert document is not None
+    target = document["apis"][name]
+    if new_rule is None:
+        if whole:
+            target.pop(APPROVAL_KEY)
+        else:
+            del target[APPROVAL_KEY][index]
+    elif add_rule and raw is not None:
+        target[APPROVAL_KEY] = [*rules, new_rule] if listed else [target[APPROVAL_KEY], new_rule]
+    elif listed:
+        target[APPROVAL_KEY][index] = new_rule
+    else:
+        target[APPROVAL_KEY] = new_rule
+    _validate(project, document)
+    after_rules = effective_approval_rules(target)
+    editor = project.editor()
+    base = ("apis", name, APPROVAL_KEY)
+
+    def apply() -> None:
+        if new_rule is None:
+            if whole:
+                editor.delete(base)
+            else:
+                editor.remove_item(base, index)
+        elif raw is None:
+            editor.set(base, new_rule, after=_after(api, APPROVAL_KEY), block=True)
+        elif add_rule:
+            if not listed:
+                editor.wrap_in_list(base)
+            editor.append(base, new_rule)
+        else:
+            assert old_rule is not None
+            _edit_rule(editor, (*base, index) if listed else base, old_rule, new_rule)
+
+    _edit(apply, f"set apis.{name}.{label} to {new_rule}")
+    plan = Plan(project.root)
+    plan.set_text(POLICY_FILENAME, project.text, editor.text)
+
+    if new_rule is None and whole:
+        loosening = _gate_loosening(before_rules[0], None)
+        notes.append(f"calls to {name} are sent without waiting for a human approval")
+    elif new_rule is None:
+        loosening = (
+            []
+            if rule_never_applies(api, index)
+            else [
+                f"{label} is removed: the calls it gated first now wait for a later rule's "
+                "approvers, or for no one"
+            ]
+        )
+        notes.append(
+            f"{label} is removed; the rules after it move up one place"
+            if index < len(after_rules)
+            else f"{label} is removed"
+        )
+        notes.extend(approval_notes(name, target))
+    else:
+        before = before_rules[index] if old_rule is not None else None
+        loosening = [
+            f"{label}: {reason}" if becomes_list else reason
+            for reason in _gate_loosening(before, after_rules[index])
+        ]
+        loosening.extend(_order_loosening(after_rules, index, before))
+        notes.extend(approval_notes(name, target))
+        notes.extend(
+            f"{label}: {note}" if becomes_list else note
+            for note in _approver_notes(project, new_rule["approvers"], new_rule)
+        )
+        if (
+            not add_rule
+            and before is not None
+            and approver_list is not None
+            and set(approver_list) != set(before["approvers"])
+            # The edit also drops calls the rule gated (its approvers and expiry aside).
+            and _gate_loosening(
+                before,
+                {
+                    **{k: v for k, v in after_rules[index].items() if k != "relayers"},
+                    "approvers": before["approvers"],
+                    "timeout_s": before["timeout_s"],
+                    "decide_with": before.get("decide_with", DECIDE_DIRECT),
+                    **({"relayers": before["relayers"]} if "relayers" in before else {}),
+                },
+            )
+        ):
+            notes.append(
+                f"this gives the {what} other approvers and drops calls it gated: to keep those "
+                f"with {', '.join(before['approvers'])} and gate the calls you named for "
+                f"{', '.join(approver_list)}, add a rule instead: "
+                + _add_rule_command(
+                    name, methods, operations, approver_list, timeout_s, a2a_operations
+                )
+            )
+    effects = _call_effects(project, project.document, document, name)
+    if any(line.startswith("approvers change (new") for line in effects):
+        loosening.append("a declared call gets new approver(s) (see above)")
+    if any(line.startswith("relaying changes (new") for line in effects):
+        loosening.append("a declared call gets new relayer(s) (see above)")
+    if any(line.startswith("now allowed") for line in effects):
+        loosening.append("a declared call the rules refused is now sent after an approval")
+    refuses = bool(_conflicts(target) - _conflicts(api)) or any(
+        line.startswith("now refused") for line in effects
+    )
+    if loosening:
+        verdict = (
+            f"This loosens the approval gate on {name} ({'; '.join(loosening)}). "
+            f"{GATE_REVIEW_NOTE}",
+            "yellow",
+        )
+    elif refuses:
+        verdict = (
+            f"This tightens the approval gate on {name}, and the agent refuses the calls to "
+            f"{name} that name no operation_id where rules with other approvers may both cover "
+            "them (see the notes): name the operation_id on those calls, or pin path and "
+            "methods in the rule.",
+            "yellow",
+        )
+    else:
+        verdict = (
+            f"This tightens or keeps the approval gate on {name} (always safe); access to "
+            f"{name} is unchanged.",
+            "dim",
+        )
+    _finish(
+        project,
+        plan,
+        dry_run=dry_run,
+        api=name,
+        before=project.document,
+        after=document,
+        widens=None,
+        notes=notes,
+        next_steps=False,
+        verdict=verdict,
+        effects=effects,
+    )
+
+
+# ---------------------------------------------------------------------------
+# show / check
+# ---------------------------------------------------------------------------
+
+
+def _effective(name: str, api: dict[str, Any]) -> dict[str, Any]:
+    methods = [str(m).upper() for m in api["allowed_methods"]]
+    timeouts = dict(DEFAULT_TIMEOUTS_MS)
+    timeouts.update(api.get("timeouts_ms") or {})
+    return {
+        "name": name,
+        "description": api.get(DESCRIPTION_KEY),
+        # http, jsonrpc or a2a; a2a: {path} for an agent's A2A endpoint.
+        "protocol": api_protocol(api),
+        A2A_KEY: dict(api[A2A_KEY]) if A2A_KEY in api else None,
+        "base_url_env": api["base_url_env"],
+        "auth": api["auth"],
+        "token_env": api.get("token_env"),
+        "forward_header": (
+            (api.get("forward_header") or DEFAULT_FORWARD_HEADER)
+            if api["auth"] in HEADER_AUTH_MODES
+            else None
+        ),
+        # auth: forward: the audience the caller's own token must name to be forwarded.
+        "forward_audience": api.get("forward_audience"),
+        # auth: exchange (RFC 8693): {audience, scope, resource} as the file sets them.
+        EXCHANGE_KEY: dict(api[EXCHANGE_KEY]) if EXCHANGE_KEY in api else None,
+        "allowed_methods": methods,
+        "preset": ch.preset_name(methods),
+        # None: every operation within allowed_methods.
+        "allowed_operations": api.get(ch.ALLOWED),
+        "denied_operations": api.get(ch.DENIED) or [],
+        "limits": api.get("limits"),
+        "openapi": api.get("openapi"),
+        "timeouts_ms": timeouts,
+        "pagination": api.get("pagination"),
+        # None: no call waits for a human approval. One rule (a mapping), or a
+        # list of rules as the file writes it.
+        "approval": effective_approval(api),
+        # Every rule in file order, with its name in messages ("approval", or
+        # "approval[N]" in a list): the first that covers a call gates it.
+        "approval_rules": effective_approval_rules(api),
+    }
+
+
+@api_group.command("show")
+@click.argument("name", required=False)
+@click.option("--json", "as_json", is_flag=True, default=False, help="Print JSON.")
+def cmd_show(name: str | None, as_json: bool) -> None:
+    """Show the effective policy per API and the calls every tool declares.
+
+    Each call's status says whether the policy allows it, and a gated call
+    names who must approve it before it is sent (the API's approval block).
+    """
+    project = _load_project()
+    if name is not None:
+        project.api(name)
+    document = project.document
+    apis = {
+        api_name: _effective(api_name, api)
+        for api_name, api in ((document or {}).get("apis") or {}).items()
+        if name in (None, api_name)
+    }
+    report = policy_check.build_report(
+        project.root,
+        project.config.agent_directory,
+        runtime=project.config.runtime,
+        policy_declared=bool(project.config.api_policy_file),
+        auth_policy=project.config.auth_policy,
+    )
+    results = [r for r in report.results if name in (None, r.call.api)]
+    if as_json:
+        payload = {
+            "policy_file": POLICY_FILENAME if document is not None else None,
+            "apis": apis,
+            "calls": [
+                {
+                    "tool": r.call.tool,
+                    "api": r.call.api or None,
+                    "method": r.call.method,
+                    "operation_id": r.call.operation_id,
+                    "path": r.call.path,
+                    # A call to a JSON-RPC API: its JSON-RPC method and A2A decision.
+                    "rpc_method": r.call.rpc_method,
+                    "a2a_operation": r.call.a2a_operation,
+                    "status": r.status,
+                    "reason": r.reason,
+                    "hint": r.hint or None,
+                    # {approvers, timeout_s, rule} for a gated call, else None.
+                    "approval": gate_payload(r.gate),
+                }
+                for r in results
+            ],
+            "violations": sum(1 for r in results if r.is_violation),
+            "gated": sum(1 for r in results if r.gate is not None),
+        }
+        click.echo(json.dumps(payload, indent=2))
+        return
+    console = Console()
+    if document is None:
+        console.print(
+            f"No {POLICY_FILENAME}: every outbound API call is refused. Declare an API with "
+            "`graph-agents-cli api add`."
+        )
+    for effective in apis.values():
+        _print_api(console, effective)
+    policy_check.print_report(
+        policy_check.PolicyReport(results=results, notes=report.notes), console
+    )
+
+
+def _print_api(console: Console, api: dict[str, Any]) -> None:
+    auth = api["auth"]
+    if auth == "bearer":
+        auth += f" (token from {api['token_env']})"
+    elif auth == "forward" and api["forward_audience"]:
+        auth += (
+            f" (the caller's credential in {api['forward_header']}, or the caller's own token "
+            f"when it was minted for {api['forward_audience']})"
+        )
+    elif auth == "forward":
+        auth += f" (the caller's credential in {api['forward_header']})"
+    elif auth == EXCHANGE_KEY:
+        exchange = api[EXCHANGE_KEY]
+        extra = "".join(
+            f"; {key} {exchange[key]}" for key in ("scope", "resource") if exchange.get(key)
+        )
+        actorless = (
+            "; accepts tokens that name no actor (allow_actorless)"
+            if exchange.get(ALLOW_ACTORLESS_KEY) is True
+            else ""
+        )
+        auth += (
+            f" (a token the issuer mints for audience {exchange['audience']}{extra}, in exchange "
+            f"for the caller's, sent in {api['forward_header']}; RFC 8693{actorless})"
+        )
+    rows = []
+    if api["description"]:
+        rows.append(("description", api["description"]))
+    if api["protocol"] == PROTOCOL_A2A:
+        rows.append(
+            (
+                "protocol",
+                f"a2a (another agent, endpoint {api[A2A_KEY]['path']}): each POST is judged by "
+                "the JSON-RPC request it sends, and a message that approves by a2a_operation",
+            )
+        )
+    elif api["protocol"] != PROTOCOL_HTTP:
+        rows.append(
+            (
+                "protocol",
+                f"{api['protocol']}: each POST is judged by the JSON-RPC request it sends",
+            )
+        )
+    rows += [
+        ("base URL", f"from {api['base_url_env']}"),
+        ("auth", auth),
+        ("methods", ch.describe_methods(api["allowed_methods"])),
+        (
+            "allowed",
+            "every operation within the methods"
+            if api["allowed_operations"] is None
+            else "; ".join(ch.describe_entry(e) for e in api["allowed_operations"]),
+        ),
+        ("denied", "; ".join(ch.describe_entry(e) for e in api["denied_operations"]) or "none"),
+        ("limits", ch.describe_limits(api["limits"])),
+        ("openapi", api["openapi"] or "none"),
+        (
+            "timeouts",
+            f"connect {api['timeouts_ms']['connect']} ms, read {api['timeouts_ms']['read']} ms",
+        ),
+    ]
+    if api["pagination"]:
+        pagination = api["pagination"]
+        rows.append(
+            ("pagination", f"{pagination['page_size_param']} <= {pagination['max_page_size']}")
+        )
+    rows.append(("approval", _describe_approval(api["approval_rules"])))
+    table = Table(title=f"API {api['name']}", show_header=False, title_justify="left")
+    table.add_column(style="bold", no_wrap=True)
+    table.add_column(overflow="fold")
+    for label, value in rows:
+        table.add_row(label, escape(str(value)))
+    print_table(console, table)
+
+
+def _describe_rule(rule: Mapping[str, Any]) -> str:
+    """``POST, DELETE and operations cancelOrder any method; approved by requester; ...``."""
+    required_for = rule["required_for"]
+    gates = []
+    if "methods" in required_for:
+        methods = required_for["methods"]
+        gates.append('"*" (every method)' if "*" in methods else ", ".join(methods))
+    if "operations" in required_for:
+        gates.append(
+            "operations " + "; ".join(ch.describe_entry(e) for e in required_for["operations"])
+        )
+    return (
+        f"{' and '.join(gates)}; approved by {describe_deciders(rule)}; "
+        f"expires after {rule['timeout_s']} s"
+    )
+
+
+def _describe_approval(rules: list[dict[str, Any]]) -> str:
+    """One rule on a line, ``approval[N]: ...`` for each rule of a list, and how they apply."""
+    if not rules:
+        return "none (no call waits for a human approval)"
+    if len(rules) == 1 and rules[0]["rule"] == APPROVAL_KEY:
+        return f"{_describe_rule(rules[0])} (approval never widens access)"
+    lines = [f"{rule['rule']}: {_describe_rule(rule)}" for rule in rules]
+    lines.append(
+        "a call waits for the first rule in file order that covers it (approval never widens "
+        "access)"
+    )
+    return "\n".join(lines)
+
+
+@api_group.command("check")
+@click.pass_context
+def cmd_check(ctx: click.Context) -> None:
+    """Check every tool's API_CALLS against api-policy.yaml (same as lint --policy-only)."""
+    from graph_agents_cli.dev.cmd_lint import cmd_lint
+
+    ctx.invoke(cmd_lint, fix=False, policy_only=True)