# Controls API

Who decides for your agents, your own decision server, and policies. The steps are in the guides of the Controls section.

## Control socket

Controls are optional. With none, an account has no limits. With them on, every checked action of your accounts is put to one decider before it runs: STACK's hosted controls, or your own server. One socket per customer. Everything below needs the owner or an admin (agent credentials are refused) and is also in the SDKs, the CLI and the MCP tools.

- GET /v1/control-socket - who decides now (effective_mode: none, hosted or remote), both addresses, which kinds are checked.
- PUT /v1/control-socket/decision - { url, timeout_ms? } sets your decision address. 201 with { socket, secret } the first time: the signing secret is shown once. A browser sign-in or an OAuth token (what a chat assistant has) gets secret null and secret_reveal { url, expires_at } instead: a single-use Console link, good for an hour, where you read the secret once signed in. https only, no credentials, query or fragment; a public host.
- PUT /v1/control-socket/events - { url } sets the address your whole record is streamed to. Same rules, its own secret.
- POST /v1/control-socket/{decision|events}/verify - a signed test exchange; success puts the address into use. POST .../test does the same without changing anything.
- DELETE /v1/control-socket/{decision|events} - remove an address and its secret.
- POST /v1/control-socket/{decision|events}/secret/rotate - a new secret, shown once (to an OAuth token, a secret_reveal link instead); the old one keeps working for 24 hours.
- PUT /v1/control-socket/mode - { mode: hosted | none }. Hosted needs your controls subscription.
- PUT /v1/control-socket/on-unavailable - { on_unavailable: "refuse" | "allow" }. What happens when your own decision server does not answer in time: refuse (default) or allow. Only an answer that never came follows it (no answer in time, unreachable, a non-200, a busy server, an open breaker); a forged or garbled answer, a blocked address and a server not verified or paused are refused whatever it says. allow loosens a control and needs approval in the browser; refuse applies at once.
- PUT /v1/control-socket/checked-types - { types: [...] | null }. null checks every kind. Kinds: model.call, proxy.call, tool.run, email.send, sms.send, call.start, call.answer, meeting.join, browser.session.start, browser.navigate, card.checkout, wallet.payment, workspace.exec, account.open, dropoff.create, dropoff.deposit, a2a.send, skill.invoke, passport.delegate, drive.upload, drive.share, letter.send, post.scan, post.forward, post.shred.
- GET /v1/control-decisions?limit&account_id&verdict&before and GET /v1/control-decisions/:id - the decisions made, with the request as sent for a refusal.

Setting or changing an address, rotating a secret, and anything that loosens your controls (removing an enforcing server, unchecking a kind, switching hosted controls to none or to your own server) need your approval in a signed-in browser. Any other credential gets 403 `GOVERNANCE_APPROVAL_REQUIRED` with the approval link, and the retry carries `X-Governance-Approval`. The chat cannot approve these. Checking more applies at once.

### What your server receives and answers

A signed POST (Standard Webhooks: `webhook-id`, `webhook-timestamp`, `webhook-signature`, an HMAC-SHA256 over `id.timestamp.body` with your `whsec_` secret) whose body names who is acting, the action kind, the target (recipients, host, amount; never message text, prompts, code, page text, card numbers or credentials) and a `request_digest`. Answer within the timeout (at most 2 seconds) with a signed body `{ decision_id, request_digest, verdict: "allow" | "deny", reason?: { code, message? }, retry?: { ref, after_seconds? } }` and `webhook-id` set to the decision id. A deny with `retry.ref` holds the action for an approval; the agent sends the reference back as `X-Control-Ref`. An example server is in `examples/control-socket`.

- A denial is 403 CONTROL_DENIED with details { decision_id, reason_code, retry? }.
- No usable answer (timeout, error, bad signature, an answer for another request) is 403 CONTROL_SOCKET_UNAVAILABLE with details { decision_id, cause }. It is refused and never allowed on silence.
- A refused action is never charged: its action count is handed back. STACK's own hosted controls failing is 503 CONTROL_UNAVAILABLE, also not charged.
- A decision your own server makes is charged $2 per 10,000, whether it allowed or denied; a decision it did not answer is not charged. A hosted check is charged on the check meter, one per checked action, whether it allowed or denied: the price is per action checked, and the action itself is never charged when it is refused. The check is charged after the decision and before the action, so an action STACK refuses afterwards (consent, calling hours, credit) still leaves its check charged. If a check that denied cannot be charged (no credit), the agent is still refused with CONTROL_DENIED. Unchecked kinds are not asked and not charged.

Your events address receives every audit row of your account as signed batches of up to 100 events, in order, at least once (use the event `id` to ignore repeats). Each event carries `entry_hash` and `prev_entry_hash` so you can check the chain. If your receiver is down, STACK retries for up to 72 hours; a batch it refuses three times is announced as a `stack.events.gap` event. Delivery never delays an action.

## Policies

