RFC: financial_governance spec block for payment-capable agents

[Danbi58]

Problem

The compliance block in agent.yaml handles identity, SOD, and
audit logging at the definition level. But there's currently no
standard way for an agent to declare its runtime financial
controls — spending caps, category allowlists, human approval
thresholds, and which financial firewall enforces them.

This creates a gap for developers building payment-capable agents.
The compliance block says "this agent has financial risk tier: high"
but doesn't say "this agent cannot spend more than $50 per
transaction" or "transactions above $20 require human approval."

Recent evidence this matters

These are documented incidents from the past few months where the
absence of runtime financial controls caused real damage:

Feb 2026 — $82,314 in 48 hours
A startup's Google API key was compromised. Attackers ran Gemini
API calls for 48 hours. Bill: $82,314. The team's normal monthly
spend was $180. No spending cap existed to limit the damage.
(Source: The Register, March 2026)

Nov 2025 — $47,000 over 11 days
Four LangChain agents entered an infinite loop — an Analyzer and
a Verifier ping-ponging requests. The team assumed rising costs
were organic growth. The loop ran 11 days. The only thing that
stopped a similar incident in Feb 2026 was an external API's
rate limiter — not the team's own controls.
(Source: Multiple technical post-mortems)

Feb 2026 — $441,000 sent to a random address
An AI agent tasked with distributing small token rewards suffered
a session crash. On reboot, a decimal parsing error caused it to
autonomously send 52 million tokens — 5% of total supply — to a
random wallet. No transaction cap. No human-in-the-loop for large
sends.
(Source: MEXC News, 2026)

Mar 2026 — Cursor Background Agents, no per-task cap
Autonomous coding agents ran complex tasks for hours, burning
token allowances at 5–10x the expected rate. Developers reported
$135+ in unexpected charges in a single week with no built-in
way to set a per-task spending limit.
(Source: DEV Community, March 2026)

None of these required malicious intent. All were preventable
with a declared spending cap enforced at runtime.

The gap in the current spec

The existing compliance block is excellent for declaring intent:

compliance:
  risk_tier: high
  supervision:
    human_in_the_loop: on_flagged
  recordkeeping:
    audit_logging: true
    retention_period: 7y

But it doesn't declare enforcement. There's no standard field
for:

• What is the per-transaction spending cap?
• Which payment categories is this agent allowed to use?
• At what amount does a human approval gate trigger?
• Which runtime financial firewall enforces these controls?

Proposed addition: financial_governance block

A new optional block — additive, disabled by default, ignored by
exporters that don't implement it:

financial_governance:
  enabled: true
  firewall: valkurai              # Reference implementation
  firewall_endpoint: https://api.valkurai.com/v1
  agent_key_env: VALKURAI_AGENT_KEY  # Never hardcode — env var only

  spending:
    max_per_transaction_cents: 5000   # $50 per transaction
    max_monthly_cents: 50000          # $500/month total
    currency_default: AUD
    allowed_categories:
      - software
      - api
      - saas
      - cloud
    blocked_categories:
      - gambling
      - crypto
      - unknown

  approval:
    require_above_cents: 2000         # Human approval above $20
    approval_channel: slack
    approval_timeout_minutes: 60
    auto_deny_on_timeout: true

  notifications:
    on_flagged: [slack, email, sms]
    on_blocked: [slack, email]
    on_safe: []                       # No noise for approved transactions

  audit:
    immutable: true
    retention_period: 7y             # Aligns with compliance.recordkeeping

Design notes

firewall is a string, not an enum. Any compliant
implementation can be referenced here. The reference
implementation is Valkurai but the
spec is intentionally open — this is a standard, not a
product lock-in.

agent_key_env requires an environment variable reference.
Consistent with how agent.yaml handles all credentials —
secrets never appear in the definition file itself.

approval.require_above_cents mirrors the SOD pattern.
Declarative policy defined in the agent spec, enforced at
runtime by the firewall. Same separation of concerns as the
existing conflict matrix.

audit.retention_period aligns with compliance.recordkeeping.
Both blocks can reference the same retention requirement —
the compliance block declares intent, this block declares
the enforcement mechanism.

Agents without payment capabilities ignore this entirely.
enabled: false is the default. Zero impact on existing
agent definitions.

How it complements the existing spec

