# Policy, approvals, and evidence

The controls that decide what an agent may do, the points where a person can step in, and the records that prove what happened.

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.

- **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](/guides/run/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](/concepts/identity-and-access) and
[Delegate work to another agent](/guides/run/delegate-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](/guides/audit/audit-and-evidence).

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](/reference/availability).

## 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](/guides/govern/restrict-network-egress)
- [Approval-required actions](/guides/run/approval-required-actions)
- [MCP connectors](/guides/connect-tools/mcp-connectors)
- [Audit and evidence](/guides/audit/audit-and-evidence)