Skip to content
Hexel StudioDocs

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:

ToolTitan capability
shellharness.sandbox.shell
read_fileharness.sandbox.read_file
write_fileharness.sandbox.write_file
edit_fileharness.sandbox.edit_file
list_filesharness.sandbox.list_files
search_filesharness.sandbox.search_files
export_fileharness.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_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 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.

ErrorMeaning
titan_refusedTitan 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_unavailableTitan did not answer. Try again.
503 approvals_unavailableNo 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.