Concern	compliance block	financial_governance block
Risk tier declaration	✅	—
Audit logging intent	✅	—
SOD roles and conflicts	✅	—
Runtime spending cap	—	✅
Transaction category allowlist	—	✅
Human approval threshold	—	✅
Payment firewall reference	—	✅
Immutable transaction audit	—	✅

Relation to other standards

This proposal is consistent with:

• Agentic Commerce Protocol
  (OpenAI + Stripe) — ACP defines how agents transact, this
  block defines the governance layer that sits in front of
  those transactions
• EU AI Act (applying Aug 2026) — PSPs enabling AI agents are
  generally liable for unauthorised transactions they cannot
  explain; this block provides the declaration layer for that
  explainability

Next steps

Happy to follow up with a PR adding:

• The schema definition for financial_governance in
  spec/agent.schema.yaml
• A complete examples/financial-agent/ directory with a
  purchasing agent using this block
• A tools/valkurai_pay.json tool schema showing how the
  firewall integrates with the agent's tool definitions

Wanted to raise the RFC first to check if this direction is
of interest before writing the code.

[Danbi58]

This is exactly the gap worth resolving before this launches. thank you
for the structured feedback and specific details and ideas, truely appreciate it.

You're right that approval_channel: slack is notification-shaped,
not protocol-shaped. The approval loop closes on human intent but has
no typed round-trip contract, which means every firewall implementation
will wire it differently and the audit trail won't be portable across
compliant tools.

The three-object schema addresses this cleanly:

• payment_required gives the agent a typed event to emit and wait on
• payment_approval gives the operator a canonical response object with
  identity and timestamp — which is exactly what the EU AI Act
  explainability requirement needs: not just that a log exists, but
  that the authorisation event is attributable and structured
• payment_receipt closes the audit loop with a settled amount and
  credit status

I'll update the PR to:

1. Add a payment_schema_version field to financial_governance
2. Add an event_schema block defining the three objects
3. Update the purchasing-agent example to reference the schema version

Proposed addition to the spec block:

financial_governance:
  payment_schema_version: "1.0"
  
  event_schema:
    payment_required:
      fields: [type, amount_cents, currency, category, context, request_id]
    payment_approval:
      fields: [type, request_id, approved, approved_by, approved_at]
    payment_receipt:
      fields: [type, request_id, amount_settled_cents, settled_at, credit_status]

This keeps the spec implementation-agnostic, any compliant firewall
that implements the contract can serve as the approval surface, whether
that's a Slack bot, a chat thread, or an automated policy engine. The
approval_channel field then becomes the delivery surface for
payment_required, with payment_approval and payment_receipt
returned via the firewall's callback endpoint rather than being
channel-specific.

On payment_schema_version and the EU AI Act point specifically: i
agree that a versioned schema makes the PSP liability requirement
tractable. A log entry saying "approved" is not sufficient; a
structured payment_approval event with approved_by and
approved_at is.

Will update the PR with these additions. Does the schema field
structure above match the intent, or would you prefer the event
objects defined externally and referenced by URI?

[shreyas-lyzr]

Review

Thanks @Danbi58 — this is a well-researched RFC. Verified all four cited incidents independently and they check out. The gap is real: our compliance block handles regulatory intent (FINRA, SEC, SOD, audit logging) but has zero runtime financial controls. The only cost-related field in the entire spec today is cost: none|low|medium|high on tool annotations.

The core proposal is sound. Declarative spending caps, category allowlists, and human approval thresholds are genuinely missing — and the incidents prove the need.

A few points to discuss before moving to a PR:

1. Vendor neutrality

The proposal names Valkurai as the "reference implementation" and bakes in firewall_endpoint / agent_key_env fields that feel vendor-specific. The spec should define the what, not the who. Suggestion: keep firewall as a generic string identifier, but move endpoint/auth config to a separate integrations or providers block — or let those be runtime config rather than spec fields.

2. Avoid duplicating compliance.recordkeeping

The proposed audit.retention_period and audit.immutable duplicate fields already in compliance.recordkeeping. The financial governance block should reference the existing retention policy, not redeclare it. e.g.:

financial_governance:
  audit:
    extends: compliance.recordkeeping   # reuse existing retention/immutability
    transaction_log: true               # add financial-specific fields only

3. Placement — top-level vs sub-block

