Approval Status for Agents

A listener in return mode files an approval request and denies at once with its id. The agent resends the identical statement after a person approves it, so it needs a way to learn the decision. GET /api/sidecars/reviews/<id> on the Control Plane answers, but it takes the Sidecar token, which an agent must not hold. The Sidecar gives the agent three ways that need no credential:

Way	Protocols	Since
Approval fields on the denial	http, grpc	1.214.0
The status path on the listener	http	1.214.0
The MCP server	every protocol	1.199.0

The status path and the MCP server need a Control Plane, because the approval status lives there. None of the three returns the statement, and none approves anything.

Approvals were called reviews before 1.244.0. The Sidecar still answers every earlier name on this page: the X-Hoop-Review-* fields, the /.well-known/hoop/reviews/<id> path and the review_* MCP tools. An agent configured against them keeps working.

Find the approval in the denial

On http and grpc, an approval denial carries the approval in structured fields, so a client does not parse the message. http sends them as headers on the 403. grpc sends the same keys, in lowercase, as trailing metadata beside PERMISSION_DENIED.

Field	Value
`X-Hoop-Denied`	`review`. Any other denial says `policy`. The value keeps its earlier name, because clients already match on it
`X-Hoop-Approval-Id`	The approval id
`X-Hoop-Approval-Status`	The Control Plane status, such as `PENDING` or `REJECTED`. Absent when the Sidecar could not read it
`X-Hoop-Review-Id`, `X-Hoop-Review-Status`	The same values under their earlier names, kept for existing clients
`Retry-After`	`5`, in return mode while the approval request is pending only

The body stays the text message, so a client that knows nothing about approvals still reads it. kubectl prints it as Error from server (Forbidden): .... On postgres, mysql, mssql and mongodb, the approval id is in the error text only:

ERROR:  statement held for human approval: waiting for approval; resend the identical statement once it is approved (approval 9f97…)

Read the status on an http listener

An http listener answers GET /.well-known/hoop/approvals/<id> itself, for an approval request filed on that listener. The agent asks the same host and port it sends its requests to:

curl -s http://relay:18080/.well-known/hoop/approvals/9f97…

{
  "id": "9f97…",
  "status": "PENDING",
  "listener_name": "billing-api",
  "approval_rule": "billing-approvers",
  "created_at": "2026-09-29T14:02:11Z",
  "decided_at": null,
  "expires_at": "2026-09-29T14:32:11Z",
  "next": "wait"
}

The earlier path, /.well-known/hoop/reviews/<id>, answers the same. next says what the agent does, so it never interprets a status on its own. See Status and next. rejection_reason is present on a rejection that gave one. expires_at is present only when the approval rule sets a time limit.

Status code	When
`200`	The approval request, as above
`404`	The id is unknown, or the approval request belongs to another listener or another Sidecar. Stop: it reads the same as a wrong id
`405`	A method other than `GET` or `HEAD`
`502`	The Control Plane could not report the approval, or is older than the Sidecar. A person checks the approval request in the Control Plane
`503`	The Sidecar has no Control Plane

An error body is {"message": "..."}. Every answer sends Cache-Control: no-store and closes the connection. The whole /.well-known/hoop/ prefix belongs to the Sidecar. Every http listener keeps it, with or without a Control Plane, and never forwards it to the upstream. A route the upstream serves under that prefix is not reachable through the Sidecar. The Sidecar answers it only as the first request on a connection. Behind another request, the listener closes the connection unanswered, because HTTP/1.1 pairs responses with requests by order. curl and Go clients resend on a new connection.

The path needs no credential, the same as the listener port. A caller who reaches the listener and holds an approval id reads that approval request’s status, listener name and approval rule. It never reads the statement.

Other protocols have no path to reserve, so they read the status over MCP.

The MCP server

The mcp block starts a Model Context Protocol server with three read-only tools. It serves every listener of the Sidecar, whatever the protocol.

config.yaml

mcp:
  listen: 127.0.0.1:8765    # the endpoint is http://<host>:8765/mcp

listen is required. Remove the block to turn the server off.
The Sidecar needs a Control Plane. A config with the block and no Control Plane is refused at startup.
A reload does not start, stop or move the server. Restart the Sidecar after you add, remove or change the block.
A bind failure stops the Sidecar, as a listener’s bind failure does.

Add the block to the Sidecar’s config file, beside listeners, then restart the Sidecar. On a Sidecar connected to a Control Plane, the file applies on the first import, or when the Sidecar runs from its config file.

The MCP endpoint has no authentication, the same as the listener ports. A caller reads every approval request of this Sidecar: its id, status, listener name and approval rule, never the statement. Bind it where only the agent reaches it: loopback when the agent runs on the same host, a ClusterIP Service on Kubernetes, never a public load balancer. The server refuses cross-origin browser requests, so a web page cannot use it from a visitor’s browser.

Tools

Tool	Input	Does
`approval_status`	`id`	Reads the approval request once
`approval_wait`	`id`, `timeout_seconds` (default 60, max 300)	Reads the approval request every 2 seconds until a person decides or the timeout ends
`approval_list`	`status`, `limit` (default 20, max 200)	Lists this Sidecar’s approval requests, newest first, across every listener. Needs 1.214.0

