Approvals and autonomy
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.
On this page
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). 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_fileare allowed. shellis allowed and confined to the sandbox: the sandbox has no internet access.- Or, if you prefer,
shellrequires approval by the people you name.
You can ask for a different policy at any time. A swarm can narrow its members further with access.capabilities; a member never gets more than its swarm allows.
When an action needs approval
- The agent calls a tool whose rule requires approval. Titan records an approval request.
- The task becomes
waitingwithwaiting_reason: approval, and its stream getsapproval.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. - A person decides it. The stream gets
approval.decided{approval_id, call_id, status, approved}. - 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.
export HEXEL_USER_ROUTE_TOKEN="..." # or pass --titan-token-file
hexel harness approve tsk_123 apr_456
hexel harness deny tsk_123 apr_456curl -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. The attention inbox lists the approvals and questions waiting on you.
Stop an agent
Every run has a Titan session. Titan's kill switch stops it, and hexel harness task cancel cancels the task.