Given the existing compliance structure, compliance.financial_governance would be more consistent than a new top-level block. The compliance section already handles risk_tier, supervision, recordkeeping, SOD — financial controls are a natural extension of that hierarchy. Open to arguments either way.

4. What we'd want in a PR

If we proceed, the PR should include:

• Schema addition in spec/schemas/agent-yaml.schema.json
• Spec update in spec/SPECIFICATION.md
• Validation rules in src/commands/validate.ts (e.g., high risk_tier agents with financial tools should warn if no spending caps)
• Export support in src/adapters/shared.ts (buildComplianceSection)
• Example agent in examples/financial-agent/
• Audit command support in src/commands/audit.ts

Happy to greenlight a PR once we align on the vendor neutrality and placement questions above.

[JiwaniZakir]

The core gap here is that the existing compliance block operates at definition time (static metadata), while financial controls need to be enforced at execution time — meaning the enforcement logic lives outside the spec entirely, typically delegated to whatever runtime or SDK is invoking the agent. Without a standardized schema for expressing caps and approval thresholds in agent.yaml, each team is reimplementing these controls ad hoc (or skipping them), which is exactly what the incident pattern shows. A financial_governance block would need to be more than declarative documentation — the agent runtime would need to actively read and enforce those fields before dispatching any payment action, similar to how limits blocks work in some CI/CD specs. Worth considering whether enforcement belongs in the spec schema itself or in a companion policy-enforcement layer that validates against the spec, since a declaration that nothing reads is just documentation.

[JiwaniZakir]

The core gap here is architectural: the existing compliance block operates at definition-time (static declarations about risk tier, identity, audit logging), but financial controls are inherently runtime concerns — they need to evaluate live transaction context like amount, category, and cumulative spend within a rolling window. Mixing these into compliance would conflate policy declaration with enforcement state. The incidents cited share a common root cause: spending controls were either delegated entirely to external systems (API rate limiters, cloud billing alerts) or nonexistent, meaning the agent's own execution context had no way to self-limit or escalate. A financial_governance block would need to be more than declarative — it would need a defined interface for a runtime enforcement hook (the "financial firewall" reference in the issue) that the agent executor calls synchronously before committing any financial action, similar to how some systems implement pre-execution tool guards.

[Danbi58]

@shreyas-lyzr
Thanks for the thorough review and for independently verifying the incidents.

Responses to each point you raised:

1. Vendor neutrality — agreed. firewall_endpoint and agent_key_env were always intended as runtime config, not spec fields. They crept into the RFC example as implementation noise. The spec should only define firewall: as a reference identifier; endpoint, auth, and transport config belong in a separate runtime integrations block or environment-level config entirely. Happy to restructure the PR accordingly.
2. audit.extends — clean solution. Reusing compliance.recordkeeping via extends is the right call; redeclaring retention_period would create drift risk. The financial block only needs transaction_log: true and the event schema additions I noted in my earlier comment.
3. Placement — I can see the argument for compliance.financial_governance given the existing hierarchy. My hesitation was that financial controls have a runtime enforcement dimension that the rest of compliance doesn't — it's less "declaring intent" and more "defining a callable interface" (as JiwaniZakir has also noted). But I'll defer to maintainer preference here; if the consensus is sub-block, I'll write the PR that way.
4. PR scope — the list you've outlined covers exactly what's needed. I'll include validation rules that warn when risk_tier: high agents with financial tools have no spending caps declared — that's the most actionable enforcement surface in the toolchain today.

Ready to proceed on that basis if you're happy to greenlight.

[Danbi58]

@JiwaniZakir

Both comments get at the same architectural tension and it's the right one to surface before this lands in the schema.

You're correct that a purely declarative block with no enforcement hook is just documentation, and documentation didn't stop any of the cited incidents. The spec can't enforce runtime behaviour by itself; it can only define the interface that a compliant runtime must implement.

The model I have in mind is closer to your second framing: financial_governance declares a policy contract, and the runtime (or a companion policy-enforcement layer) is responsible for calling the declared firewall synchronously before any financial tool dispatch similar to pre-execution tool guards. The spec's job is to standardise what that contract looks like so any compliant runtime can implement it consistently, rather than each team wiring their own ad hoc controls.

The event_schema additions I proposed earlier (the payment_required / payment_approval / payment_receipt objects) are specifically intended to define that interface boundary, typed events that the enforcement hook emits and receives, making the round-trip auditable and portable across runtimes.

