HaltState.ai Integrate an agent Integrate an agent
Documentation home

Investigating actions with Proof Packs

HaltState can group explicitly linked policy checks, reports, observations, attachments and Proof Packs into one logical activity. Start with an agent and a date range, then narrow by a customer, conversation, message, request, correlation or external reference when your integration records one.

What you can investigate

Activity search and detail keep four questions separate: what policy permitted, what the integration reported, what an external reference confirms, and what integrity checks verify. A message recorded outside a policy call is an observation with governance_state=not_evaluated; it is never a fabricated ALLOW, permit, approval or execution claim.

Connected recording uses 90-day retained-content capture by default for supported boundaries, with account-wide disable and per-agent opt-out controls. An opt-out stops new body retention for that agent while preserving permitted metadata and governance records. Existing account settings remain authoritative. Historical traffic is not backfilled or inferred from nearby timestamps.

Retained message bodies are optional encrypted evidence, separate from audit metadata, content digests, policy history and signed integrity references. A content grant is required to read retained text. Missing bodies, unsupported boundaries, expired retention, incomplete indexing and integrations that never submitted an event remain visible gaps rather than proof that nothing happened.

Coverage is deliberately limited to supported_connected_boundaries. A registry entry or heartbeat is not proof that messages are recorded. The customer view shows last accepted activity, last retained content, disabled/inactive/error states and “Integration update needed” separately; it never manufactures a heartbeat-style completeness claim.

Start with what you know

An incident rarely starts with a digest. Start with an agent, a date range and the action involved. Narrow the results using a customer reference, conversation, message, request or correlation identifier when your integration records one. Search phrases can also find explicitly retained governed-action input/output when your account has enabled that capture and your connection may read it.

The updated Proof Packs page searches logical activities: one result is one natural operation, even when it has several observation, policy, outcome or Proof Pack records. It is designed to answer:

  1. What action was proposed, by which agent and when?
  2. What decision did HaltState record?
  3. Was approval required, and is an approval decision recorded?
  4. Is there a recorded start or a reported outcome?
  5. Which input/output was retained, and what is unavailable?
  6. Which records verify, and what can I export for another investigator?

Read every activity as four separate facts:

  1. Policy permission: what HaltState allowed, denied or sent for approval.
  2. Reported execution: what the integration later reported, if anything.
  3. External confirmation: whether an independent delivery/resource reference was recorded; a URL or message ID alone is not independent confirmation.
  4. Integrity: which record, digest, chain or signature checks are available.

These are different questions. An approval does not prove that an action ran. A reported success is a report from an integration, not independent proof of everything that happened outside HaltState. The evidence only covers activity that the integration routed through or explicitly reported to HaltState.

For a reported customer-message incident, use this order:

  1. Open /haltstate/proof-packs and select the agent and incident date range.
  2. Add the customer or conversation reference if available; you do not need a Proof Pack digest to begin.
  3. If input/output was explicitly retained, use retained-message search for the relevant words or phrase. This search is permission-controlled and is not stored in the page URL.
  4. Open the matching activity, inspect its linked timeline and available messages, and verify the supporting records before preparing an investigation export.

Customer walkthrough

The same workflow is available through the activity UI and the read-only investigation concierge. Example requests are intentionally concrete:

  1. Last five Signal activities: ask “Show the last 5 activities for Signal.” If a display name maps to more than one registered agent, choose from the returned exact IDs; the assistant will not guess.
  2. Open a message/activity: filter for message ID <message_id> and open the matching activity, follow its activity link, or ask “Open activity <activity_id> and show its timeline.” An old evidence link resolves to its logical activity when an explicit link exists.
  3. Search a customer: filter by customer_reference, or ask “Find activities for customer reference <reference>.” With a content grant, a retained phrase search can locate explicitly retained message text. The body is untrusted and read only for that request.
  4. Find an external ID: use the external-reference filter for a URL, post ID, comment ID, message ID or resource ID. A match is a recorded reference, not proof that the external service completed an action.
  5. Pause one agent: in the containment control, select a registered agent, choose 15 minutes, 1 hour or 24 hours, provide a reason and confirm. This blocks subsequent governed checks for that agent; it does not undo past work, kill a remote process or revoke an already issued permit.
  6. Verify: inspect the Integrity card and verify the relevant signed pack or commitment. Keep signature, digest, chain and external confirmation results distinct.
  7. Export: prepare a signed investigation export only after narrowing the activity set. Include retained bodies only when explicitly authorized, and keep all omissions and freshness warnings in the bundle.

