Human-in-the-Loop

Three mechanisms pause a run for a human:

1. AskUserQuestion: the agent asks a question and waits for an answer.
2. Tool approval: the agent waits for allow or deny before a gated tool call.
3. Plan mode: the agent proposes a plan and waits for approval before executing.

Runs inherit their permission mode from the explicit request override or the saved agent/task default. Turn on human_in_the_loop when you want checkpoints before the agent continues.

Quick start

runs.wait() handles all three inline, no manual polling loop:

from m8tes import M8tes

client = M8tes()

run = client.runs.create(agent_id=1, message="draft and send a weekly customer update",
                         human_in_the_loop=True, permission_mode="approval", stream=False)

run = client.runs.wait(
    run.id,
    on_question=lambda req: {"Which segment?": "enterprise"},  # answer questions
    on_approval=lambda req: "allow",                           # approve tool calls
)
print(run.output)

Both callbacks receive the full PermissionRequest: inspect req.tool_name and req.tool_input (for questions, req.tool_input["questions"] is the full list) before returning your decision.

permission_mode="approval" only pauses for tools that are not on the safe allowlist. Safe reads (and the Agent/Task spawn tools) do not raise awaiting_approval, so on_approval will not fire for those. If the agent stalls without a pending permission, create_and_wait / reply_and_wait raise TimeoutError and best-effort cancel the run (cancel_on_timeout=True); bare wait / poll observe only unless you opt in.

Permission modes

If a run resolves to approval or plan and you omit human_in_the_loop, the API enables it automatically. Explicitly setting human_in_the_loop=False with those modes returns a validation error.

AskUserQuestion

Answers always go through runs.answer(). The answer key is the question text:

client.runs.answer(run.id, answers={"Which customer segment should I prioritize?": "enterprise"})

Behavior depends on how the agent framed the question:

Tool approval gates and plan approvals never auto-continue.

for req in client.runs.permissions(run.id):
    if req.tool_name == "AskUserQuestion" and req.status == "pending":
        for q in req.tool_input["questions"]:
            # q["question"] is the answer key; q["options"] is the list of choices
            print(q["question"], [o["label"] for o in q["options"]])
        client.runs.answer(run.id, answers={"Which customer segment should I prioritize?": "enterprise"})

Tool approval

Fetch pending requests with runs.permissions(), then decide with runs.approve():

for req in client.runs.permissions(run.id):
    if req.status == "pending":
        client.runs.approve(run.id, request_id=req.request_id,
                            decision="allow",  # or "deny"
                            remember=True)     # also stores a cross-run always-allow policy

With decision="allow", remember=True allows matching requests for this run and saves an always-allow policy for future runs.

GET /runs/{id}/permissions and permission_resolved events carry the saved outcome. A later event can confirm persistence; update the UI when it arrives.

Strict human-decision tools such as decide_value_observation always ask again and omit the remember control. To save a policy before running, see pre-approve trusted tools.

client.runs.update_permission_mode(run_id=42, permission_mode="autonomous")
client.runs.update_permission_mode(run_id=42, permission_mode="approval")

Pre-approve trusted tools

Create per-user permission policies so trusted tools skip approval pauses across runs. Pre-approve read-only tools (search, fetch, list) and keep write/send/delete actions gated:

client.permissions.create(user_id="cust_123", tool="slack")
client.permissions.create(user_id="cust_123", tool="linear")

Omit user_id to pre-approve a tool at the account level: the scope runs match when they carry no user_id. This is also where "always allow" decisions made during a run are stored, so it is the list to check when you want to see or revoke standing approvals:

client.permissions.create(tool="slack")           # applies to runs with no user_id
for policy in client.permissions.list():          # standing account-level approvals
    client.permissions.delete(policy.id)          # revoke one

High-stakes actions (money, access, destroy) ask a human by default in approval/plan mode. Autonomous mode and an explicit Always-allow (approval card tick, or POST /permissions) supply standing grants; hard blocks, explicit denials, and strict human-decision tools still take precedence. Treat pre-approving one as deliberate. Every policy records source (run_approval or api). Routine task setup, including attaching an already-connected app and pausing or resuming a schedule, auto-approves without a stored policy.

def onboard_user(user_id: str):
    client.users.create(user_id=user_id)
    for tool in ["slack", "linear", "googlesheets"]:
        client.permissions.create(user_id=user_id, tool=tool)

Plan mode

The agent proposes a plan and waits for approval before executing. It has its own page: Plan Mode.

Production pattern: webhooks

Prefer webhooks over polling: subscribe to run.awaiting_input, show the pause, send the decision with answer or approve. AskUserQuestion pauses include questions in the payload; tool approval pauses use runs.permissions(). See Webhook Events.

{
  "type": "run.awaiting_input",
  "data": {
    "id": 42,
    "status": "awaiting_approval",
    "questions": [
      {
        "question": "Which customer segment should I prioritize?",
        "header": "Segment",
        "multiSelect": false,
        "options": [
          { "label": "enterprise", "description": "Large orgs (500+ seats)" },
          { "label": "mid-market", "description": "Growing teams" }
        ]
      }
    ]
  }
}

run = client.runs.reply_and_wait(
    run.id,
    message="also break it down by region",
    on_approval=lambda req: "allow",
)
print(run.output)

Next: Runs · Users · Tools · Webhook Events