Skip to main content
Some tool calls should not run on an agent’s say-so: a large payment, deleting data, sending something to a customer. With require_approval=True, RootSign records the call as pending, holds it until a person approves or rejects it, and records that decision next to the action. If nobody answers in time, the call is refused and recorded as timed out.
Approving from another terminal needs the PostgreSQL backend, because the agent and rootsign approve are different processes reading the same store. On the default JSONL backend, approval is an inline prompt in the agent’s own terminal.

Hold a tool for approval

1

Set up the PostgreSQL backend

start-db runs PostgreSQL with TimescaleDB in Docker, and init creates the tables.
2

Mark the tool

Add require_approval=True to @rootsign.trace(). The function body runs only after a person approves:
transfer.py
Run it. The script stops at wire_transfer and waits:
3

Approve it from another terminal

List what is waiting, then approve by action ID:
Within a couple of seconds the waiting script runs the tool and finishes:

Reject, or let it time out

To refuse the call, add --reject:
The tool never runs, and the call raises HiTLRejectedError in the agent:
If nobody answers within timeout_seconds, the call raises HiTLTimeoutError and is recorded as timed out, which is kept distinct from a person saying no:
A decided action is no longer pending, so approving it again fails with Error: no pending action found with ID <action_id>. and exit code 1.

Options

rootsign approve --list shows the 20 most recent pending actions across all sessions.

What gets recorded

For the three runs above, the approval records read: Approval records are not part of the hash chain, so a session with pending, rejected or timed-out actions still verifies as VALID. An evidence bundle shows each approval next to the action it decided.
approver_id is the operating-system login of whoever ran rootsign approve, written as cli:<user>. RootSign does not authenticate the approver: anyone who can run the CLI against the database can approve or reject, and authorization_status is not covered by the hash chain. Control who can reach the database, and treat approver_id as a label, not proof of identity.

On the JSONL backend

With the default backend there is no shared store for another process to write to, so RootSign asks in the agent’s own terminal instead. The first word decides: y, yes or approve approves, anything else rejects, and the rest of the line is recorded as the reason:
The approval is recorded with approver_id tty:<os user>. Without a terminal, for example in a background job or CI, the first call fails before the tool runs:
A JSONL session file is append-only, so the action keeps authorization_status pending after the decision. The decision is in the approval record that follows it, and an evidence bundle shows the two together.

Limitations

  • Plain functions only. require_approval=True on a LangChain BaseTool or a CrewAI tool raises NotImplementedError. Put it on the plain function the tool calls instead. The MCP proxy has its own require_approval=True that holds every proxied call.
  • No timeout on the JSONL prompt. The inline prompt waits until someone answers.
  • Approval happens from the CLI. There is no web interface for approving yet.

Export an evidence bundle

Show a reviewer each action with the approval that decided it.

Redact PII

Keep personal data out of what the approver is shown and what is stored.