A policy is the configuration behind hosted controls: what an agent may not do, what needs a person, and how much it may do, beyond the connection grants it already has. It only narrows. It never opens anything a grant did not, and nothing about it is written into the agent's Passport. There is one policy per agent and one default for your account that applies to every agent without its own. They need hosted controls on; the owner or an admin writes them and agent credentials are refused everywhere, so an agent can never read or change its own controls.

- GET /v1/control-policies - every policy, and whether controls are on. GET /v1/control-policies/default and GET /v1/control-policies/agents/:agentId read one ({ policy, in_force }).
- PUT /v1/control-policies/default and PUT /v1/control-policies/agents/:agentId - { definition, expected_revision? } creates a policy, or revises it when you send the revision you read. The answer says whether the change tightened or loosened.
- DELETE /v1/control-policies/default and DELETE /v1/control-policies/agents/:agentId?expected_revision - delete one; the agent falls back to the default.
- POST /v1/control-policies/agents/:agentId/start-from-current-access - a policy equal to the agent's current connection grants. It changes no outcome until you tighten it. It is also made for you when controls are switched on.
- POST /v1/control-policies/simulate - { agent_id | definition, call: { action, target?, amount_cents?, request?, connection_id?, mission_id? } } tries one call against a policy and says allow, review or deny, with the rule and what is left of each limit. Nothing is counted, held or sent.
- GET /v1/control-policies/:id/revisions - every revision, with who made it. GET /v1/control-reviews[?status=pending|all] and GET /v1/control-reviews/:id - the actions a policy held for a person.

A definition has these sections; every list is an allowlist when present and no restriction when absent, and every number is a ceiling.

- connections - mode any (every granted connection, minus what a rule refuses or holds) or listed (only what an allow rule names), and rules: an effect (allow, review or deny), a connection, catalog intents and raw constraints. A rule that allows a send must name who receives it, or set its recipients to "per_mission" so each Mission names them (400 UNBOUNDED_SEND_RULE otherwise); a review or deny rule may be broad.
- actions - a stance per kind of action (model.call, proxy.call, email.send, ...): allow, review or deny.
- recipients - email (addresses, or @domain), sms and call (E.164 numbers) the account may reach. An email goes only when every recipient (To, Cc and Bcc) is on the list. Each of the three may instead be "per_mission": a send then names the stored message it answers with reply_to_message and goes only to whoever wrote it.
- spend - max_per_action_cents; limits, each a window (day, month or mission) and a unit (cents or actions) that parallel calls cannot overrun; max_concurrent, the actions of one agent running at the same moment.
- review - over_cents: hold an action above this amount for a person.
- surfaces - models (allowed names, max_cost_per_call_cents), browser.hosts, card (merchants, max_amount_cents), wallet (payees, max_amount_cents), workspace (max_timeout_seconds) and tools.allowed.

Recipients set per job: each Mission names who it may send to. A connection rule with effect allow carries `recipients: "per_mission"`. A send is allowed only in a Mission that names the recipients exactly, and only to them. A Mission that does not name them is refused with reason `recipients_not_pinned`; a send to someone the Mission did not name is refused with `recipient_not_allowed`. The Mission names them when it opens, with `recipients`, `recipient_pins` or `reply_to_message` (see Missions). A delegated Passport carries the same Mission, so it carries the same recipients; the per-job rules of the agent the Mission was opened for apply to it too.

The account's own `recipients.email`, `recipients.sms` and `recipients.call` can be `"per_mission"` too. The email send, the text and the call then name the stored message they answer with `reply_to_message` and go only to whoever wrote it; a reply goes to who wrote the message in its path (with `reply_all`, also the original's own To and Cc), and an invite response to its organizer. A send that names no message (a forward, a new email, text or call) may go to whoever the owner pinned on the account's Mission, and with none pinned is refused with `recipients_not_pinned`; a recipient other than the sender is refused with `recipient_not_allowed`, and an id that is not one of the account's received messages is 404 `NOT_FOUND`. An email's sender is not pinned when the receiving server failed it on DMARC; the answer is then 422 `MESSAGE_SENDER_NOT_VERIFIED` and nothing is sent. A missing verdict refuses nothing. A text or a voicemail is the number it came from. Changing a list to `"per_mission"`, or back, is a loosening; setting it where there was no rule is a tightening.

Tightening a policy applies at once. Loosening it, deleting it and switching controls off need your approval in a signed-in browser (`account_control_loosen`): any other credential gets 403 `GOVERNANCE_APPROVAL_REQUIRED` with the approval link, and the retry carries `X-Governance-Approval`. A revision that is not provably a tightening counts as a loosening, mixed changes included.

- A refusal is 403 CONTROL_DENIED with details.rule { policy_id, policy_revision, section, rule, code }: which rule refused, never a value from the call. The same evidence is on the decision, in the audit log and on your events stream.
- An action held for a person is 403 CONTROL_DENIED with reason review_required and details.retry.ref. A person approves it on the approval page or in the chat; the agent sends the same call again with X-Control-Ref. One approval covers one call, once.
- A spend limit refused while paying is 403 CONTROL_LIMIT_EXCEEDED. A refused action is never charged.
