Overview
Decision Horizon is an interceptor on an AI agent's tool path. Every consequential action the agent takes produces a signed Agent Decision Record: who sponsored it, what authority it held at that instant, what it had read, what it could have read and never did, which policy rule fired, exactly what an approver was shown, and what changed.
An intent record is signed before the tool call runs and an outcome record after it. Records are Ed25519-signed and hash-chained, one chain per session, and the whole chain verifies offline against a public key you pin yourself. The public key is never written into the chain.
It runs in one of three places: the MCP proxy (dh proxy, between an agent and an MCP tool server; the strongest, because it executes the call itself), the gateway sidecar (dh gateway, in front of an OpenAI-compatible model endpoint), or the in-process SDK (Python or TypeScript; the weakest, and the records say so).
Quickstart
Install
# Python package: CLI, proxy, gateway, Python SDK, verifier
pip install decision-horizon
# HTTP transports (dh proxy --listen / --downstream-url, dh gateway)
pip install 'decision-horizon[http]'
# TypeScript SDK for Node agents (Node 18 or later)
npm install @decision-horizon/sdk
Compiled wheels cover Linux, macOS and Windows on CPython 3.10 to 3.12. Check with dh --version.
Record and verify a first session
This uses the reference MCP filesystem server (needs Node for npx).
dh keygen # ~/.dh/signer.key (0600) + signer.key.pub <- pin the .pub
dh init # writes dh.toml; edit [identity], [authority] and [adapter].accessible_root
dh proxy -c dh.toml -- npx -y @modelcontextprotocol/server-filesystem /path/to/repo
Point your MCP client at the dh proxy … command instead of the server. It sees the same tool list, byte for byte. accessible_root is optional: without it the proxy asks the downstream server, or the record abstains (see MCP proxy).
When the session ends:
dh verify ~/.dh/records/<session>.jsonl --pub ~/.dh/signer.key.pub # exit 0 only if nothing is flagged
dh replay ~/.dh/records/<session>.jsonl --html replay.html --pub ~/.dh/signer.key.pub
dh query ~/.dh/records/<session>.jsonl --session-horizon '*.env*' # every action after a credential was read
dh replay renders a chain as sentences or an HTML report; dh query answers audit questions across a chain.
kid (key id) is a label you choose. Give the same value to dh keygen --kid, [signing].kid and dh verify --kid. All three default to signer-1.Concepts
What a record contains
Records use schema adr/0.2. Each record carries these blocks:
| Block | What it holds |
|---|---|
principal_chain | Human sponsor (idp, subject, session), then agent (id, version), then sub-agents, with delegation scope deltas. |
authority_t0 | Grants, what was explicitly not granted, expiry and purpose hash, as they were at that instant. |
horizon | What the agent had observed (content hashes only), deterministic by-value findings at confidence 1.0 (used_by_value, used_by_window, not_used_by_value), the heuristic retrieved_not_used at confidence 0.5, accessible_not_retrieved with its accessible_basis, read_earlier_in_session, and abstain, where the record says "unknown" rather than guessing. |
action | Tool, arguments hash, targets (every path-like argument, source and destination), pre/post state hash, state_moved_since_horizon (true, false, or null for never observed). |
policy | Engine, rule id, verdict (allow, soft_deny, hard_deny). For a checkpoint: who decided (policy:auto-deny, env:DH_APPROVE, or a named approver), the hash of exactly what they were shown, and a redacted view. Arguments are never stored, only hashed. |
outcome | Status (success, error, blocked; at the gateway reported, executed, unreported), error, affected refs, result hash. Reversibility is never asserted. |
witness | Optional. One entry per configured witness: an attestation of an earlier head, or an "unreachable" statement. Inside the signed body. |
coverage | On intent and terminal records: what this insertion point sees and does not see. |
sig | Ed25519 over the canonical body, and the kid. The previous record's hash is inside the signed body. |
Intent, outcome and terminal records
- An intent record is written and signed before a consequential tool call runs.
- An outcome record follows it once the call has finished (or was blocked) and names the intent it closes.
- A terminal record closes the session. It states how many records came before it and the head it bound. A chain without one is either still running or was truncated, and the verifier treats it that way.
Hash chain and signing
Each record's prev_hash is the hash of the record before it, and it sits inside the signed body. The hash of the last record is the chain's head. Reordering, dropping, inserting or editing a record breaks either a signature or the chain.
Records are stored as one .jsonl file per session in [store].dir (default ~/.dh/records), fsync'd per record, with a .meta.json holding the head hash. Record files are 0600 in a 0700 directory.
What the verifier flags
It catches reordering, forged or edited records, swapped prev_hash pointers, spliced or duplicated records, tail truncation, a record after the terminal, and an intent with no outcome. Errors are reported as [index, code] pairs:
| Code | Meaning |
|---|---|
malformed_record | A field the verifier reads is missing or has the wrong type. |
malformed_ts | ts is not a strict ISO-8601 timestamp. |
schema_mismatch | The record's schema is not the expected one. |
kid_mismatch | The record's key id differs from the expected kid. |
body_hash_mismatch | The body does not hash to the stated body_hash. |
bad_signature | The signature does not verify under the pinned public key. |
chain_break | prev_hash does not match the previous record's hash. |
seq_gap | seq is not the record's position (it must be an integer, never true or 2.0). |
session_mismatch | The record names a different session than expected. |
terminal_mismatch | The terminal record's own count or bound head disagrees with the chain. |
record_after_terminal | Records appear after the terminal record. |
unterminated_chain_possible_truncation | No terminal record, and the session was not declared open. |
dangling_intent_no_outcome | An intent with no outcome: the action may have executed without an outcome record. |
head_mismatch | The chain's head differs from the expected head. |
empty_chain | An empty file is not a verified session. |
meta_contradicts_chain | The store meta beside the chain says more than the chain shows (more records, a closed session without its terminal record, or a head that is not the hash of the record it counts to). |
When a session is declared open and has no terminal record, the verifier issues the warning session_open_no_terminal_record instead of an error. ok is true, and dh verify exits 0, only when nothing is flagged.
The coverage statement
A chain with no record of a call is evidence only that the call did not pass this insertion point. So every intent record and the terminal record carry a signed coverage block: insertion_point (mcp_proxy, gateway or in_process_sdk), transports, tool_surface (count and hash), signer, key_at_rest, witness, and uncovered, a stated list of blind spots such as "tools reachable by the agent outside this proxy are not recorded".
dh verify prints the statement. A chain written before this field existed is reported as "not stated", never as covered. The list is what the code knows about itself; a blind spot nobody has named is not in it.
MCP proxy
dh proxy wraps one MCP tool server. The agent sees the downstream's tool list unchanged; every consequential call becomes a signed record.
stdio and HTTP
# stdio on both sides
dh proxy -c dh.toml -- npx -y @modelcontextprotocol/server-filesystem /repo
# the agent connects over HTTP; the tool server is a local stdio process
dh proxy -c dh.toml --listen 127.0.0.1:8787 -- npx -y @modelcontextprotocol/server-filesystem /repo
# -> point the agent's MCP config at http://127.0.0.1:8787/mcp
# the tool server is hosted; govern it without touching it
dh proxy -c dh.toml --downstream-url https://tools.example.com/mcp
# both
dh proxy -c dh.toml --listen 0.0.0.0:8787 --downstream-url https://tools.example.com/mcp
Options: -c, --config (default dh.toml), --listen HOST:PORT, --mount (default /mcp), --downstream-url URL. HTTP needs pip install 'decision-horizon[http]'.
One proxy process is one record chain: run one per agent session. SIGTERM writes the terminal record before the process exits, on both transports.
[adapter].downstream_headers. The record cannot see a call that never reached the proxy.[adapter]
downstream_headers = { Authorization = "Bearer $DH_DOWNSTREAM_TOKEN" } # expanded from the environment at load
An unset variable is a configuration error, never a literal on the wire. Configured header values are never logged or recorded.
Configuration
dh init writes an annotated dh.toml with these tables: [identity] (sponsor and agent), [authority] (grants, not_granted), [store], [signing], [witness], [gateway], [approval], [adapter] (accessible_root, ref_args, sensitive_refs, cross_session_taint, downstream_headers, resolve_paths) and [policy].
The accessible set
accessible_not_retrieved lists what the agent could have read and did not. The set comes from [adapter].accessible_root when set (configured), else from the downstream's own list_allowed_directories tool (a claim taken on faith, listed at confidence 0.7). Otherwise accessible_basis is null and the record abstains rather than claiming "nothing else". The agent's client roots can only narrow the set, never define it. The walk stops at 20,000 entries.
With roots known, paths are resolved (realpath, ..) before the horizon, policy or record see them, so reading .env through a symlink is recorded as a read of .env. MCP resources and prompts are forwarded and treated as reads.
Coding agents
Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI and other coding agents run built-in tools (a shell, file edits, web fetch) that never pass through MCP. Decision Horizon reaches them through each agent's own hook system: before a tool runs it records what the agent had read, applies your policy and Ostiary, signs an intent record and answers allow, deny or ask in that agent's format. After the tool runs it signs the outcome.
Install
pip install decision-horizon
dh hooks install claude-code # this project (.claude/settings.json)
dh hooks install cursor copilot --user # every project of this user
dh hooks list # supported agents and where their hooks go
dh hooks uninstall claude-code # takes out only Decision Horizon's entries
The first install creates ~/.dh/hooks.toml and a signing key if you have none. A project's own dh.toml takes precedence. With DH_API_KEY set, sessions upload to your account and show up in the Console.
Supported agents
| Agent | Where the hook goes | Can ask the user |
|---|---|---|
| Claude Code | .claude/settings.json | Yes |
| Cursor | .cursor/hooks.json (fails closed) | No, it denies |
| GitHub Copilot: CLI, cloud agent, VS Code | .github/hooks/decision-horizon.json | Yes |
| OpenAI Codex CLI | .codex/hooks.json; turn on [features] hooks and approve once in /hooks | No |
| Gemini CLI | .gemini/settings.json | No |
| Windsurf | .devin/hooks.json | No |
| Cline | .clinerules/hooks/ scripts | No |
| Kiro | .kiro/hooks/decision-horizon.json | No |
| Factory Droid, Continue CLI, Augment | their settings files | Factory and Continue |
| OpenCode, Amp | a small plugin that calls dh hook | No |
What it does in a session
- One signed chain per agent session, for example
claude-code-<session id>. Files inside the project are recorded as./path. - Ordinary work is allowed and recorded. Reads fold into the horizon, so a later action is judged against what the agent had seen.
- A value read from a secret file and then sent anywhere is paused: Claude Code and Copilot show their own approval prompt; the other agents deny it. A call the user declines never reports back and is listed
unreportedwhen the session ends. - Deleting the records, reading the signing key or editing the agent's own hook configuration is denied, so the agent can't switch its governance off.
- If Decision Horizon itself fails, a consequential call is denied (
[hooks] on_error = "allow"lets it through); reads always pass. - Agents without a session-end event (Windsurf, OpenCode, Amp):
dh hooks close-idle --older-than 12hsigns the closing record.
Claude Agent SDK
from claude_agent_sdk import ClaudeAgentOptions, query
from decision_horizon.claude_agent import DecisionHorizon
dh = DecisionHorizon()
async for m in query(prompt="...", options=ClaudeAgentOptions(hooks=dh.hooks())): ...
dh.close()
import { query } from "@anthropic-ai/claude-agent-sdk";
import { DecisionHorizonHooks } from "@decision-horizon/sdk";
const dh = new DecisionHorizonHooks({ key: "~/.dh/signer.key", kid: "signer-1" });
for await (const m of query({ prompt: "...", options: { hooks: dh.hooks() } })) { /* ... */ }
await dh.close();
The SDK has no interactive prompt, so a paused call goes to your configured approver or is denied.
Limits
- A hook runs beside the agent, from configuration its user controls. Whoever controls the machine can switch it off, and calls made while it is off aren't recorded. Every record names its insertion point,
agent_hook:<agent>. - Arguments and results are as the agent reported them. A shell command's targets are the paths it spells out.
- Each hook call is a short process, about 0.15 seconds.
- Codex runs hooks only for its shell,
apply_patchand MCP tools. Hook formats belong to each agent and can change;dh hooks listshows what this version writes.
Gateway sidecar
An agent that runs its own tool loop against an OpenAI-compatible /v1/chat/completions endpoint has no tool server to wrap. dh gateway sits between the agent and the model instead. The agent only changes its base_url.
pip install 'decision-horizon[http]'
dh gateway -c dh.toml --listen 127.0.0.1:8790 --upstream-url https://api.openai.com/v1 --idle-s 600
# -> OpenAI(base_url="http://127.0.0.1:8790/v1", api_key=…)
Requests and headers pass through; the Authorization value is never logged or recorded.
How it reads the loop
- Reads are the tool results the agent reports (
role: "tool"messages). Paths named in prose are not inferred as reads. - Intents are the model's requested
tool_calls. Policy runs before the response reaches the agent; a denied call is replaced by assistant text naming the rule and verdict, never the values. - Outcomes are
reportedonce the agent sends the matching tool message, orunreportedat session close. - Streaming: tool-call deltas are held until the choice finishes, then policy runs. Content deltas pass through.
- Sessions are keyed by the
X-DH-Sessionheader, else by a hash of the first system and user message, and close on idle, onX-DH-Session-End: true, or on SIGTERM. - Request bodies over 4 MB are refused with 413 (
[gateway] max_body_bytes).
Execution receipts
A runner, the code that executes tool calls, can sign a receipt per call with its own key. Pin its public half in the gateway:
dh keygen --out runner.key --kid runner-1 # on the agent host
# dh.toml (gateway):
# [gateway] runner_pubs = [{kid = "runner-1", pub = "/srv/dh/runner.key.pub"}]
from decision_horizon.runner import Runner
runner = Runner("runner.key", "runner-1")
for call in message.tool_calls:
name, args = call.function.name, json.loads(call.function.arguments)
result, receipt = runner.run(call.id, name, args, lambda: tools[name](**args))
messages.append(runner.tool_message(call.id, name, args, result)) # role: tool + metadata.dh_receipt
A receipt that verifies and matches the intent makes the outcome executed; one that does not leaves it reported with the reason. A receipt proves the runner key holder attested to the call, not that it ran.
accessible_basis is always null there).Python SDK
When there is no MCP server and no gateway in the way, wrap the tool functions directly. The SDK ships in the same decision-horizon package and uses the same policy, key and store as the proxy.
from decision_horizon.sdk import Session
with Session.from_config("dh.toml") as s:
@s.read("read_file", ref_arg="path")
def read_file(path): ...
@s.govern("write_file", ref_args=["path"], state_reader=lambda p: open(p).read())
def write_file(path, content): ...
write_file("pub/notes.txt", "...") # raises PolicyBlocked on a denial or an unapproved checkpoint
This works with LangChain, OpenAI Agents, CrewAI or your own loop: wrap the tool functions and you get the same chain. If the agent receives content some other way, call observe(ref, content, …) on the interceptor so it enters the horizon.
insertion_point: in_process_sdk). The hook lives inside the agent process, so a compromised agent can call the function directly and leave no record. Use the proxy wherever one can sit.TypeScript SDK
@decision-horizon/sdk is an in-process hook for Node agents (Node 18 or later). It writes the same adr/0.2 records, and dh verify accepts them.
npm install @decision-horizon/sdk
npx @decision-horizon/sdk keygen --out ~/.dh/signer.key --kid signer-1 # same key format as dh keygen
import { Session, PolicyBlocked } from "@decision-horizon/sdk";
import { readFile, writeFile } from "node:fs/promises";
const s = new Session({
key: "~/.dh/signer.key", kid: "signer-1", storeDir: "~/.dh/records",
sponsor: { idp: "okta", sub: "u_hans", session: "s1" },
agent: { id: "support-agent", version: "3" },
authority: { grants: ["read_file", "write_file"], purpose: "triage" },
});
const read = s.read("read_file", (path) => readFile(path, "utf8"), { argNames: ["path"], refArg: "path" });
const write = s.govern("write_file", (path, content) => writeFile(path, content), { argNames: ["path", "content"], refArgs: ["path"] });
await read("repo/.env");
try {
await write("repo/pub/config.txt", "API_KEY=...");
} catch (e) {
if (e instanceof PolicyBlocked) console.log(e.ruleId, e.verdict);
}
await s.close();
Wrapped functions are async. withSession(opts, async (s) => { ... }) closes the session even if the body throws.
Options
| Option | Purpose |
|---|---|
approver | A function returning a boolean or { approved, decidedBy?, approver? }, or webhookApprover({ url, token, timeoutS }) for an HTTPS endpoint. |
socket | Unix socket of a running dh signer; the key stays in that process. Use await Session.open({ socket, ... }). |
rules / policy | Your own rules, in the same form as dh.toml. |
cloud | { enabled, url, api_key_env }, as [cloud]. Upload is on when DH_API_KEY is set; see Automatic upload. |
ostiary | { mode, baselines, internal_domains }, as [ostiary], or false. See Ostiary. |
Command line
npx @decision-horizon/sdk keygen --out <path> --kid <kid> [--force]
npx @decision-horizon/sdk verify <chain.jsonl> --pub <file.pub> [--kid <kid>] [--head <sha256:...>] [--no-meta] [--open] [--json]
npx @decision-horizon/sdk push [--pin] [--status] [--retry] [--dir <store>]
npx @decision-horizon/sdk watch [paths...] [--json] [--min review] [--follow] [--webhook <url>] [--hold]
Installed, the command is dhjs. verify prints VERIFIED (exit 0) or FAILED (exit 1), the same report as dh verify without witness options.
Differences from the Python package
- No
dh.toml, Cedar or retention handling: configure in code.dhjs pushtakes--urlinstead of reading[cloud]. - Cannot unlock an encrypted key: run it in
dh signerand passsocket. - No witness client:
coverage.witnesssays"none". - Two processes must not write the same session id.
The SDK also ships a Runner for gateway receipts, byte-identical to the Python runner's.
Policy
Rules live in dh.toml (or in a Cedar policy file with pip install 'decision-horizon[cedar]'). There are two tiers: hard blocks; soft is a checkpoint. action is a glob or a list of globs. targets is every path-like argument of the call (source and destination), set by the interceptor so the agent cannot override it.
# what the agent READ changes what it may DO next
[[policy.rules]]
id = "public_write_with_secret_in_horizon"; tier = "soft"
action = ["write_file", "edit_file", "move_file", "copy_file", "create_directory"]
when = { targets = "*pub*", horizon = "*secret*" }
# session taint: a secret observed at ANY earlier point keeps it on soft-deny
[[policy.rules]]
id = "session_taint_public_write"; tier = "soft"
action = ["write_file", "edit_file", "move_file", "copy_file", "create_directory"]
when = { targets = "*pub*" }
composition = { prior_action = "*", prior_ref = "*secret*" }
Enforced before any rule: not_granted (hard), expired authority (hard), and unknown tools (soft: escalate, never silently allow).
Taint by value
The interceptor keeps, in memory only, the values it has seen in sensitive content ([adapter].sensitive_refs, such as *.env*, *.pem, *token*). If one appears later in the arguments of any consequential call, secret_value_in_arguments fires. With cross_session_taint = true (the default), a keyed fingerprint index in the store (no values) catches a value read in an earlier session: secret_value_from_prior_session. A false positive can be retired with dh taint --retire <fp> --reason ….
Checkpoints and the approval channel
[approval].mode decides what a soft_deny means:
deny(default): the call is blocked and the record says no human was consulted.allow-env: approves whenDH_APPROVE=1and records that the environment variable decided. Development only.allow-all: for tests, never production.webhook: pauses on a decision from your HTTP endpoint (a Slack bot, ticket system, your own UI).
[approval]
mode = "webhook"
url = "https://approvals.example/dh"
timeout_s = 30 # default
token_env = "DH_APPROVER_TOKEN" # optional; sent as Authorization: Bearer, never written anywhere
allow_http = false # plaintext http is refused unless you say so (dev only)
The endpoint receives only what the record already exposes, plus a nonce; argument values never leave the box. It answers {"approved", "approver", "decided_by", "shown_hash", "nonce"}. The record can verify that the answer is bound to this request, not that a human acted, so it records decided_by: "webhook:<host>". A timeout, error or mismatched answer is recorded as policy:auto-deny (<reason>) and the action is blocked: no human consulted, never a denial by a human.
Key custody
Generating a key
dh keygen # ~/.dh/signer.key, kid signer-1, plaintext PKCS8 PEM, mode 0600
dh keygen --out /srv/dh/signer.key --kid acme-1
dh keygen --encrypt # passphrase from $DH_KEY_PASSPHRASE, --passphrase-file, or a prompt
The public half is written to <out>.pub. --force overwrites an existing key, after which previous chains no longer verify with the new key.
Signer daemon
[signing].key signs in-process, fine for development and single-host pilots. Otherwise run the signer as its own process, under its own user:
dh signer --key /srv/dh/signer.key --kid acme-1 --socket /run/dh/signer.sock # as user dh-signer
# dh.toml: [signing] socket = "/run/dh/signer.sock"
The proxy then holds no key. The daemon enforces a per-session monotonic sequence, so a compromised proxy cannot re-sign history or extend a closed session; it can only have new records signed, which the chain shows. The socket is created 0660; anything that can reach it can open new sessions.
The daemon also keeps a signed record of the last head it signed per session (<key>.seq.json), which gives dh verify an expected head for a running session (see Expected head). It is as trustworthy as the daemon's host.
The key at rest
dh keygen --encrypt stores the key under AES-256-GCM with a scrypt-derived key. The passphrase never goes on argv; for the proxy and SDK, prefer [signing].passphrase_file over passphrase_env. Every intent record states coverage.key_at_rest (plaintext, encrypted or daemon). [signing] require_encrypted = true (or dh signer --require-encrypted) refuses a plaintext key. Encryption does not protect a key unlocked in a process an attacker can read, nor a weak passphrase.
Pinning the public key
Verification always uses a public key you supply: dh verify --pub is required, and the key is never read from the chain. On the hosted service you pin each signer key once per kid, and a pin is never replaced (see Hosted API). A pin proves which key signed a chain; it does not prove whose key it is.
Witnesses
Everything above trusts the signer's host. A witness is a second process, meant for another host or trust domain, holding its own Ed25519 key. It never sees a record. After each record is appended, the interceptor sends it {session, seq, head}; the witness requires the sequence to be monotonic per session, refuses forks, logs the head to its own signed append-only log, and returns an attestation. The next record embeds it inside the signed body.
dh keygen --out /srv/dh/witness.key --kid witness-1 # on the witness host
DH_WITNESS_TOKEN=… dh witness --key /srv/dh/witness.key --kid witness-1 --listen 0.0.0.0:8790 --token-env DH_WITNESS_TOKEN
# or --socket /run/dh/witness.sock (guarded by the socket's file permissions)
# dh.toml: [witness] url = "https://witness.example:8790" token_env = "DH_WITNESS_TOKEN" every_n = 1 timeout_s = 5 required = false
dh verify <chain> --pub signer.key.pub --witness-pub witness.key.pub
dh verify <chain> --pub signer.key.pub --witness-pub witness.key.pub --witness-url https://witness.example:8790
A record at or before a witnessed head cannot be altered, dropped or reordered without breaking the chain or an attestation; new records after it can still be forged by the key holder. dh verify --witness-pub reports witnessed_through and the unwitnessed tail; --witness-url / --witness-socket asks the witness for the latest head it saw. An unreachable witness is stated in the next record, and with required = true it blocks consequential actions.
Quorum
Configure several witnesses with [[witness]], each pinned by kid and pub, and quorum = k (default: all):
[[witness]]
url = "https://w1.example:8790"
kid = "witness-1"
pub = "/etc/dh/witness-1.pub"
token_env = "DH_W1_TOKEN"
quorum = 2
[[witness]]
url = "https://w2.example:8790"
kid = "witness-2"
pub = "/etc/dh/witness-2.pub"
token_env = "DH_W2_TOKEN"
[[witness]]
socket = "/run/dh/witness-3.sock"
kid = "witness-3"
pub = "/etc/dh/witness-3.pub"
dh verify <chain> --pub signer.key.pub --witness-pub w1.pub --witness-pub w2.pub --witness-pub w3.pub --witness-quorum 2
A head counts only with at least k valid attestations from distinct pinned keys. Forging a witnessed head then needs the signing key and k of the n witness keys, and n − k witnesses may be down before a head goes unwitnessed.
Countersigned before the action runs
before_execute = true (implies every_n = 1 and required = true) makes the interceptor append the intent record, send its head to the quorum, and run the action only if k attestations came back. Otherwise the action does not run and the outcome says blocked with policy.blocked_by = "witness_before_execute_unattested".
Verifying chains
dh verify <chain.jsonl> --pub signer.key.pub [options]
dh verify runs entirely offline. It exits 0 only if nothing is flagged. The public key is pinned by you and never read from the chain.
Options
| Option | Meaning |
|---|---|
--pub | Pinned public key (.pub). Required. |
--kid | Expected key id (default: the store's meta, or the first record). |
--head | Expected head hash obtained out of band. The strongest check. |
--no-meta | Do not take the expected head from the store's .meta.json. |
--open | The session is still running: a missing terminal record is a warning. |
--state PATH | The signer daemon's state file: expected head is the last record that signer signed, accepted only if its signature verifies under --pub. |
--signer-socket PATH | Ask the running signer daemon for the last head it signed. |
-c, --config | Take the signer from [signing]: state if set, else the daemon at socket. |
--witness-pub, --witness-pubs-file, --witness-quorum, --witness-kid, --witness-url, --witness-socket, --witness-token-env, --witness-before-execute | Witness checks. See Witnesses. |
--json | Machine-readable report. |
Expected head
To catch a truncated open session or a different chain from the same key, compare the head against one you trust. Sources, weakest to strongest:
- The store's
.meta.json(the default). Weak: it sits next to the chain. - The signer daemon (
--state,--signer-socket,-c): a head recorded by a separate process and signed with the pinned key. As trustworthy as that process's host. --headwith a value you obtained out of band. This wins over the others.
dh verify <chain> --pub signer.key.pub --head sha256:…
dh verify <chain> --pub signer.key.pub --open --state /srv/dh/signer.key.seq.json
dh verify <chain> --pub signer.key.pub --open --signer-socket /run/dh/signer.sock
--open alone disables tail-truncation detection. A live session has no terminal record, so a chain with its last decisions removed looks the same as one that is still running. Pair --open with an expected head from the signer or --head. With an in-process [signing].key there is no signer-held head.On a host with Node and no Python, npx @decision-horizon/sdk verify prints the same report for a chain without witness options.
Hosted API
The hosted API stores your chains per tenant, searches and verifies them, and keeps an audit log. It holds only your public keys, never your signing key.
Base URL and authentication
https://api.decisionhorizon.dev
Every tenant route requires your tenant API key:
Authorization: Bearer $DH_API_KEY
You receive your tenant API key from us at onboarding. Store it as a secret; only a hash of it is kept on our side.
Session ids match ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$; kids match ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$.
Routes
| Method | Path | What it does |
|---|---|---|
| GET | /healthz | Public. Returns {"status":"ok"}. |
| GET | /openapi.json | Public. OpenAPI description of the tenant routes. |
| GET | /v1/whoami | Your tenant: {tenant, key_id, name, created_at, version}. |
| GET | /v1/keys | Pinned signer keys: {signers: {<kid>: {pem, fingerprint, pinned_at, pinned_by_key_id}}}. |
| PUT | /v1/keys/signers/{kid} | Pin an Ed25519 public key for a kid. Body: the PEM text, or {"pem": "..."}. |
| POST | /v1/verify | Stateless verify. Stores nothing. |
| POST | /v1/sessions/{session}/records | Upload records (JSONL) to a session. All or nothing. |
| GET | /v1/sessions | List sessions, ordered by session id. |
| GET | /v1/sessions/{session} | Download the stored chain as JSONL (application/x-ndjson), the original lines in seq order. |
| GET | /v1/sessions/{session}/verify | Verify a stored chain under the session's pinned key. |
| POST | /v1/sessions/{session}/hold | Place a legal hold. Body {"reason"?}, at most 500 characters. |
| DELETE | /v1/sessions/{session}/hold | Lift a legal hold. |
| GET | /v1/query | Search intent records across sessions. |
| GET | /v1/audit | Your tenant's audit log as JSONL, oldest first. |
Pinning signer keys
PUT /v1/keys/signers/{kid} accepts only Ed25519 public keys; a private key or another key type is rejected with 400. Pinning is permanent: the same PEM again returns 200 unchanged, and a different PEM for an existing kid returns 409 pinned_key_conflict. A pin is never replaced. The fingerprint is "sha256:" plus the hex SHA-256 of the key's DER bytes.
Verify
POST /v1/verify takes JSONL text, or JSON {"records": [...], "expected_head"?, "kid"?, "open"?}. kid defaults to the first record's sig.kid, and the key always comes from your pinned signers (404 unknown_kid if not pinned). A key inside the records is never trusted.
Response, also used by GET /v1/sessions/{session}/verify:
{
"ok": true,
"errors": [[index, "code"], ...], // first 100
"error_count": 0,
"warnings": [],
"head": "sha256:…",
"open": false,
"count": 7,
"pinned_key": {"kid": "signer-1", "fingerprint": "sha256:…"},
"expected_head_source": null
}
Error codes are those under What the verifier flags. expected_head_source is "out of band" when you supplied expected_head. For a stored session without one, the stored head is used and the source reads "server store meta (the head this server accepted at ingest; the operator is trusted for it — compare with a head obtained out of band)".
Uploading records
POST /v1/sessions/{session}/records takes a JSONL body and is all or nothing. Records must be signed under the session's pinned kid (404 unknown_kid otherwise). A record already stored unchanged is counted in duplicates; a different record at a stored seq is 409 conflicting_record. If verification flags a new record, the upload is 400 record_rejected with those errors and nothing is stored (an intent whose outcome has not arrived yet is accepted). Uploading after a terminal record is 409 session_closed. A line that is not a JSON object is 400.
Response: {session, accepted, duplicates, records, head, open}. Records are append-only and returned byte for byte as received; no endpoint edits or deletes them.
Listing and querying
GET /v1/sessions?limit=&cursor= (limit default 100, max 1000) returns {sessions: [{session, records, head, kid, closed, hold, last_ts}], count, next_cursor, truncated}.
GET /v1/query searches intent records only. Parameters: tool, rule, verdict (allow, soft_deny, hard_deny), target (matches action.ref or any of action.targets), status, horizon (matches any ref in horizon.observed), since (ISO 8601), session, limit, cursor (<session>:<seq>). It returns {decisions: [{session, seq, adr_id, ts, tool, target, targets, rule, verdict, hitl, status, observed, read_earlier, abstain}], count, next_cursor, truncated}.
Audit log
Every pin, ingest, verify, hold change and key change writes an audit entry {seq, ts, tenant, key_id, action, details, prev_hash, hash}. Entries are hash-chained per tenant and append-only. GET /v1/audit?limit=&cursor= returns them as JSONL.
Errors and limits
Every error is JSON:
{"error": "<human message>", "code": "<snake_case_code>"}
Status codes: 400 bad input, 401 missing or bad key, 403 forbidden, 404 not found (including another tenant's session), 409 conflict, 413 too large, 429 rate limited.
- Maximum request body: 4 MB (413 above it).
- Requests are rate limited per API key; over the limit you get 429.
- CORS: browser requests are accepted only from Decision Horizon's own web origins (such as the Console), with the
AuthorizationandContent-Typeheaders. Server-side and command-line clients are not affected.
Automatic upload (dh push)
With your tenant API key in DH_API_KEY, dh proxy, dh gateway and both SDKs (Python and Node) upload each session to the hosted store as it is written, in the background. It is on by default, for three reasons:
- The evidence survives the host. Anything on the machine that holds the chain can delete or truncate the local file. The hosted copy, and the head the server accepted, can't be rolled back from that machine.
- Verification gets a head that doesn't sit next to the chain, which is what catches a rewritten tail.
- Sessions are searchable, verifiable and holdable in the Console without copying files around.
To turn it off, set [cloud] enabled = false in dh.toml, or DH_PUSH=0 for one run. A host with no API key uploads nothing. Only the signed chain already on disk is sent (tool arguments are hashed, never stored), and your signing key never leaves the host. Each process prints one line at start saying upload is on, why, and how to turn it off.
[cloud]
enabled = true # default
url = "https://api.decisionhorizon.dev"
api_key_env = "DH_API_KEY" # the variable holding the key; never the key itself
export DH_API_KEY=dh_t_... # from onboarding
dh push --pin # once per signing key: pins [signing].key + .pub to your account
dh push --status # what is uploaded and what is pending
dh push # catch up anything a run left behind (offline, crash)
Upload never blocks the agent. Failures back off and retry, and anything still pending at exit goes with the next run or dh push. A record the server refuses (tampered, forked, or after the session closed) is marked and never retried silently; dh push --retry tries again once you've looked. A local chain that is now shorter than what was uploaded is reported, never repaired, and the hosted copy stays intact.
Examples
BASE=https://api.decisionhorizon.dev
AUTH="Authorization: Bearer $DH_API_KEY"
# who am I
curl -s "$BASE/v1/whoami" -H "$AUTH"
# pin a signer key (once per kid)
curl -s -X PUT "$BASE/v1/keys/signers/signer-1" -H "$AUTH" \
--data-binary @"$HOME/.dh/signer.key.pub"
# upload a session's records (JSONL)
SID=<session>
curl -s -X POST "$BASE/v1/sessions/$SID/records" -H "$AUTH" \
--data-binary @"$HOME/.dh/records/$SID.jsonl"
# verify the stored session against a head you saved yourself
curl -s -G "$BASE/v1/sessions/$SID/verify" -H "$AUTH" \
--data-urlencode "expected_head=sha256:…"
# query decisions
curl -s -G "$BASE/v1/query" -H "$AUTH" \
--data-urlencode "verdict=soft_deny" \
--data-urlencode "tool=write_file" \
--data-urlencode "since=2026-10-01T00:00:00Z"
Ostiary
Ostiary (a doorkeeper) learns what normal looks like for each agent from its own records: which tools and targets, in what order, how fast, at what hours, and what it had just read. It scores every intent in about 0.1 ms, offline, with no language model, and gives a risk, a recommended decision (allow, review or block) and its top reasons. With too little history for an agent it says so (cold).
In the path, inside the record
The proxy, the gateway and both SDKs score each call before it runs and sign the score into the intent record as policy.risk. It's on by default in advise mode: the score is evidence and nothing else. You choose what it may do:
[ostiary]
mode = "advise" # advise | escalate | enforce | off
baselines = "~/.dh/ostiary-gate.json"
internal_domains = ["acme.com"] # sending here isn't "external"
| Mode | What a score does |
|---|---|
advise | Recorded in policy.risk only. |
escalate | A call the policy allows but Ostiary rates review or block goes to your approver, who sees the score and reasons. No approver means it's denied. |
enforce | Block is denied, with policy.blocked_by = "ostiary"; review goes to the approver. |
The policy verdict is never rewritten, so the record always shows what the policy said and, separately, what Ostiary did.
One switch, every product
dh ostiary # mode, and what it has learned about each agent
dh ostiary mode escalate # set it in dh.toml (comments kept)
dh ostiary reset --agent support-1 # forget an agent (it changed jobs)
DH_OSTIARY=enforce dh proxy -c dh.toml -- <server> # any command, one run: advise | escalate | enforce | 0
Session.from_config("dh.toml") # Python: [ostiary] from the file
Session(key=..., ostiary="escalate") # or just the mode
new Session({ ..., ostiary: "escalate" }) // Node
The Console's Ostiary page lists every action it flagged across your sessions. Records made before Ostiary was on are scored right there in your browser with the same model; nothing is sent anywhere.
DH_OSTIARY=0 turns it off for one run. Baselines are stored with mode 0600 and protected from the governed agent like the record store; a damaged file starts cold and never blocks a session.
Two rules the model can't unlearn
- Sensitive content the agent read, in this or an earlier session, reaching an outbound call to a non-internal destination is always a block, even if that destination was made to look familiar first.
- Novelty alone (a new tool, area or sequence with no danger signal) is at most a review, and is learned after one. Nothing that scored as risky is ever learned as normal.
Watching existing records
dh watch # score [store].dir, print review and block
dh watch -f --webhook https://alerts.example/dh
dh watch -f --hold # legal hold in the hosted store on a block
dh watch --json --min allow # every score as JSON
dh watch --bench # rerun the labelled stress test
npx @decision-horizon/sdk watch ~/.dh/records # the same scores from Node
How it was measured
The shipped model was fitted on a synthetic, labelled corpus of agent sessions (four personas, legitimate behaviour that looks odd, seven attack families) and measured on sets it never trained on: an unseen attack family, renamed tools and domains, legitimate look-alikes, evasive attacks and baseline poisoning. It scores at least 85% precision, recall, F1 and decision accuracy on every one; the weakest are 91.8% precision on legitimate look-alikes and 96.6% recall on legitimate behaviours never used in design. The Python and Node implementations give identical scores. These numbers describe the corpus, not your agents: start in advise, review what it flags, then turn on escalate.
Console
The Console at decisionhorizon.dev/console/ is a browser front end to the hosted API.
Signing in
Sign in with your tenant API key. The key is kept only in that browser tab's sessionStorage. A sample-data mode shows the Console with example data.
What you can do
- Browse sessions.
- Filter decisions by tool, rule, verdict, target, outcome, what the agent had read, session, and time (since).
- Verify a session, optionally against an expected head you saved.
- Download a session's chain and the pinned public key.
- Place and remove legal holds.
- View pinned keys and the hash-chained audit log.
- "Verify a file": a stateless check of a chain file you supply, which stores nothing.
Verifying offline from the Console
You do not have to trust the hosted service for verification. Download the chain and the public key from the Console, then run the verifier on your own machine:
dh verify <session>.jsonl --pub <downloaded>.pub --head sha256:… # the head you recorded yourself
# or, without Python:
npx @decision-horizon/sdk verify <session>.jsonl --pub <downloaded>.pub --head sha256:…
For the strongest check, use the public key and head you kept yourself rather than copies the service returns.
SIEM export
dh export turns chains into one event per decision (an intent record and its outcome, merged). It verifies first, always: --pub is required and every chain is checked exactly as dh verify checks it. A chain that does not verify is refused and none of its decisions are exported; the run exits non-zero naming it. With --allow-unverified it is exported and each event says verified: false and why.
dh export ~/.dh/records/<session>.jsonl --pub ~/.dh/signer.key.pub # jsonl to stdout
dh export --dir ~/.dh/records --pub signer.key.pub --format ocsf --out decisions.ocsf.jsonl
dh export --dir ~/.dh/records --pub signer.key.pub --format pdf --out audit.pdf --report-org "Acme Corp"
dh export --dir ~/.dh/records --pub signer.key.pub --format cef --syslog siem.example:6514 --syslog-tls --syslog-ca ca.pem
DH_SPLUNK_TOKEN=… dh export --dir ~/.dh/records --pub signer.key.pub --format ocsf \
--splunk-hec https://splunk.example:8088 --follow --cursor ~/.dh/export.cursor
DH_OTLP_HEADERS="x-api-key=…" dh export --dir ~/.dh/records --pub signer.key.pub \
--otlp-endpoint https://otel-collector.example:4318 --follow --cursor ~/.dh/otel.cursor
Formats
jsonl(default): schemadh-export/1, with a stableevent_id(<session>:<seq>) and the verification result on every event.ocsf: OCSF 1.1.0 API Activity (class_uid6003). The fulldh-export/1object rides underunmapped.dh.cef: ArcSight CEF, with everydh-export/1field as adh<CamelCase>extension.otel: OpenTelemetry traces, one span per decision, following the GenAI semantic conventions (execute_tool <tool>,gen_ai.tool.name,gen_ai.tool.call.id,gen_ai.agent.*,gen_ai.conversation.id). One trace per session; the span id comes from the signed intent record's hash. A blocked or failed call is an ERROR span witherror.type. Everydh-export/1field rides asdh.*: verdict, approver, Ostiary score, record hash, head and the verification result. Spans also carry the CoSAI WS2 AI Telemetry Framework (AITF) attributes the records can fill:agentic_log.*,identity.approval.*,security.mediation.*andsecurity.attribute_source.*.
pdf writes a branded audit report to --out (pip install "decision-horizon[pdf]"): a letterhead with your organisation (--report-org), the verification statement, totals, a needs-attention section that explains every blocked call, checkpoint and Ostiary flag from its record, every session's decisions and every record hash. The PDF is not signed; it carries an events digest equal to the sha256 of the jsonl export of the same chains, so anyone can prove which records it came from.
Every format carries Ostiary's signed score: risk_score, risk_decision, risk_reasons, risk_mode and risk_model (null when the gate was off).
Sinks
--out FILE: mode 0600.--splunk-hec URL: token fromDH_SPLUNK_TOKEN, never argv;https://required.--otlp-endpoint URL: OTLP/HTTP (JSON) to any OpenTelemetry Collector or backend;/v1/tracesis added to a bare host. Headers fromDH_OTLP_HEADERSorOTEL_EXPORTER_OTLP_HEADERS, never argv;https://required; redirects refused; spans the collector rejects count as a failure.--syslog HOST:PORT: RFC 5424 over TCP, UDP (--syslog-proto udp) or TLS (--syslog-tls).
--follow --dir DIR --cursor PATH tails a store and exports each decision once its outcome is on disk.
record_hash, outcome_record_hash and head let anyone check it against the chain, which stays the evidence. Delivery is at least once. No native Sentinel or Chronicle connector is shipped; use CEF over syslog, the OCSF/jsonl file, or OTLP into a collector that forwards there.Retention and legal hold
Records are kept forever by default ([store].retention_days = 0). With a window set, dh prune deletes closed sessions whose terminal record (the signed timestamp inside the chain, not the file's mtime) is older than it. It never touches a session that is open, has no terminal record, or is on hold.
dh prune verifies each chain against the pinned public key before it trusts the terminal timestamp. A chain that does not verify is never deleted, and without a key nothing is deleted.
dh hold <session-id-or-chain-path> --on --reason "case 42"
dh hold <session> --off
dh sessions --dir ~/.dh/records # HOLD column
dh prune -c dh.toml --dry-run # what would go; deletes nothing
dh prune -c dh.toml [--older-than DAYS] # override the window for one run
Hold transitions are appended to <store>/hold.log. Each deletion appends the session and its head hash to <store>/prune.log, so a copy held elsewhere still verifies against that head.
On the hosted service, use POST / DELETE /v1/sessions/{session}/hold or the Console to place and lift holds. The hosted API has no endpoint that deletes or overwrites stored records.
Limits
These are stated limits. Each one is something the product does not do, or does only partly.
- Bypass. An HTTP tool server is governed only for calls that come through the proxy. The record cannot see a call that never reached it.
- The in-process SDK lives inside the agent process. A compromised agent can call the underlying function directly and leave no record.
- A compromised proxy can have a false new record signed, but cannot alter, drop or reorder existing ones. A compromised signer host can sign anything; witnesses narrow that to records after the last witnessed head and to false records written in real time, which they still countersign.
--openalone disables tail-truncation detection. Use an expected head from the signer daemon or one obtained out of band.accessible_not_retrievedcomes from a configured root or the downstream's own claim, only for directories the proxy can walk, at most 20,000 entries per walk. A server can name a directory it will not serve, and the proxy cannot tell.retrieved_not_usedis a heuristic, labelled with confidence 0.5. Whether content reached the action by value is deterministic; whether the agent reasoned about it without copying is not.- Value taint is literal, plus listed encodings, a split across two writes to one target, and a one-character edit. Two or more edits, halves sent to different targets, and unlisted re-encodings are not caught.
- The gateway sees the model's requested calls and the results the agent reports, nothing in between. Without a runner receipt it cannot verify that a call executed, or executed as recorded. An agent holding the upstream's URL and key can go around it.
- The hosted service is trusted for availability and what it stores, not for verification: re-verify any chain offline. Whoever holds a tenant API key can pin a key and upload chains under it.
FAQ
Does a record contain my file contents or tool arguments?
No. Observed content is hashed, arguments are hashed, and a target path carrying a known sensitive value is recorded as redacted:sha256:…. The approver sees the arguments in memory; the chain does not.
Do I have to trust the hosted service to know a chain is intact?
No. Download the chain (GET /v1/sessions/{session} or the Console) and run dh verify under the public key you pinned yourself. A head you saved out of band catches a substituted or truncated chain.
Can I verify without Python?
Yes, without witness checks: npx @decision-horizon/sdk verify prints the same report as dh verify.
What happens if my approval endpoint is down?
The action is blocked and recorded as policy:auto-deny (<reason>) with no approver. An unreachable approver is recorded as no human consulted, never as a denial by a human.
Does the absence of a record prove the agent did not act?
No. It is evidence only that the call did not pass that insertion point.
What if the proxy dies before the session ends?
The signer daemon keeps its sequence state across a restart. An open session whose proxy died before its terminal record verifies only with --open and is flagged otherwise. That is intended.