Policy, approvals, and evidence

Tanomis’s promise is that an agent can act, and every action stays attached to who asked, what was allowed, and what actually happened. This page is the map of those controls. Each one has its own guide; this is where they fit together.

At a glance

• Declared ceilings in agent.yaml bound what a version may reach: models, external hosts, connector tools, and the authority its own tokens can carry.
• Tenant ceilings set by an administrator only ever narrow a declaration.
• Approvals pause a run for a person at the actions you choose, and survive disconnects.
• Two evidence planes record it: a tamper-evident audit ledger for decisions and attribution, and an execution trace for what the agent did, kept apart on purpose.

Every control is a ceiling, and ceilings only narrow

A version declares what it needs. An administrator may set a per-tenant ceiling. The effective permission is the intersection, and no layer can add to what a lower one declared.

Control	Declared by the author	Bounded by the tenant	Enforced at
Models	model, permitted_models	Tenant model policy	The LLM gateway, per call
External hosts	network.egress	Tenant egress ceiling	Deploy time, then the runtime proxy per connection
Connector tools	integrations.<key>.tools.allow	Compatible connection and agent access	The gateway, per tool call
Agent authority	policy.scope_ceiling	The caller’s own ceiling on a delegated call	Delegation and token exchange

Where a declaration exceeds the tenant ceiling, the deploy fails and names both the entry and the ceiling that excluded it, before anything is built. You find out in seconds.

Approvals: a person decides at the moments you choose

Two manifest settings turn specific moments into durable interactions:

• policy.approval_required_tools lists the harness tools that must wait for a permission decision. Each call emits a permission request; the run pauses until a person allows or denies.
• policy.enable_ask_user lets the agent ask a person a question mid-run and wait for the answer.

Governed connector tools can be marked the same way with approval_required_tools on the integration grant.

An interaction is a control-plane record, not a live socket. It survives a closed browser tab, a restarted application, or a suspended session. A decision is accepted exactly once, so two reviewers cannot both answer; the second sees the recorded answer. The application flow is in Approval-required actions; the Console renders the same requests as allow/deny cards.

Identity: who asked, and who acted

Every request carries two identities kept apart: the invoking principal (the person or service that started the work, resolved from the access token and the selected workspace) and the agent actor (the version that acted, attested by the platform with a per-run identity that the agent process cannot forge).

When one agent hands work to another, the callee’s effective authority is what it was granted for that call, intersected with both agents’ ceilings. Authority narrows at every hop and never widens. See Identity and access and Delegate work to another agent.

Evidence: two records, kept apart

Plane	What it records	Properties	Who uses it
Audit ledger	Attribution, policy decisions, approvals, delegation decisions, enablement changes, content hashes	Tenant-isolated, append-only, hash-chained, signed. It carries references and decisions, never prompt or tool payload bodies.	Auditors, compliance, incident review
Execution trace	One trace per run: model calls, tool calls, timing, and content captured at the level tenant policy allows	Mutable evaluation data with its own capture, sampling, and retention policy	Engineers debugging behaviour, evaluators

They share the run and session identifiers, so a ledger decision can point at the trace content it was made about, by hash, without copying the content into the ledger. Read the organization’s trail with tanomis org audit; see Audit and evidence.

What evidence can and cannot prove

A valid ledger chain proves the platform’s record is intact and unaltered. It does not by itself prove that an external system changed the way the agent intended. For effects on other systems, verify in that system.

What every run gets

The causal order is identity → context → policy checkpoint → agent action → optional human decision → evidence.

• Identity on both sides. The person or service that asked, and the exact agent version that acted, attested by the platform.
• A policy checkpoint before the action. Models, hosts, connector tools, and delegated authority are ceilings that only narrow.
• A person when you want one. Approval requests and questions pause the run and survive disconnects; the first answer wins.
• Evidence you can hand to an auditor. A signed, append-only ledger of decisions, and a separate execution trace of what the agent did.

Availability: Shared connectors are configured per tenant; durable approvals are on in hosted Tanomis. See What is available where.

The journey, with the controls in place

1. Build: declare models, hosts, connectors, approvals, and the authority ceiling in agent.yaml.
2. Deploy: the declaration is validated against the tenant’s ceilings before a build starts, then frozen into the version.
3. Run: the gateway, the egress proxy, and the connector gateway enforce per call; approvals pause the run where you asked them to.
4. Review: the ledger holds the decisions; the trace holds the execution.

Where to go next

• Restrict network egress
• Approval-required actions
• MCP connectors
• Audit and evidence