Phone Agent Debugging and Recovery: Fix Failed Android AI Assistant Tasks

Stop a Failed Phone-Agent Task Safely

The first five minutes of phone agent debugging and recovery should protect the phone from repeated external effects. Stop the active task, leave the relevant app on its current screen, and read the last visible result before pressing retry. A surfaced error may describe the final failed step while the actual cause occurred earlier. For example, a message can appear to fail at sending even though the first problem was an ambiguous contact selection or a permission change.

Start by deciding whether the workflow was read-only, reversible, or consequential. Reading battery status is usually safe to repeat. Changing volume or brightness is reversible after checking the current value. Sending a message, placing a call, deleting an item, creating a calendar event, or submitting a form can affect another person or service, so confirm whether that effect already happened. Repeating the entire request can create a duplicate message, event, order, or notification.

1. Stop the running task and prevent automatic repetition.
2. Record the exact request and the last result shown by the agent.
3. Inspect the destination app for evidence of completion.
4. Note the current screen, selected account, target, network state, and time.
5. Retry only after identifying a failed precondition or incomplete step.

Approval design makes this first response easier because it separates an intended action from an executed action. Our guide to approval confidence and rationale for phone agents explains how visible targets and action summaries help users decide whether to continue, stop, or investigate.

Capture a Minimal Failure Bundle

A useful failure bundle reconstructs the request, trajectory, phone state, and result while keeping private information out of the report. Begin with the original intent in plain language and the expected outcome. Then record what actually happened: which app opened, which target appeared, which tool or action ran, whether an approval was shown, and what the phone displayed afterward.

The AgentDebugX research paper organizes debugging around trajectory-wide investigation because the root cause can precede the visible error. That idea transfers well to Android phone agents. A final timeout might follow an earlier loss of network access. A tool error might follow stale current-screen context. A rejected action might trace back to a permission that Android revoked while the app was idle.

Capture these items when they are available:

• The original request and a short description of the expected result.
• The sequence of visible steps, tools, app transitions, and approvals.
• The last successful step and the first step with an unexpected result.
• The foreground app, screen state, selected account, and target item.
• Relevant permission status, network state, battery restrictions, and notification state.
• A timestamp, device model, Android version, app edition, and installation source.
• The final visible result, error category, and any retry or recovery action already attempted.

A screenshot alone rarely captures enough context. It may show the final dialog while omitting the request, selected contact, permission state, or earlier tool result. Pair a carefully chosen screenshot with a short timeline. Remove passwords, authentication codes, API keys, tokens, full contact details, private message text, precise addresses, and unrelated notifications. The broader guide to AI agent identity, permissions, and audit trails explains how action evidence can remain useful while access stays bounded.

Classify the Failure Layer

Two failures can display the same message and require different repairs. Agent root cause analysis becomes faster when the task is divided into layers. Check each layer against observable phone state instead of assuming that the final error identifies the source.

Android permissions deserve a separate check because users can deny or revoke them and the operating system can reset access. The official Android runtime permission guidance tells apps to check access when it is needed and to continue with a reduced experience when the user declines it. A permission that worked during setup may therefore differ from the permission available during today’s task.

A model failure usually produces a poor interpretation, target, argument, or action order while the required capability remains available. A permission failure occurs when the intended action is valid but Android blocks access to the required resource. A routing failure sits between them: the request may be understood correctly, yet the agent selects a capability that is inactive, unavailable, or mismatched to the current state. The AI Agent Capability Routing on Android: AutoAttach, Suggest, Fallback, and FoneClaw guide explains how AutoAttach, Suggest, and Fallback select an available capability or provide a recovery route when the preferred path cannot continue.

Find the Earliest Causal Step

AgentDebugX describes a four-part loop: Detect, Attribute, Recover, and Rerun. We can adapt that loop to phone workflows by treating the device, Android permissions, foreground app, selected account, approvals, tool results, and external effects as part of the trajectory. The framework guides an investigation; its reported benchmark results apply to the evaluated research settings.

Detect means identifying the first observable departure from the expected workflow. Start with the final error, then trace backward through the visible task history. Find the last step whose input, state, and result were all correct. The following step is the first candidate for investigation.

Attribute means testing the candidate cause against evidence. Prefer read-only checks: inspect whether the permission is granted, verify the foreground app, look for the created calendar event, confirm the current Wi-Fi state, or check whether the intended contact exists. Compare the tool arguments with the original request. If the task used current-screen context, confirm that the context represented the screen where the action was supposed to occur.

Name the cause narrowly and include confidence. A useful conclusion might read: “High confidence: location access was revoked before the nearby-place search; the model selected the correct capability, and the tool reported missing permission.” When evidence remains incomplete, retain alternatives: “Medium confidence: the message may have been sent before result verification timed out; check the conversation before retrying.” This format prevents a plausible explanation from being treated as certainty.

Strict attribution remains difficult when several states change together. An app can move to the background while the network drops and an approval expires. In that case, restore one precondition at a time and use read-only checks between changes. Builders who want to turn these incidents into repeatable measurements can use our Android Phone Agent Benchmark Guide: Reliability, Safety, and Task Success to define observable success, recovery, and verification criteria.

Recover Without Duplicating Completed Effects

