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 Proof Pack evidence. Signed records carry their own integrity metadata and verification material.

What this documentation covers

These docs cover replay safety, 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 published baselines remain separate from the replay-safe repository source candidates. Java 17 source builds and focused replay tests pass locally, but registry publication is not externally verified. Rust is first-party preview source with no verified remote package or executable verification on this host because a Rust toolchain was unavailable.

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: signed evidence records with a full-content digest, Ed25519 signature, tenant-scoped verification, and hash-chain validation. Authenticated verification reports the assurance available for each record.

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.