HITL Policies

Human-in-the-loop (HITL) lets you intercept tool calls before they execute and decide — approve, block, or let them pass automatically — based on a named policy file.

How it works

HITL is on by default. When the engine runs a tool call, it evaluates the active policy and takes one of three actions:

• approve — pause and prompt the user; execution continues only after explicit approval
• allow — pass through silently (no prompt)
• deny — reject the call immediately without prompting

In the CLI, approval prompts appear inline in the terminal (TTY):

To disable HITL entirely, pass --auto:

# HITL on (default) — the engine pauses before destructive tool calls:
contenox chat --shell "refactor main.go"

# HITL off — autonomous mode, no approval prompts:
contenox chat --shell --auto "refactor main.go"
contenox run  --auto --chain ./my-chain.json "do the thing"

[!WARNING] --auto disables all approval prompts. Use only in trusted environments or non-interactive scripts.

Policy file format

A policy is a JSON file with an optional default_action and a list of rules:

{
  "default_action": "deny",
  "rules": [
    { "tools": "local_fs",    "tool": "write_file",  "action": "approve" },
    { "tools": "local_fs",    "tool": "sed",         "action": "approve" },
    { "tools": "local_shell", "tool": "local_shell", "action": "approve" },
    { "tools": "webtools",    "tool": "web_post",    "action": "approve" },
    { "tools": "webtools",    "tool": "web_put",     "action": "approve" },
    { "tools": "webtools",    "tool": "web_patch",   "action": "approve" },
    { "tools": "webtools",    "tool": "web_delete",  "action": "approve" }
  ]
}

Rules are evaluated top-to-bottom; the first match wins.

Condition operators (when[].op)

A rule with when conditions gates a tool only for calls whose arguments match — for example, prompting only for shell commands in a blacklist:

{ "tools": "local_shell", "tool": "local_shell", "action": "approve",
  "when": [{ "key": "command", "op": "command_ask_always", "value": "rm,sudo,dd,chmod" }] }

Who may answer a unit’s question (attention)

A mission unit that hits something it must not decide alone calls its mission.mission_ask_attention tool. That question lands in the session that fired the mission, where you answer it in place — your words go straight back to the unit as the result of the call it is parked on, and it continues.

By default only a human may answer, because that is what the unit escalated for. An envelope can hand routine questions to the agent that fired the mission instead — it often already knows the answer from the conversation the mission was fired in:

{
  "default_action": "approve",
  "rules": [],
  "attention": { "allowAgentAnswers": true, "maxAgentAnswers": 2 }
}

The agent is also skipped when the firing session is busy with a turn you started, or is not currently open — a question is never silently swallowed by an agent-to-agent exchange you cannot see. When the agent does answer, it happens as a visible turn in your transcript, and the durable ask records that an agent (not a person) answered it.

Built-in presets

Contenox ships six policy presets, written to ~/.contenox/ by contenox init. (A workspace .contenox/ file with the same name overrides the global one.) The first three are the general-purpose postures; the last three are the profiles the ACP editor transports and the terminal UI load.

Each preset also states who may answer a unit’s question (see attention) rather than inheriting the invisible default, and the stances follow each preset’s character:

Selecting the active policy

contenox config set hitl-policy-name hitl-policy-strict.json
contenox config get hitl-policy-name   # verify

This writes to the KV store and takes effect immediately — no restart required. The setting applies to all subsequent invocations in the same workspace.

Policy resolution order

When HITL is enabled and a tool call needs evaluation, the engine resolves the policy as follows:

1. Read the hitl-policy-name key from the KV store.
2. If set, load that file from the workspace .contenox/ directory, falling back to ~/.contenox/.
3. If the key is empty or the file is missing, fall back to hitl-policy-default.json.
4. If that file is also missing, use a built-in fail-closed policy with no rules: every tool call, including reads, requires approval.

See contenox workspace in the CLI reference for granting and revoking the workspace roots sessions may run in.