Each tool is also served under its earlier name, review_status, review_wait and review_list, with the same input and output. An answer points the agent at the tools of the family it called, so an agent allowed only the review_* tools is told to call review_wait. approval_status and approval_wait return one approval request and what to do next. approval_list returns {"reviews": [...]} of the same shape (the key keeps its earlier name), and status filters on PENDING, APPROVED, REJECTED, REVOKED, PROCESSING, EXECUTED or EXPIRED.

{
  "id": "9f97…",
  "status": "APPROVED",
  "listener_name": "payments",
  "approval_rule": "payments-approvers",
  "created_at": "2026-09-29T14:02:11Z",
  "decided_at": "2026-09-29T14:03:40Z",
  "next": "resend_identical_statement",
  "instruction": "Approved. Resend the identical statement, byte for byte, to listener payments. It runs once.",
  "timed_out": false,
  "waited_seconds": 42
}

instruction is next in words, for an agent that reads prose. timed_out and waited_seconds come from approval_wait only. timed_out: true is not an error: call again. Keep the 60-second default for approval_wait. Some MCP clients drop a tool call that blocks for longer than 60 to 120 seconds. approval_wait sends a progress notification every 2 seconds to a client that asks for them. When the config has an mcp block, a return-mode denial leads with the approval id and names the tool:

ERROR:  approval 9f97…: waiting for approval; call the MCP tool approval_wait with the approval id, then resend the identical statement once it is approved (statement held for human approval)

Status and next

The status path and the MCP tools map a status to next the same way:

`status`	`next`	The agent
`PENDING`	`wait`	Waits again. It does not resend
`APPROVED`	`resend_identical_statement`	Resends the identical statement once, before `expires_at` when it is set
`PROCESSING`	`wait`	Waits again. Another request is using the approval, and the upstream’s answer spends it or gives it back. Only on a listener with `spend_approval_on: accepted`
`REJECTED`, `REVOKED`, `EXECUTED`, `EXPIRED`, any other	`stop`	Stops. Only a person asks again

The resend runs through the listener like any statement, so the analyzer, the audit trail and masking apply, and the resend uses the approval. With spend_approval_on: accepted, a resend that the upstream refuses gives the approval back. See The retry contract. Two tool answers are errors:

Error	The agent
Not found on this Sidecar	Stops. The Control Plane scopes the read to this Sidecar, so another Sidecar’s approval request reads the same as a wrong id
The Control Plane is older than this Sidecar	Stops. A person checks the approval request in the Control Plane

Connect an agent

Add one MCP entry per Sidecar the agent uses, next to the connection string it pairs with. One entry covers every listener and every replica of that Sidecar: the server keeps no session, so it can sit behind a load balancer.

The agent connects to	The agent’s MCP entry
`postgres://agent@payments-sidecar:15432/payments?application_name=claude%20hoop-approval%3Dreturn`	`hoop-approvals` at `http://payments-sidecar:8765/mcp`

Claude Code
Cursor
Other clients

For one developer:

claude mcp add --transport http hoop-approvals http://payments-sidecar:8765/mcp

For a team, commit .mcp.json at the repository root. claude mcp add --scope project writes it:

.mcp.json

{
  "mcpServers": {
    "hoop-approvals": {
      "type": "http",
      "url": "http://payments-sidecar:8765/mcp"
    }
  }
}

Cursor reads the same shape without type, from .cursor/mcp.json in the project or ~/.cursor/mcp.json:

.cursor/mcp.json

{
  "mcpServers": {
    "hoop-approvals": {
      "url": "http://payments-sidecar:8765/mcp"
    }
  }
}

Any client that speaks the Streamable HTTP transport takes the same URL: http://<host>:8765/mcp.

An agent that uses two Sidecars needs two entries, for example hoop-approvals-payments and hoop-approvals-ledger. The denial does not name the Sidecar, so name each entry after the connection string it pairs with, and tell the agent to call the entry of the Sidecar that denied.

On Kubernetes

Set listen: 0.0.0.0:8765 in the config file, so the Service reaches the pod. Then publish the port with one laneServices entry in the chart values:

values.yaml

laneServices:
  mcp:
    enabled: true           # ClusterIP by default; keep it
    ports:
      - {name: mcp, port: 8765}

The agent’s URL is http://<fullname>-mcp.<namespace>.svc:8765/mcp. <fullname> is <release>-hoopsidecar, or the release name alone when it already contains hoopsidecar. kubectl get svc shows it. Every pod in the cluster can reach a ClusterIP Service. Add a NetworkPolicy that admits only the agent’s pods.

Risk Analysis

Holding a statement for a person, return mode, and the retry contract.

Config File

Every other section of the config, and what startup refuses.

Getting Started

Sidecar

Features

Control Plane Setup

Find the approval in the denial

Read the status on an http listener

The MCP server

Tools

Status and next

Connect an agent

On Kubernetes

Next

Risk Analysis

Config File

​Find the approval in the denial

​Read the status on an http listener

​The MCP server

​Tools

​Status and next

​Connect an agent

​On Kubernetes

​Next

Risk Analysis

Config File

Find the approval in the denial

Read the status on an http listener

The MCP server

Tools

Status and next

Connect an agent

On Kubernetes

Next