Once the earliest causal step is identified, recover the missing precondition and rerun the smallest safe suffix of the task. First inspect what has already completed. A send operation may have succeeded even when confirmation failed. A calendar event may exist even though the agent lost focus before displaying it. A setting may already hold the requested value.

Use this recovery ladder:

1. Verify external effects: Check the destination conversation, call history, calendar, file list, system setting, or service account.
2. Restore the failed precondition: Regrant the required permission, unlock the phone, reopen the correct app, select the correct account, reconnect the network, or return the target item to the foreground.
3. Reconfirm the target: Verify the recipient, date, file, device, setting, and proposed value.
4. Retry the failed step: Repeat a read-only or reversible action after checking current state. For a consequential action, use a fresh approval that describes the exact effect.
5. Verify the result: Read the returned state and inspect the destination when confirmation remains uncertain.
6. Stop at a new failure: Capture the new evidence instead of escalating into repeated execution.

Permission recovery may require opening Android settings after access has been permanently denied or reset. If the user declines access, continue through a supported reduced path, such as opening the system app for manual completion. Android’s model expects graceful degradation, so recovery should explain which capability needs access and what alternative remains available.

Task queues add another consideration: a later step may be waiting on an earlier one. Resume only the affected task and preserve isolation from unrelated conversations or queued jobs. Our guide to multi-conversation Android agent task queues explains how running, waiting, stopped, and approval states should remain attached to the correct conversation.

Use FoneClaw Controls to Diagnose and Recover

Building FoneClaw has taught us that recovery works best when the user can return to the same task, see the current state, and repair a specific precondition. We support governed Android workflows across 100+ built-in tools, with visible results for supported phone state, communication, settings, workflow, and extension capabilities. Each action still depends on its Android permission, current device state, active account, and supported route.

Begin by returning to the conversation or floating assistant task where the failure occurred. Check whether the task is running, waiting for approval, stopped, or displaying a tool result. Keeping that continuity prevents a retry from becoming an unrelated new request with missing context.

When screen state caused the failure, open the correct app and page, then attach the current screen deliberately from the floating assistant. FoneClaw uses that selected context to understand the visible state while keeping the user in control of when the screen is shared. The Android Floating AI Assistant: Use Current-Screen Context Safely guide covers the practical context, review, and cross-app workflow in more depth.

Next, inspect the approval and tool result. Confirm the target, action, requested permission, and any result already returned. Use the stop control when the plan is continuing through an incorrect route. If Android blocks a required permission, follow the permission recovery path, return to the same task, and verify that the affected capability can now read or change the intended state.

Use retry after repairing the precondition. A read-only status check can usually be repeated immediately. A reversible setting change should begin by reading its current value. A message, call, deletion, calendar change, or other consequential effect should begin with destination verification and a fresh review of the target. Our retry controls keep the action visible so the user can evaluate the proposed step before it continues.

Finish with a state check. Read the resulting volume, connectivity, event, message destination, app state, or other observable outcome. When the tool result and destination disagree, preserve both pieces of evidence and stop. The current FoneClaw Features page lists the supported capability families that can participate in these workflows.

Create a Useful Support or Bug Report

Escalate when the same repaired precondition produces the same failure, when the result conflicts with the destination state, when a consequential effect cannot be verified, or when recovery requires changing data you cannot safely reconstruct. Repeated crashes, incorrect targets, cross-task state leakage, approval mismatches, and permission loops also deserve a reproducible report.

Use this redacted support bundle:

• Intent: The exact task in sanitized form.
• Expected result: One observable completion condition.
• Actual result: The last successful step and surfaced error.
• Timeline: App transitions, approvals, tools, retries, and timestamps.
• Environment: Device model, Android version, app edition, installation source, network type, and battery restrictions.
• Permissions: Relevant granted, denied, or reset access.
• Reproduction: The shortest sequence that produces the problem.
• Evidence: Redacted screenshots and visible tool results.

Remove credentials, tokens, authentication codes, private contacts, message content, exact locations, account identifiers, and unrelated screen information unless a specific item is essential and the user has approved sharing it. State what was redacted so support can distinguish missing evidence from unavailable state.

Prevent Recurrence With Acceptance Tests

Turn a repaired incident into a small acceptance test. Record the request, required preconditions, expected approval, observable external effect, and final verification. Run the case once under the normal configuration and again after changing one relevant state.

The official Android app permission best practices recommend testing flows with both granted and revoked permission combinations. For a phone agent, add cases for temporary denial, permanent denial, permission reset, locked and unlocked screens, foreground changes, network loss, account changes, interrupted approvals, and an app interface that opens on an unexpected page.

Include ambiguity tests as well. Use duplicate contact names, multiple calendars, several map apps, or two similarly named files where those states are realistic. The expected behavior should be a clarifying question or visible target selection before a consequential action. Then interrupt the task after planning, after approval, and after the external effect but before verification. Each test should define whether retry is allowed, which state must be checked first, and what evidence confirms success.

One successful rerun closes the immediate incident. A durable regression case checks the original failure state, the repaired state, and the recovery path after future Android, app, permission, or interface changes. Builders developing broader evaluation systems can continue with our guide to governed phone-agent test harnesses, which explains how reviewed failure cases can improve acceptance coverage while keeping consequential changes under human control.