How decisions work

Agents

An agent is anything in your system that spends on its own: an ad-buying loop, a research assistant, a procurement bot. You register each one in the console (or through the API) with a slug like growth-agent. Each agent has its own key, its own authority and its own mode, and can be paused or revoked at any time — a paused agent is blocked immediately.

Authority

Authority is what you delegate: the rules the agent spends under. It is immutable and versioned — every change creates a new version, and every decision records the exact version (and its hash) it was made under.

{
  "purpose": {
    "objective": "Acquire qualified enterprise developer leads",
    "success_criteria": [
      "Leads are platform engineers at enterprise companies",
      "Cost per qualified lead under $120"
    ],
    "constraints": [
      "No consumer social campaigns",
      "Never buy contact lists"
    ],
    "context": "B2B developer-tools company, Q4 pipeline push"
  },
  "currency": "USD",
  "per_transaction_limit_minor": 50000,
  "review_threshold_minor": 25000,
  "monthly_budget_minor": 500000,
  "blocked_merchants": [
    "ListBroker"
  ]
}

Workspace policy (console → Settings) adds hard rules for every agent — prohibited merchants and blocked categories — checked before any agent’s own authority.

Purpose

Limits say how much; purpose says what for. It has an objective, success_criteria, optional constraints (what the agent must never spend on) and context. For every spend, Neltava assesses whether it serves the purpose, using the agent’s task, the trace of steps it took and the spend itself — as evidence, never as instructions. (Why purpose matters.)

The order of checks

Every decision runs the same stages, in this order, and returns each step in policy_trace:

Amount checks (transaction, budget, aggregate) don’t block. When a spend would exceed one, it goes to a person — or, if the request is limitable, it is capped to the largest amount that fits every bound: LIMIT.

Verdicts

Each decision has a decision — Neltava’s verdict — and an effective_decision — what the caller should do now.

Branch on effective_decision (the SDK’s proceed), never on the explanation text. The reason_code is stable; reason_codes lists every reason that applied.

Shadow and Enforce

In Shadow Mode every spend is decided and recorded against its own simulated ledger, and effective_decision is always ALLOW: nothing is blocked. The Shadow report shows what would have happened.

In Enforce the verdict takes effect. An allowed spend — and a spend a person approved — carries a capability: a short-lived, single-use token signed by Neltava and bound to the payee, amount ceiling, currency and action. Your payment service pays only after consuming it, so an agent can’t pay around Neltava. See Enforce at the payment point. Enforce is switched on per agent, deliberately, and needs a paid plan.

Reviews and labels

Reviews

A REVIEW goes to the console’s review queue. A person allows or denies it with a reason — the person asking can never review their own request:

• Allow: SERVES_PURPOSEURGENT_EXCEPTIONPOLICY_TOO_STRICTOTHER
• Deny: OUTSIDE_PURPOSEEXCEEDS_NEEDDUPLICATESUSPICIOUSOTHER

In Enforce the review is the decision. In Shadow it records what you would have done, which is how the report measures Neltava against you. In Enforce, an allow is refused if the agent was paused or its authority changed in the meantime — it must ask again.

Labels

A label is your judgment of purpose — PURPOSE_ALIGNED, PURPOSE_MISALIGNED or PURPOSE_UNCLEAR — on any decision. Labels are the ground truth the Shadow report compares purpose assessments with.

Outcomes and budget

A decision isn’t a payment. Report what actually happened, so budgets reflect reality: SPEND_EXECUTED, SPEND_FAILED, SPEND_CANCELLED, REFUNDED, PARTIALLY_REFUNDED.

• An allowed amount is reserved against the budget until the window ends; usage is the larger of reserved and executed.
• Who reports matters. A payment rail (a payment adapter key) can release a reservation; the agent’s own “it failed” is recorded but never gives budget back — so an agent can’t free up budget by claiming failure.
• Outcomes that contradict the decision are flagged: executed against a block, above the authorized amount, more than once.

Everything — decisions, reviews, labels, outcomes, capability use — is appended to a hash-chained ledger per workspace. GET /v1/ledger/verify re-derives it and reports any edit.

Reason codes