---
title: Approvals and autonomy
description: How Titan decides each action an agent takes in its sandbox, how a
  task waits for an approval, and how you or your approvers decide it.
url: https://hexelstudio.com/docs/harness/approvals
---

The harness gives every agent a sandbox: its own computer, with a shell and a workspace of files. How much the agent may do there without asking is your Titan policy's decision, not the harness's.

## Every sandbox action is a Titan capability

Each sandbox tool is a Titan capability of its own:

| Tool | Titan capability |
| --- | --- |
| `shell` | `harness.sandbox.shell` |
| `read_file` | `harness.sandbox.read_file` |
| `write_file` | `harness.sandbox.write_file` |
| `edit_file` | `harness.sandbox.edit_file` |
| `list_files` | `harness.sandbox.list_files` |
| `search_files` | `harness.sandbox.search_files` |
| `export_file` | `harness.sandbox.export_file` |

Before the tool runs, Titan checks the call against your policy, which allows it, denies it or requires approval ([Policies and approvals](https://hexelstudio.com/docs/titan/policies-and-approvals)). The Agent Ledger records the decision and the execution. A denied call does not run, and the agent receives the refusal as the tool's result.

## Autonomy in the private preview

When Hexel Studio onboards your organization, you agree the harness's policy together. The starting point:

- The file tools and `export_file` are allowed.
- `shell` is allowed and confined to the sandbox: the sandbox has no internet access.
- Or, if you prefer, `shell` requires approval by the people you name.

You can ask for a different policy at any time. A [swarm](https://hexelstudio.com/docs/harness/swarms) can narrow its members further with `access.capabilities`; a member never gets more than its swarm allows.

## When an action needs approval

1. The agent calls a tool whose rule requires approval. Titan records an approval request.
2. The task becomes `waiting` with `waiting_reason: approval`, and its stream gets `approval.requested` `{approval_id, call_id, tool, capability}`. `GET /harness/tasks/{id}` lists the approvals the task waits on, with Titan's status; it never shows the action's arguments.
3. A person decides it. The stream gets `approval.decided` `{approval_id, call_id, status, approved}`.
4. Approved, the tool runs and the task continues. Denied or expired, the tool does not run.

## Decide an approval

The person a task acts for can decide its approvals through the harness, when your Titan policy lets a person decide their own agent's actions. Titan makes the decision: the harness forwards it with **your own Titan user-route token**, in the `X-Titan-User-Token` header. That token is issued for Titan's person routes when you sign in; it is not the CLI login or an API access token. Ask Hexel Studio how to get yours during the preview.

```bash
export HEXEL_USER_ROUTE_TOKEN="..."     # or pass --titan-token-file
hexel harness approve tsk_123 apr_456
hexel harness deny tsk_123 apr_456
```

```bash
curl -X POST https://api.hexelstudio.com/v1/harness/tasks/tsk_123/approvals/apr_456 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" -H "X-Environment-Id: $ENVIRONMENT_ID" \
  -H "X-Titan-User-Token: $TITAN_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve"}'
```

Titan checks that the run's session acts for you before it takes your decision.

| Error | Meaning |
| --- | --- |
| `titan_refused` | Titan refused the decision; `details.titan_code` says why, for example `SELF_APPROVAL_NOT_ALLOWED` when your policy needs someone else to approve, or `NOT_FOUND`. |
| `502 titan_unavailable` | Titan did not answer. Try again. |
| `503 approvals_unavailable` | No Titan is configured to decide approvals for this environment. |

Approvers your policy names decide on Titan's own approvals, as for any other agent: see [Approvals](https://hexelstudio.com/docs/titan/approvals). The [attention inbox](https://hexelstudio.com/docs/harness/attention) lists the approvals and questions waiting on you.

## Stop an agent

Every run has a Titan session. Titan's [kill switch](https://hexelstudio.com/docs/titan/kill-switch) stops it, and `hexel harness task cancel` cancels the task.
