solve_visual_challenge
Resolves visual CAPTCHA challenges by applying tile selections, executing clicks, and returning pass/fail status. Handles dynamic image replacement for multi-round puzzles.
Instructions
Apply the AI client's tile selection, execute the click chain, click Verify, wait for the reCAPTCHA token, and return the outcome. Pairs with inspect_visual_challenge — must be called with the challenge_id returned by the previous inspect call.
Requires confirm: true as a safety latch — an accidental call without confirm returns confirm_required without clicking anything. Also requires QA_VISUAL_CHALLENGE_CONSENT=true at the server level.
DYNAMIC-REPLACE MODE (v0.7.4): when the challenge prompt says 'Click verify once there are none left' (en) / '確定沒有遺漏' (zh), clicked tiles get replaced with new images. solve detects this and returns status: 'continue' with a FRESH screenshot + tile grid instead of clicking Verify. The AI should look at the new screenshot and call solve again with the next matches. To finalize (click Verify and check for a token), pass an empty selected_tile_indices: [].
Returns: {status: 'passed' | 'continue' | 'failed' | 'expired' | 'consent_required' | 'confirm_required' | 'challenge_not_found' | 'error', challenge_id, attempts_remaining, token (only on passed), hint, plus on 'continue': screenshot_base64, tiles, tile_count, grid_layout, rounds_used}. Telemetry logs the boolean outcome only — no screenshots, no challenge text, no tile selection are ever persisted.
Plan bookend (v0.10.0): pass plan_id from a prior qa_plan call and the response auto-attaches plan_verification. Evidence is a single-record summary {kind: 'captcha_solve', status, token_populated, rounds_used, fingerprint, challenge_id} — the raw token is NEVER included (telemetry hygiene). Verification only fires once solve actually executes; consent_required / confirm_required / challenge_not_found / expired all bypass it because they're usage errors, not solve outcomes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| challenge_id | Yes | Required. The challenge_id returned by inspect_visual_challenge. Expires after 5 minutes; re-inspect to get a fresh id. | |
| selected_tile_indices | Yes | Required. The tiles the AI client wants to click, by index (0..tile_count-1). For a 3x3 grid: tile 0 = top-left, 4 = center, 8 = bottom-right. For a 4x4 grid: 0..15 row-major. | |
| confirm | No | Safety latch. MUST be set to true for the click chain to execute. Without it, returns `confirm_required` and clicks nothing — this prevents an accidental tool call from auto-submitting a CAPTCHA. | |
| plan_id | No | 選填，v0.10.0+. Plan id returned by qa_plan. When supplied AND solve actually executes, the response gains a `plan_verification` envelope with single-record evidence {kind: 'captcha_solve', status, token_populated, rounds_used, fingerprint, challenge_id}. Raw token never appears in evidence — CPs check token_populated. |