Worth noting in the spec text explicitly: "a financial_governance block with no compliant enforcement layer is advisory only." That sets the right expectation and puts the onus on runtime implementors to close the loop.

[Danbi58]

@JiwaniZakir to close the loop on the enforcement question: the reference implementation does run the control path synchronously.

The rule engine evaluates before any downstream cost is incurred, Gate 2 policy checks (spending caps, category allowlist, cumulative spend) happen before Stripe is called and the LLM enrichment is explicitly async and non-blocking so it never creates a latency dependency on the control path.

I agree that a declaration that nothing reads is documentation. The intent here is that the spec defines the interface contract, and a compliant runtime calls it synchronously before any financial tool dispatch.

Happy to document that expectation explicitly in the spec text.

[JiwaniZakir]

The financial_governance block makes sense as a first-class spec concern separate from compliance — the distinction between identity/audit controls and runtime spending controls is real and worth encoding explicitly. One thing worth specifying early: whether enforcement is declarative (the runtime reads the block and enforces it) or advisory (the block documents controls that an external firewall owns), since mixing those models across implementations will cause interop headaches. The approval_threshold field in particular needs a clear owner — is it the agent runtime, the financial firewall, or the orchestrator?

[Danbi58]

@JiwaniZakir

The financial_governance block documents the policy contract; the financial firewall owns enforcement. The agent runtime's only responsibility is to call the firewall synchronously before dispatching any financial action, it doesn't interpret or enforce the fields itself.

This means the block is closer to a service binding than a policy engine. The runtime says "this agent has a firewall declared, here is the endpoint contract, call it before any payment tool fires." The firewall reads the policy, evaluates the transaction, and returns SAFE / FLAGGED / BLOCKED. The spec never becomes an enforcement engine.

On approval_threshold specifically: the firewall owns it. The field in the spec is a declaration of intent that the firewall enforces, the agent runtime and orchestrator have no visibility into whether a transaction exceeded the threshold, only into the firewall's response. This keeps the approval logic out of the orchestration layer entirely, which is important for auditability, if the orchestrator could override the threshold, the audit trail becomes unreliable.

The interop risk you're flagging is real if implementations split between the two models. Worth adding a conformance note to the spec text: a compliant runtime calls the declared firewall synchronously and treats its response as authoritative. It does not re-implement or override the enforcement logic locally.

[JiwaniZakir]

The proposed financial_governance block addresses a real gap — the compliance block describing risk tier without any runtime enforcement mechanism is essentially just documentation. A concrete schema question worth resolving early: should approval_threshold be an absolute value or a percentage of spend_limit, since a flat $20 threshold behaves very differently for a $50-cap agent vs. a $5,000-cap agent? Also worth specifying whether the firewall field references a named integration (e.g. stripe-radar, custom) or a webhook endpoint, since that determines how tooling validates the field at parse time rather than only at runtime.

[valkurai]

@JiwaniZakir good questions on both.

On approval_threshold, absolute cents is the right choice over a percentage. A percentage threshold creates a spec-time dependency between two fields that are set independently and may change at different times. If the spend_limit is updated, the effective threshold silently changes too, which makes the audit trail harder to reason about. An auditor looking at a historical transaction needs to know the threshold that applied, not reconstruct it from a ratio. Absolute cents keeps the governance intent explicit and independently auditable. The difference in behaviour across different cap sizes is by design, operators set the threshold that matches their risk tolerance for their specific agent.

On the firewall field, it should reference a named integration identifier, not an endpoint. The endpoint is runtime config and does not belong in the spec (as we established earlier in the thread). A named identifier like valkurai or stripe-radar allows tooling to validate the field at parse time against a known registry of compliant implementations and keeps the spec agnostic about transport. How the runtime resolves the named identifier to an endpoint is an implementation concern, not a spec concern in my view.

[JiwaniZakir]

The declarative-vs-enforcement gap is the right concern, but I'd push back slightly on framing it as either/or — the spec block still has value as a machine-readable contract that enforcement layers (firewalls, orchestrators, CI gates) can consume, rather than requiring each implementation to invent its own schema. The real requirement is that compliant runtimes must reject or escalate transactions that violate the declared limits, which should be stated normatively in the spec itself. Without that "MUST enforce" language and a defined behavior for when the firewall_endpoint is unreachable, the block is just documentation, exactly as described.