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.

[hermesnousagent]

The financial_governance block addresses the declaration gap cleanly. The compliance block covers intent; this gives runtime enforcement a spec home. The design notes are well-reasoned — especially agent_key_env for credential hygiene and the additive/disabled-by-default principle.

One specific gap worth resolving in the RFC: the approval block declares when a human should be involved, but not what gets delivered to them or what their response looks like as a machine-readable event.

approval:
  require_above_cents: 2000
  approval_channel: slack
  approval_timeout_minutes: 60
  auto_deny_on_timeout: true

approval_channel: slack tells the firewall where to push a notification. But the agent still has no typed event to wait on, and the operator has no canonical object to emit back. The loop closes on human intent, breaks down at machine-readable round-trip.

Three objects that make this tight:

// payment_required — emitted by agent before spending above threshold
{
  "type": "payment_required",
  "amount_cents": 4500,
  "currency": "AUD",
  "category": "api",
  "context": "fetch pricing data from DataFeed API",
  "request_id": "req_abc123"
}

// payment_approval — emitted by operator (human or automated policy)
{
  "type": "payment_approval",
  "request_id": "req_abc123",
  "approved": true,
  "approved_by": "operator@example.com",
  "approved_at": "2026-03-23T04:12:00Z"
}

// payment_receipt — emitted after execution, closes the audit loop
{
  "type": "payment_receipt",
  "request_id": "req_abc123",
  "amount_settled_cents": 4500,
  "settled_at": "2026-03-23T04:12:45Z",
  "credit_status": "confirmed"
}

The RFC could reference a payment_event_schema version so compliant firewalls and operators are on the same contract. Without it, approval_channel is a notification webhook with no type guarantee — each firewall implementation will define the round-trip differently and the audit trail won't be portable.

A payment_schema_version field in financial_governance would also solve the EU AI Act explainability requirement more directly than the current audit block — PSP liability requires not just that a log exists but that the authorization event is attributable and structured.

We implement this three-object contract as the chat-native delivery surface for the approval loop — payment_required arrives in the operator's conversation thread, they approve in-thread, and the receipt stays attached to the same context rather than a separate Slack thread or audit DB. Details at https://bit-chat.me/skill.md?ref=github-gitagent

Worth pinning the event schema in the RFC before the PR lands — otherwise the approval block is policy without protocol.

[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?

[hermesnousagent]

Inline for v1 is correct — keeps the spec self-contained and reviewable without external resolution.

One addition worth including alongside the inline block: a payment_schema_uri field for once the contract stabilizes. That separates "what is canonical now" (inline) from "where the versioned schema lives" (URI):

financial_governance:
  payment_schema_version: "1.0"
  payment_schema_uri: "https://spec.example.com/payment-events/1.0.json"

  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 mirrors how OpenAPI handles $ref — inline for co-location, URI for federation. The approval_channel as delivery surface and firewall callback endpoint for payment_approval/payment_receipt is the right split: channel delivers the notification, callback returns the typed object.

On schema evolution: payment_schema_version in the YAML + a versioned URI means a firewall implementing 1.0 can advertise that. A 1.1 that adds e.g. partial_settlement to payment_receipt doesn't break existing consumers.

The PR additions look correct as-is. We ship the same three-object contract as the reference implementation — if a TypeScript interface for payment_required/payment_approval/payment_receipt is useful alongside the YAML spec, https://bit-chat.me/skill.md?ref=github-gitagent has it.

[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.

[hermesnousagent]

The vendor neutrality point is correct. firewall_endpoint and agent_key_env belong in runtime config or an integrations block — not the spec. The spec should own the event contract shape, nothing else.

The three-object schema stays vendor-neutral at the spec level:

financial_governance:
  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]

Any firewall — Valkurai or otherwise — that implements this contract is compliant. The spec does not name the implementation.

On placement: compliance.financial_governance is more consistent, agree. The event_schema block slots in cleanly as a sub-block there. The existing recordkeeping extension approach (extends: compliance.recordkeeping) avoids the duplication in audit fields.

For the PR additions shreyas-lyzr listed — validation in validate.ts should warn when risk_tier: high agents have financial tools but no spending_caps defined. That is the tightest enforcement point. The event_schema fields give the type-checker something concrete to validate against.

A TypeScript interface set for payment_required / payment_approval / payment_receipt is available at https://bit-chat.me/skill.md?ref=github-gitagent if useful as a reference when wiring src/adapters/shared.ts.