Stop, Confirm, Limit
How Contexa stops an agent, asks the accountable person to confirm its request, and limits its pace and scope, according to the decision and the settings. It also covers the answers an agent receives and how to handle them, how administrators release a stop, and the console screens.
At a glance
- Agent request
- ①Call limitsPast the calls allowed per minute:
429 AGENT_CALL_LIMIT - ②Ended delegationRevoked:
403 DELEGATION_REVOKED; expired or not started: a confirmation is asked for - ③CHALLENGE decisionA confirmation is asked for (
403 AGENT_CONFIRMATION_REQUIRED); an approved confirmation lets it through once - ④Narrowed scopeWhile only reading is allowed after a risky decision, other operations get
403 AGENT_SCOPE_NARROWED - ⑤Before a
@ProtectablemethodDecided in place when there is no decision; an ALLOW in force is reused for a few requests only - Runs
What works under each ownership
The gate (① to ④) runs in both ownership modes: inside the security chain Contexa builds under CONTEXA_OWNED, and as a servlet filter right after the application's Spring Security chain by default (HOST_OWNED), behind the authentication bridge that stamps the delegation. The @Protectable methods (⑤) and the handling after a decision work in both.
| Control | CONTEXA_OWNED( @EnableAISecurity(mode = SecurityMode.FULL)) | HOST_OWNED (default) |
|---|---|---|
| Enforcing stored decisions (BLOCK, CHALLENGE, ESCALATE) | At the URL and at @Protectable | At the URL (filters right after the application's chain) and at @Protectable |
| Deciding an agent request with no decision in place, limiting ALLOW reuse, decision merging | Works | Works (@Protectable) |
| Stopping after a BLOCK (delegation revoked, tokens revoked, notice) | Works | Works. Tokens are revoked only with an AgentTokenRevoker |
| Confirmation by the accountable person (CHALLENGE, ended delegation) | Works | Works. An agent's CHALLENGE is answered with 403 AGENT_CONFIRMATION_REQUIRED and the confirmation status address |
| Refusing revoked delegations, call limits and denial alarm, refusing outside a narrowed scope | Works | Works |
Policy expression agentRequestConfirmed() | Works | Works |
| Refusing a suspended agent's token | Contexa resource server and authorization server | Up to your resource server |
| Evaluating again as the delegator | URL and method policies | Method policies |
Answers an agent receives
The agent (or its framework adapter) must understand and handle these answers. The body is JSON; the fields below come with error, message and path.
Status, error | When | What the agent does |
|---|---|---|
429 AGENT_CALL_LIMIT | Past a call limit. Body scope (DELEGATION or AGENT), limit, retryAfterSeconds | Sends again after Retry-After seconds |
403 DELEGATION_REVOKED | The request runs under a revoked delegation. Body delegationId | Stops. The person must delegate again |
403 AGENT_CONFIRMATION_REQUIRED | The decision is a CHALLENGE, or the delegation expired or has not started | Polls statusUrl and sends the same request again once it is APPROVED (confirmation) |
403 AGENT_SCOPE_NARROWED | An operation outside the narrowed scope. Body allowed, until, operation | Does only the allowed operations until until, or gets the request confirmed |
413 AGENT_CONFIRMATION_UNBINDABLE | A confirmation is needed but the body is larger than a confirmation can be bound to (1 MB by default) | Sends it in smaller parts |
429 ZERO_TRUST_ANALYSIS_BUSY | Decision merging is on and every analysis place and queue slot is taken | Sends again after Retry-After seconds |
Confirmation by the accountable person
On a CHALLENGE decision a person is asked to step up (MFA), but an agent cannot do MFA. So Contexa asks the person accountable for that agent to confirm that request.
- Agent→AppRequest
- Contexa→Agent
403 AGENT_CONFIRMATION_REQUIREDwith the confirmation ID, status URL and expiry - Contexa→PersonA notice (mail, else the console) with a link to the confirmation page
- Person→ContexaApprove, refuse or report
- Agent→Contexa
GET statusUrl→APPROVED - Agent→AppSends the same request again → runs once (
USED)
{
"status": "PENDING",
"error": "AGENT_CONFIRMATION_REQUIRED",
"trigger": "DECISION_CHALLENGE",
"confirmationId": "6f1c2a90-…",
"statusUrl": "/contexa/api/agent-confirmations/6f1c2a90-…",
"expiresAt": "2026-11-02T06:15:00Z",
"confirmationHeader": "Contexa-Agent-Confirmation",
"message": "The person accountable for this agent must confirm this request; …",
"path": "/api/reports/export"
}
- Who confirms: the delegator for a delegated agent, the sponsor for an autonomous agent. Without an accountable person no confirmation is made and the request is refused (the body has no
confirmationId). - A confirmation is bound to its request: tenant, user, agent, method, path, query string and the body's SHA-256. It is used only by that same request and becomes
USEDonce used. The agent may name the confirmation ID in theContexa-Agent-Confirmationheader when sending again. - Time: the person's answer is awaited for
confirmation-timeout(15 minutes by default), and an approval must be used within the same time. Past it the confirmation isEXPIRED(refused); expired ones are swept every minute. - Report: when the person reports the request, it is refused and the agent is stopped at once (as in stopping, with a BLOCK stored right away).
- An approval is kept as a verifiable record. With Contexa's authorization server it is an OAuth2 authorization, without it a signature with the evidence signing key, verified again when used. What was confirmed also goes into the decision context (the
Confirmationline). - On the confirmation page only the person the confirmation is for decides, in their own session. A request from an agent is refused there even with that person's token.
| Confirmation status | Meaning |
|---|---|
PENDING | Waiting for the person |
APPROVED | Approved, not used yet |
USED | Approved and used by its request |
REJECTED, EXPIRED, REPORTED | Refused, timed out, reported (all final refusals; refused is true in the status) |
An agent asking for confirmation first
With the policy !delegationRequiresApproval() or agentRequestConfirmed() on work whose delegation requires approval, the agent can ask for a confirmation itself before it runs (trigger REQUESTED).
POST /contexa/api/agent-confirmations
Content-Type: application/json
{ "method": "POST", "target": "/api/reports/export?month=2026-10",
"bodySha256": "9f86d081…", "reason": "Monthly report export" }
It returns 202 with the confirmation's status (409 without an accountable person, 403 when the caller is not an agent). target is the path with the query, starting with /; bodySha256 is the SHA-256 (hexadecimal) of the body it will send. Poll the status at GET /contexa/api/agent-confirmations/{id}. This too needs the gate that consumes confirmations, so it works only under CONTEXA_OWNED.
The start of the confirmation link in notices is set with confirmation-link-base-url (for example https://app.example.com). Left empty, the link is relative, with the application's path only. The Host header the agent sent is never used in the link.
Stopping and releasing
When a BLOCK is decided on an agent's request, that agent only is stopped. It is not added to the people's block list, and the person's own work goes on.
A delegated agent is blocked
- The decision is stored under the agent's key (
<user>::agent::<agent>) - The delegation is revoked
- The tokens it holds for that person are revoked
- The delegator is told
An autonomous agent is blocked
- Its registration is suspended (
SUSPENDED): every token issued to it is refused - Its tokens are revoked
- Its sponsor is told
A report by the accountable person and a call limit set to STOP stop the agent the same way. A stop is released through the admin API or console, or on the accountable person's confirmation page (a kill switch stop by administrators only).
action | Fields | What it does |
|---|---|---|
RELEASE_DELEGATION | userId, agentId | Clears the agent's decisions for that person so its next request is decided again. The revoked delegation stays revoked; the person delegates again |
RELEASE_AGENT | agentId (tenantId optional) | Puts the registration back in service and clears the agent's decisions |
KILL_SWITCH | agentType, tenantId (optional) | Stops every agent in service of that type (all types when empty) at once |
KILL_SWITCH_RELEASE | The same | Puts back only the agents the kill switch stopped; agents stopped for other reasons stay stopped |
POST /contexa/admin/api/agents/stops
Content-Type: application/json
{ "action": "KILL_SWITCH", "agentType": "AGENT", "reason": "Prompt injection incident" }
reason is required and the ADMIN role is needed. GET shows the stopped agents and delegations. Without the service that stops agents (AgentContainmentService) it answers 503 (the autonomous security plane is off). A scope a BLOCK narrowed stays narrowed after the release until its period ends.
Scope narrowing
After a risky decision on an agent's request, the agent's next requests may only read for a while.
- When: after a CHALLENGE, ESCALATE or BLOCK, or an ALLOW whose risk reaches
risk-threshold(0.7 by default). - How long:
duration(1 hour by default). A scope is only narrowed, never widened. - The operation is read from the method and the words of the path (
READ,WRITE,EXPORT,DELETE,ADMIN,EXECUTE). AGET /api/exports, for example, is an export (EXPORT). - A request outside the scope gets
403 AGENT_SCOPE_NARROWED; it passes once its accountable person confirms it. A person's request is never narrowed.
Call limits and the denial alarm
| Limit | Default | Counted for |
|---|---|---|
| One delegation | 120 per minute | One person's work (the agent's decision key) |
| The whole agent | 600 per minute | Everyone the agent acts for |
- Past a limit,
on-exceeddecides:THROTTLE(default,429withRetry-After) orSTOP(the agent is stopped; the request's own answer is still429). - Denial alarm: when at least 10 requests in 5 minutes were refused at a rate of 50% or more, an audit record is written and the accountable person is told (once per window).
- When the enforcement mode is not
ENFORCE(SHADOW and so on), a request past a limit goes on and is only recorded. The counts are per instance.
Requests with no decision, and ALLOW reuse
- No decision yet: a person's request goes on and is analysed afterwards, but an agent's request is decided in the request, even at an asynchronous
@Protectablemethod (protectable.unrecorded-agent-request: DECIDE_IN_PLACE, default). WithPROCEEDit goes on as a person's does. - An ALLOW in force: for a person it answers later requests for its validity, but for an agent only the same operation, 3 distinct resources and 10 requests; for a sensitive resource (
SENSITIVEorCRITICAL) only 1 resource. Past that the request is decided again in place, so an agent that reads a customer list one record at a time cannot read it all on its first ALLOW.
Decision merging (off by default)
When one agent sends many requests at once, the model is not called for each: the same question is analysed once. While the first request is analysed, the others wait for its verdict and are answered by it.
Setting (contexa.security.zerotrust.agent.flight.*) | Default | Meaning | When to change |
|---|---|---|---|
enabled | false | Turns it on | When one agent sends bursts of the same request and model calls pile up |
max-in-flight-analyses | 3 | Analyses one agent may have running at once | To match model throughput |
queue-capacity | 20 | Requests that may wait for a place | When 429 answers are frequent |
wait | 40s | The longest wait. Past it: 429 ZERO_TRUST_ANALYSIS_BUSY | With slower models (Layer 2 included) |
pass-budget | 3 | Requests that may pass before the first verdict (0 for none) | 0 to let nothing pass before the first decision |
pass-families | [READ] | Operations that may pass first; only for resources your application declared non-sensitive | To change which operations may pass first |
- No request is let through for lack of a verdict;
pass-budgetabove is the only exception. - A restriction (BLOCK, ESCALATE, CHALLENGE) stored for the agent while requests wait answers them at once.
- A failure of decision merging itself is not a decision: each request is then analysed on its own. The state is kept in memory per instance.
In modes that do not enforce (SHADOW and so on)
When the enforcement mode is not ENFORCE (SHADOW, OBSERVE, DISABLED, or contexa.security.zerotrust.enabled=false), the gate records ended delegations, narrowed scopes and call limits and lets the request on. The re-evaluation as the delegator is only recorded too. A CHALLENGE in force still waits for its confirmation.
Policy expressions
| Expression | Meaning |
|---|---|
agentRequestConfirmed() | Whether the accountable person confirmed this very request (true only for an agent's request) |
agentCallsInLastMinuteAtMost(n) | Whether this delegation made at most n requests in the last minute, this one included; true for a person and when nothing counted them |
The delegation expressions are in Delegation and Objective Contracts.
Decision records and tamper checks
Each decision leaves one decision record in the audit log (ctxa_audit_log, category SECURITY_DECISION). For a person's request the agent and delegation fields are empty.
| Field | Content |
|---|---|
| Subject | The subject kind, the agent, the delegator, the delegation id |
| Operation asked for | The request's action family |
| Risk facts | The reason codes the decision cited, with their fact IDs |
| Enforcement | The response enforced and why. The outcome is APPLIED, KEPT_STRICTER (a stricter response already in force was kept), OBSERVED_ONLY (recorded only, in a mode that does not enforce) or DISCARDED (the processing lost ownership and the result was dropped) |
| Request context hash | The SHA-256 of the time, tenant, user, agent, delegation, operation, method, path, target, requested items and argument summary |
With a signer (the signing key of sealed evidence), decision records are chained in the order they are saved: each record's fields and the previous record's hash are hashed together with SHA-256 and signed. The admin console's security event log shows the check result of each record.
| Result | Meaning |
|---|---|
VERIFIED | As sealed |
MISMATCH | A field changed, the hash was computed again so the signature fails, or a record in the middle of the chain was removed |
UNVERIFIABLE | Written before records were sealed, or signed with a key no longer held (for example a temporary key before a restart) |
The oldest records removed by the audit log retention (default 90 days, System Settings) do not count as MISMATCH.
A decision record keeps the time of its event, and the save does not write it again, so the record is verified as it was sealed. A decision record saved before this was fixed had its time written again by the save and stays MISMATCH; it is not sealed again, so that a mismatch keeps meaning a record was altered (Old decision records mismatch after an upgrade).
Console screens and APIs
| Screen or API | Path | What it does |
|---|---|---|
| Agent list, detail, registration | /contexa/admin/agents (/detail, /new) | Registry, status, delegations, decision records |
| Agent stops tab | /contexa/admin/blacklist/agents | Stopped agents and delegations, release, kill switch |
| Confirmation page | /contexa/agent-confirmations | My confirmations and notices; approve, refuse, report; release my stopped agents (reason required) |
| Learning control API | /contexa/admin/api/agents/learning | QUARANTINE (kept but never read, nothing more learned), RELEASE or REMOVE the learning of an agent or of one delegation. Other agents' and people's learning is never touched |
Stops, releases, confirmations and delegation records are all kept in the audit log (AGENT_* categories).
Settings
All under contexa.security.zerotrust.agent. (except the last row).
| Setting | Default | Meaning | When to change |
|---|---|---|---|
confirmation-timeout | 15m | How long a confirmation is awaited, and how long an approval may be used | When accountable people need longer to answer, or waits should be shorter |
confirmation-sweep-interval | 1m | How often expired confirmations are swept | Rarely |
confirmation-link-base-url | None | The absolute start of the link in notices | When notice links must be absolute (opened from mail) |
confirmation-max-body-bytes | 1048576 | The largest body a confirmation is bound to | When requests that need confirmation carry bodies over 1 MB |
scope-narrowing.enabled / .duration / .risk-threshold | true / 1h / 0.7 | Scope narrowing | To fit the period or risk threshold to your work, or to turn it off |
call-limit.enabled / .per-delegation-per-minute / .per-agent-per-minute / .on-exceed | true / 120 / 600 / THROTTLE | Call limits | When normal traffic nears the limits, or past them the agent should be stopped (STOP) |
denial-alarm.enabled / .window / .min-requests / .rate | true / 5m / 10 / 0.5 | Denial alarm | When alarms are too frequent or too rare |
allow-reuse.max-requests / .max-distinct-resources / .sensitive-max-distinct-resources | 10 / 3 / 1 | How far an ALLOW is reused | To widen or narrow what one ALLOW answers (wider: fewer decisions, more risk) |
flight.* | The table above | Decision merging | The table above |
contexa.security.zerotrust.protectable.unrecorded-agent-request | DECIDE_IN_PLACE | An agent request with no decision (PROCEED: as a person's) | When agent requests should go on while analysed, as a person's do (PROCEED) |
Extension points
| Bean | When you need it | Default |
|---|---|---|
AgentNoticeChannel | To notify through chat, push or tickets instead of mail | Mail when a mail sender exists (the person's account needs an address), else kept in the console only |
AgentTokenRevoker | To revoke an external authorization server's tokens on a stop | With Contexa's authorization server it revokes there; otherwise nothing is revoked (stop and BLOCK are relied on) |
AgentConfirmationAuthorizer | To keep approvals in your authorization server | A Contexa authorization server grant, else a signature with the evidence signing key |
AgentScopeNarrower / AgentScopeStore | To narrow differently or store elsewhere | Read only for 1 hour / JDBC or memory |
AgentConfirmationStore / AgentNoticeStore | To change the store | JDBC (ctxa_agent_confirmation and ctxa_agent_notice tables) or memory |
Operations notes
- Several instances: call limit counts and decision merging state are in memory per instance. In-memory registries and stores are lost on restart, so use the Contexa database in production.
- Without the stop service (
AgentContainmentService) there is no stop after a BLOCK and no narrowing, and the stop API answers503.contexa.autonomous.enabled: falsedoes not produce this state; it turns all of Contexa off. - An agent's decision is the model's; the engine only computes facts (Decision Engine).