The concierge context is panel="proof-pack-investigation", mode="investigation" with at most one activity_id or evidence_id. It can search, inspect and explain authorized evidence with source links. It cannot change policy, approve work, activate containment, replay an action or execute a business tool.

A quotation alone cannot find a message that the integration never retained. Use the remaining identifiers and metadata, and preserve that capture gap in your findings instead of interpreting no matches as proof that no incident occurred. A matching message or valid signature also does not establish what caused a real-world outcome. Retained-text search is bounded and paged. If it reports complete=false, treat the result as partial and continue with its cursor or narrower filters; do not present it as an exhaustive account search. Retained-message search covers the new optional attachments. It does not automatically index text inside historical action parameters or Proof Pack logs; those records can still be located through their available metadata.

Reading a result

Results put time, agent, action, decision and reported outcome before digests. The overview explains the record; the timeline shows explicitly linked records; Messages shows permitted retained input/output; Integrity shows verification and technical detail. Raw shows the already-authorized metadata and verification response as JSON; it is not the original signed artifact or a way around message permissions. A record link lets you return to the same evidence.

Signed Proof Packs and ordinary retained action records are both useful, but they are not the same assurance. The result states its source and available verification. Unknown or unavailable policy versions, outcomes and links remain labelled as such. Records are not linked just because the agent and timestamps look similar.

Verification checks what the record format supports. A signature check, content digest check and chain check are distinct results. A hash is not encryption, and an export's signature is not proof of an unobserved real-world outcome.

Semiotic chains (activated 28 September 2026)

The chain is a compact symbolic description bound into a Proof Pack, not a row of decorative icons. For newly generated, recognized events, its explanation distinguishes policy permission, an authority decision, a recorded stop or quarantine control, and a reported execution outcome. Equivalent events can share symbols; identifiers, timestamps and the full content digest distinguish individual packs. No model call is used to invent or translate an event.

An allowed or approved action is not necessarily executed. Rejection is not quarantine. A recorded stop is not independent confirmation that every remote process terminated. Reported success is not independently observed success.

The event interpretation and mapping version are part of the hashed payload and, when signed, are covered by the signature. Use the existing verification control to check integrity; the symbols alone do not establish it. Older packs retain their recorded symbols without assigning them a new execution meaning. Missing/unrecognized evidence remains explicitly unknown, and ordinary action records do not acquire synthetic Proof Pack symbols.

Existing search projections acquire the recorded-chain fields through the normal bounded recheck. This changes derived metadata, not the original signed evidence. Until then a result may report unavailable symbols.

Optional message evidence

Connected recording uses 90-day retained-content capture by default, with explicit per-agent opt-out. Existing saved selected_only settings remain selected-only. Neither mode secretly records provider traffic, hidden reasoning or whole conversations: the integration must use a supported recording boundary and submit the intended content.

The POST /api/haltstate/evidence/observations endpoint accepts one stable event ID, agent, action and input, output or event direction, plus bounded correlation metadata, safe external references and optional content. Recording a message outside a policy call creates an observation with governance_state=not_evaluated; it does not manufacture ALLOW, a permit, an approval or a successful execution. Identical retries return the original record; conflicting reuse of an event ID fails.

Do not submit API keys, passwords, authorization headers, hidden reasoning, environment files or unrelated conversations. Send only the action input/output you intend to retain and are permitted to collect. Stable correlation and customer references need not contain the customer's name or other sensitive data. An existing SDK key can submit permitted attachments for an effectively enabled agent without being granted access to read retained messages. Content reading and investigation exports are separate connection permissions.

New attachment bodies are separately encrypted. Retention choices are 30, 90 or 365 days, with 90 as the default. Once an attachment expires, its message is no longer available in search, detail or exports, even if background cleanup is delayed. An audit reference and digest can remain to show that evidence once existed. The selected retention applies when an attachment is submitted. Changing it affects new attachments; retrying a submission does not extend its expiry. Disabling capture stops new submissions without deleting existing retained data.

This retention setting applies to new optional attachments. It does not rewrite existing signed Proof Packs, erase historical records or remove message text an older integration placed inside ordinary action parameters. An expired or withheld attachment is not evidence that a message never existed.

