Skip to content

Tool Approval

Use the top-level tool_approval block to make chosen tool calls wait for a person to approve them in the Matrix conversation. This example gates Slack posting and reactions, plus shell calls selected by a review script:

tool_approval:
  default: auto_approve
  timeout_days: 7
  rules:
    - match: slack_post
      action: require_approval
    - match: slack_react
      action: require_approval
    - match: run_shell_command
      script: ./approval_scripts/shell_review.py
      timeout_days: 3
Field Type Default Meaning
default auto_approve or require_approval auto_approve Decision for calls that no rule matches
timeout_days number, greater than 0 and at most 36500 7 How long an approval card stays open before it expires
rules list [] Ordered rules; the first matching rule wins
rules[].match string Required Case-sensitive glob over exposed function names, not toolkit identifiers, so the same function name in another toolkit also matches
rules[].action auto_approve or require_approval — Fixed decision; set exactly one of action or script
rules[].script string — Config-relative Python file defining check(tool_name, arguments, agent_name) -> bool, which may be async; approval is required only when it returns True
rules[].timeout_days number, greater than 0 and at most 36500 tool_approval.timeout_days Expiry window for this rule
scheduled_any_arguments boolean true Let a requester approve a scheduled tool call for any arguments to the same tool, not only the exact arguments; see Pre-Approved Tool Calls

config_manager calls that only read configuration, manage_config(operation="inspect") and manage_agent(operation="validate"), never ask for approval, even when a rule matches them or default is require_approval.

A tool can declare that its calls do what calls of another function do, such as a plugin function that types command lines into a shell; that function's rules then judge them too, so a run_shell_command rule also asks before such a tool runs a line it matches. Approval aliases explains how its own rules and that function's rules combine.

Approving and Denying

  • React to the approval card with ✅ to approve the tool call.
  • Reply to the card to deny the call; the start of the reply is recorded as the denial reason.
  • Only the original human requester can approve or deny their pending call. When an agent acts on a request relayed by another agent's reply, the original human is asked.
  • Tool calls requested by agents, the system, or configured bridge bots are denied instead of waiting for approval.
  • An unanswered card expires after its timeout_days and the call is denied.
  • A gated call can also be approved once, ahead of time, when an agent schedules it; see Pre-Approved Tool Calls.

With background jobs on, the default, most gated calls ask from their job instead; Approvals says how long the reply waits for the decision, that 🛑 on the reply while it is still running denies its jobs' pending cards, and what a restart does. A call that pauses its reply instead, such as a tool that asks for confirmation itself, a subagent call, or any gated call with background jobs off, works as follows. While approval is pending, the agent stops typing and counts as still responding in that conversation: later messages to it there wait until the approval ends and get a ⏳ reaction, while other conversations and agents carry on. Stopping the reply with 🛑, or deleting the message it answers, cancels the approval and expires its card, and deleting the message also removes the reply; an edit that regenerates the reply cancels it too (see Message Edits). Pending approvals survive restarts and config reloads, and an approved call resumes the paused response. The approved call runs only with the exact arguments shown on the card.

Auto-Approval for a Few Minutes

Eligible cards also offer auto-approval for 5, 10, or 30 minutes. It covers the original call, matching pending calls, and later calls for the same room, thread, requester, agent, and exact tool operation, with any arguments. It is offered only in a thread and when the card shows the complete arguments, and never for tools that request confirmation themselves, background-script approvals, or scheduled calls. The requester can stop auto-approval from the originating card, and any config change or room membership change ends matching grants; calls already approved still run.

Auto-Approve Everything

Send !auto_approve 30 (minutes) or !auto_approve 2h in a thread to run every tool call you request there without approval cards, for 1 minute up to 24 hours. It covers every agent and team in that thread, script rules, tools that ask for their own confirmation, background jobs, and background scripts, and turning it on approves the cards already waiting for you there. Other people in the thread still approve their own calls, an agent cannot turn it on for you, and a tool call scheduled to run later still asks when it is scheduled. In a room that uses thread_mode: room, the window covers the whole room. !auto_approve shows when the window ends and !auto_approve off ends it early; restarts and config reloads keep it. !auto_approve off does not stop auto-approval started from an approval card; stop that on the card. MindRoom Chat shows the open window in the thread header in rooms where the router may send the io.mindroom.auto_approve state event, which the rooms MindRoom creates allow.

Approval Card Contents

Cards show a redacted preview of the tool arguments, and clients can expand the complete redacted arguments when the preview is truncated. Fields whose names mark them as secret, such as password, credentials, or an Authorization header, are hidden while their field name stays visible. Inside text, only credentials in known token formats, such as sk-…, ghp_…, github_pat_…, xoxb-…, AIza…, and JSON Web Tokens, are replaced by numbered placeholders like ⟦secret-1⟧; equal tokens get the same number. Other inline secrets, such as export DB_PASSWORD=hunter2 or an inline Authorization: Basic … header, stay visible, so keep secrets in credentials or secret-named fields. Deny the call when a hidden field or a placeholder where a command, host, path, or delimiter belongs could change what runs.

A card cannot be approved when its arguments exceed 2 MB, nest deeper than 32 levels, or fail to upload; approving it denies the call with Cannot approve: the tool arguments cannot be shown in full. Have the agent retry with a smaller payload, such as saving large content to a workspace file or sending it as an attachment, or auto-approve the tool with a script rule.

Tools That Cannot Pause for Approval

The OpenAI-compatible API has no approval cards, so it hides every tool function that matches a required-approval rule, including script rules. Skill and knowledge-search functions such as get_skill_script and search_knowledge_base cannot pause for approval on any channel, so they are hidden when a required-approval rule or default: require_approval applies to them. Add an auto_approve rule for such a function to keep it available.

When the Router Is Missing

Approval cards need the router in the room, so a gated call in a room without the router is denied with Tool approval needs the router in this room. The agent gets that denial as the call's result and can recover on its own: every agent in a room has a built-in invite_router tool that invites the router into the current room, waits briefly for it to join, and reports when the invite is still pending. Once the router has joined, the agent retries the call, and the card appears as usual. The router accepts that invite only when its router.accept_invites allows the inviting agent's Matrix account; for a team, that is the team's account rather than the member agent's. Otherwise enable that setting or add the router to the room manually, then retry. An adopted personal room keeps the router out unless its record lists it in router_user_id or additional_user_ids, so invite_router refuses there instead of inviting a router the room would remove again.