Task Lifecycle

Every phone task follows the same loop: start it, monitor until something actionable happens, act on the outcome. This page is the complete map.

The four states

                    ┌──────────┐
   phone_run_task ─>│ pending  │  waiting for the phone
                    └────┬─────┘
                         │ phone picks it up
                    ┌────▼─────┐
              ┌─────│ running  │─────┐
   task pause │     └────┬─────┘     │ terminal outcome
              │          │           │
        ┌─────▼────┐     │      ┌────▼──────┐
        │  paused  │─────┘      │ completed │  + terminal
        └──────────┘  resume    └───────────┘

Status	Meaning
`pending`	Accepted by the server and waiting for the phone.
`running`	The phone has started executing the task.
`paused`	Execution is suspended and can be resumed on the same `task_id`.
`completed`	The task reached a terminal outcome.

The monitor loop

phone_task_monitor is how you wait. It returns as soon as the task is paused or completed; otherwise it returns monitor_timed_out: true after its timeout (default and cap 120 s):

loop:
    result = phone_task_monitor(task_id)
    if result.monitor_timed_out:      # still pending/running
        continue                       # just call it again
    if result.status == "paused":
        phone_task_resume(...)         # or leave it paused deliberately
        continue
    # status == "completed" → read result.terminal

Use phone_task_status only for a point-in-time snapshot, never as a polling loop.

Terminal outcomes

When status is completed, exactly one terminal explains why:

Terminal	Meaning	What to do
`ok`	The task completed successfully.	Read `result`.
`needs_user_control`	The phone needs user input or confirmation.	Answer with `phone_task_message`.
`timeout`	Execution exceeded its deadline.	Retry with a higher `per_call_timeout_s` or a narrower prompt.
`queue_wait_exceeded`	The phone did not start the task before its queue deadline.	Confirm the device is online and free, then start a new task.
`stopped_by_user`	Cancelled - via `phone_task_cancel`, `phone_session_end`, or displaced by a new `phone_run_task` on the same device.	Start a new task if still needed.
`agent_error`	The phone agent failed while executing.	Retry; check `error` for details.
`device_offline`	The task could not be delivered to the selected device.	Reconnect the device, then retry.
`session_expired`	The session expired before completion.	Start a new session and task.
`iteration_limit`	The phone agent reached its action limit.	Break the task into smaller steps.

Handling patterns for each are in Error handling.

Human-in-the-loop handoffs

Sensitive moments - logins, confirmations, CAPTCHAs - are never handled by the agent alone. The phone hands control back:

The task completes with terminal: needs_user_control

Mobile message_user, needs_confirmation, need_login, need_login_details, and CAPTCHA actions all surface this way.

Inspect what the phone needs

The task’s error.control_type and error.prompt describe the request - a confirmation, login details, a CAPTCHA to solve.

Answer with phone_task_message

Collect the user’s answer - or let them complete the step directly on the device and send a short acknowledgement. The response contains a continuation_task_id.

Monitor the continuation task

Not the completed original - it will never run again. A continuation task can itself finish with needs_user_control; repeat until a terminal outcome no longer requests control.

In the handoff reply, delivered_to_device: false is not a failure - the original task is already completed. The presence of continuation_task_id is the success signal.

Pause and resume

phone_task_pause returns pausing immediately; monitor until the task reports paused or completed.
phone_task_resume continues the same task_id, optionally with a course-correcting instruction.
Time spent paused does not count against the execution timeout.

Steering a running task

phone_task_message adds guidance to a running task without pausing it - “use the second option”, “skip that dialog”. Keep monitoring the same task_id; check delivered_to_device in the response.

Displacement

One task per device: starting a new phone_run_task on a device cancels its existing pending, running, or paused MCP task (terminal: "stopped_by_user"). Tasks started from the phone app itself are not cancelled and can hold the execution lane, keeping new MCP tasks pending.

Error handling

A handling pattern for every terminal outcome

Monitoring

Steps, snapshots, and debugging live tasks

Getting Started

Core Concepts

Use Cases

Best Practices

Troubleshooting

The four states

The monitor loop

Terminal outcomes

Human-in-the-loop handoffs

Pause and resume

Steering a running task

Displacement

Next

Error handling

Monitoring

​The four states

​The monitor loop

​Terminal outcomes

​Human-in-the-loop handoffs

​Pause and resume

​Steering a running task

​Displacement

​Next

Error handling

Monitoring

The four states

The monitor loop

Terminal outcomes

Human-in-the-loop handoffs

Pause and resume

Steering a running task

Displacement

Next