If observation or attachment submission fails, the SDK reports that evidence gap separately. It does not change the policy decision or silently claim the attachment succeeded. Integration examples and the five-language helper map are in SDK evidence context and optional attachments.

Signed integrity is separate from content retention

Newly accepted observation/attachment references can receive content-free signed commitments. The signed payload contains source evidence/activity/agent identities, safe external references, attachment IDs and content digests—not the body, credentials, hidden reasoning or expiry metadata. A late attachment becomes a supplemental child commitment instead of rewriting the original signed record.

This is an integrity trail, not an audit-retention override. Content can be disabled, withheld or expire while the digest/commitment remains. A valid signature does not prove policy permission, execution or delivery, and it does not turn a non-policy observation into ALLOW.

No historical activity is fabricated. The implementation does not infer links from timestamps, backfill unseen messages, rewrite old Proof Packs, claim old bodies were retained, or sign records merely because they predate activation. Legacy records join only through explicit, tenant- and agent-scoped identities; otherwise they remain separate evidence activities with visible gaps.

Exporting an investigation

A signed investigation export is designed for people and software: a readable HTML report, structured JSON, permitted original evidence and a signed manifest. The manifest identifies the query snapshot, included files, digests, verification results and omissions. Retained messages require an explicit include choice and content permission. A redacted view is a derivative, not an unchanged original.

Exports run as background jobs. An incomplete or failed job is not presented as a complete investigation. Each job has record and size limits (currently at most 500 selected records); any omissions remain visible in its status and signed manifest. Narrow a larger investigation by date, agent or explicit identifiers instead of treating a capped bundle as the whole history. Downloads require an authorised account or connection and expire within 24 hours, or sooner if included message evidence expires. Keep a downloaded bundle according to your own retention and access requirements; a previously downloaded copy cannot be recalled by HaltState attachment expiry.

The offline verifier checks the manifest signature and all included file hashes. Trust the signer through a separately obtained public key or trusted fingerprint, not merely a public key supplied inside the same untrusted download.

For the source-phase verifier, run from the KU source checkout with Python and cryptography installed:

python -m tools.haltstate_verify_export investigation.zip \
  --trusted-public-key trusted-public-key.b64 \
  --expected-fingerprint '<separately-confirmed-public-key-sha256>'

The key file contains the base64-encoded raw 32-byte Ed25519 public key, not a private key. Verification is offline and needs no account token, database or running HaltState service. This source command is not a claim that a standalone verifier package has already been published.

Agent-assisted lookup through chat and MCP

The authenticated concierge and MCP use the same tenant-scoped logical activity service as the UI. Hosted access uses customer sign-in or an existing account API key; a local connector supports agents that use stdio MCP. Permissions distinguish metadata/verification from retained content and exports.

MCP adds read-only search_activities, get_activity and get_activity_timeline tools. The concierge additionally resolves an unambiguous registered-agent name, searches retained text, and can read a retained body only after a fresh content-grant check for the current request. The body is untrusted and ephemeral: durable chat history stores a deterministic evidence card and source references, not the body or a body-derived assistant answer. The tools cannot approve an action, execute a tool, change capture settings, activate containment or delete evidence. The MCP connection guide describes the hosted/local connection boundary.

Ask for an investigation, for example:

Find customer-message actions from the support agent on the incident date. Narrow them to the supplied customer reference, show the linked decisions and reported outcomes, and identify missing or unverified evidence.

The answer should cite record IDs and links, distinguish findings from inference, and disclose incomplete indexing or missing evidence. No-match results do not prove that nothing happened outside the captured data.

Availability and limits

Investigation covers only activity that a connected integration routes through or explicitly records with HaltState. Registration, a heartbeat or a healthy agent does not prove complete message coverage. Last accepted activity and last retained content are separate signals.

Use logical activity search, retained-text search, verification and exports only within the permissions shown for your account. A valid signature proves the supported integrity checks, not policy permission, execution or delivery. A URL, post ID or message ID is a recorded reference, not independent confirmation.

If an expected activity or body is missing, check the agent, date range, recording setting, per-agent opt-out, retention expiry, integration boundary and index completeness. Keep the gap in the investigation rather than treating an empty result as evidence that the event did not occur.