> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause for a human

> Stop an agent mid-task to ask a question or wait for an approval, then resume the same task with the answer.

An agent can stop mid-task and wait for a person, then resume the **same task** with their answer. This is plain A2A, with no Nasiko SDK: your agent ends its turn in one of two paused task states, and Nasiko does the rest. It records a pending request, shows it in **Chat** and in `nasiko chat`, and sends the person's reply back to your agent as the next message on that task.

This page is for agent authors. For how people answer a pause, and the API that resolves one, see [Approvals](https://docs.nasiko.com/governance/approvals.md).

| Task state | Use it when |
| - | - |
| `TASK_STATE_INPUT_REQUIRED` | The agent is missing information it shouldn't guess: a name, a date, an amount, a recipient |
| `TASK_STATE_AUTH_REQUIRED` | A person must grant something first: a tool approval, or reconnecting a connector |

The older `input-required` and `auth-required` names are accepted too.

> [!TIP]
>
> The general-assistant agent in the `nasiko` repo, [`agents/general-assistant-1.1.1.zip`](https://github.com/Nasiko-Labs/nasiko/blob/main/agents/general-assistant-1.1.1.zip), implements everything on this page. Deploy it with `nasiko upload agents/general-assistant-1.1.1.zip`, then send `hitl input test`, `hitl auth test`, `hitl options test`, or `hitl multiselect test` to try each kind of pause without a model key.

## Pause

With `a2a-sdk` (Python), set the state with a message and optional `metadata`:

```python theme={null}
await updater.update_status(
    TaskState.TASK_STATE_INPUT_REQUIRED,
    message=updater.new_agent_message([new_text_part("Which repo should I file this in?")]),
    metadata={"messages": llm_history, "pending_tool_call_id": call.id},  # your resume state
)
```

The message text becomes the question the person sees. `metadata` is saved on the task and handed back to you on resume, so store everything you need to continue: the model conversation so far, the pending tool call.

> [!WARNING]
>
> Use a persistent task store if your agent can restart while a task is paused. `InMemoryTaskStore` loses paused tasks on restart.

Some `metadata` keys change how the question is shown:

| Key | Applies to | Effect |
| - | - | - |
| `auth_url`, `provider` | `TASK_STATE_AUTH_REQUIRED` | Shows an **Authorize with *provider*** link |
| `hitl_request_id` | `TASK_STATE_AUTH_REQUIRED` | Links the pause to the MCP gateway's approval request, so approving it actually grants the tool. Copy it from the gateway error. See [below](#pause-for-a-tool-approval). |
| `expected_input` | `TASK_STATE_INPUT_REQUIRED` | A hint about the expected answer |
| `options`, `header`, `multi_select`, `allow_custom_input` | `TASK_STATE_INPUT_REQUIRED` | Shows choices instead of a free-text box. See [Offer choices](#offer-choices). |

## Resume

The person's reply arrives as a new message on the **same task ID**. `context.current_task` is the stored task: its `status.state` is still the paused state, and its `metadata` is what you saved. Branch on that state:

```python theme={null}
stored = context.current_task
if stored and stored.status.state == TaskState.TASK_STATE_INPUT_REQUIRED:
    meta = MessageToDict(stored.metadata)   # metadata comes back as a protobuf Struct
    history = meta["messages"] + [{"role": "tool",
                                   "tool_call_id": meta["pending_tool_call_id"],
                                   "content": user_text}]
    # ...continue the model loop with `history`
elif stored and stored.status.state == TaskState.TASK_STATE_AUTH_REQUIRED:
    # retry the exact tool call the person just approved; pause again if it still needs approval
    ...
```

For a `TASK_STATE_AUTH_REQUIRED` pause, the reply text is `confirmed` or `denied`. Don't treat any other value as approval.

## Pause for a tool approval

When a tool's permission for your agent is **ask**, the [MCP gateway](https://docs.nasiko.com/build/mcp/agent-integration.md) answers `tools/call` with error `-32001` until someone approves it. A connector whose own credential is missing or broken answers `-32002`. For both:

1. Read the approval request ID from `error.data`: `hitl_request_id`, or `hitl_request_ids` (a list) for a batched call such as Composio's `COMPOSIO_MULTI_EXECUTE_TOOL`. Check both keys.
2. Pause with `TASK_STATE_AUTH_REQUIRED`, and put that ID in `metadata` as `hitl_request_id`.
3. On resume with `confirmed`, retry the same tool call. Pause again if it still returns `-32001`.

Without `hitl_request_id`, the person can confirm the pause but the tool stays unapproved.

## Offer choices

Add these keys to `TASK_STATE_INPUT_REQUIRED` metadata to show choices:

```python theme={null}
metadata = {
    "header": "Format",
    "options": [
        {"label": "Summary", "description": "Brief overview"},
        {"label": "Detailed"},
    ],
    "multi_select": False,        # default false
    "allow_custom_input": True,   # also allow a typed answer; default false
}
```

On resume you get the chosen `label` back exactly. For multi-select, each chosen label, and any typed text, is on its own line.

Labels must be non-empty and unique, with at most 20 options. If the block is malformed, Nasiko drops it, shows a plain text question instead, and logs a warning on the server.

## Make a model-driven agent pause reliably

Give the model two extra tools alongside its MCP tools, `ask_human(question, options?)` and `finish_task(message)`, and call it with `tool_choice="required"`.

With `tool_choice="auto"`, models often ask a clarifying question as plain text, which you can't tell apart from a final answer. When every turn must be a tool call, the tool the model picks tells you what to do:

| Model calls | Your agent |
| - | - |
| `ask_human` | Pauses with `TASK_STATE_INPUT_REQUIRED` |
| An MCP tool that returns `-32001` or `-32002` | Pauses with `TASK_STATE_AUTH_REQUIRED` |
| `finish_task` | Completes the task |

## Answering a pause

People answer pauses inline in **Chat** and in `nasiko chat`, or in `nasiko maf workflow run … --wait` for workflows. Other clients use the HTTP API: list pending requests with `GET /api/hitl/pending` and answer with `POST /api/hitl/{id}/resolve`. See [Approvals](https://docs.nasiko.com/governance/approvals.md) for the request body for each kind of pause.

## Related

* [Approvals](https://docs.nasiko.com/governance/approvals.md) — how people answer a pause, and the API
* [Connect your agent to the MCP gateway](https://docs.nasiko.com/build/mcp/agent-integration.md) — the gateway errors that trigger a tool-approval pause
* [Tool permissions](https://docs.nasiko.com/governance/tool-permissions.md) — set a tool to **ask**
* [A2A agents and frameworks](https://docs.nasiko.com/build/a2a.md) — the task states and wire format


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.