Introduction

What HaltState controls

HaltState governs actions rather than conversations. An agent can still reason, draft, summarize, and recommend, but a business action such as refund.create, payment.authorize, customer.pii.export, database.write, or customer.email.send must pass through the policy engine before it reaches a system of record. This gives teams a deterministic control point for high-risk behavior without pretending that prompts alone can enforce production authority.

Core loop

1. The agent prepares an action and safe context.
2. The SDK or service calls the HaltState guard endpoint with an idempotency key.
3. The policy engine returns ALLOW, APPROVAL_REQUIRED, or DENY.
4. The worker executes only allowed or later-approved actions.
5. The worker reports the final outcome and HaltState records hash-verified evidence for a Proof Pack.

What this documentation covers

These docs cover the guard pattern, idempotency keys, approval lifecycle, SDK usage, environment variables, exception handling, Proof Pack schema, ops APIs, and the real retail refund agent example that powers the public live board. Python, TypeScript, and Go external installs are verified. Java preview metadata is verified on JitPack, while Maven Central is not published. Rust is first-party preview source with no verified remote package yet.

Key concepts

• The enforcement loop: the action wrapper asks HaltState for authority before the side effect touches a target system.
• Policies: granular allow, deny, or approval-required rules for actions such as refunds, payments, PII exports, production writes, and customer messages.
• The guard pattern: SDK control flow that keeps approval, denial, retry, and report behavior consistent across scripts and services.
• Proof Packs: hash-verified evidence records that preserve decisions, reports, integrity hashes, and redaction status for audit and incident response.

What changed in this public direction

The public story now centers on governed business actions, not generic agent observability. The retail refund agent is the reference: it attempts refund.create, HaltState evaluates policy first, the worker executes only allowed or later-approved actions, and public evidence is sanitized before it reaches the live board.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.