Resolve Bugs from Your IDE

Once the proxy is logged in with the agent:resolve scope, a coding agent can close bugs directly from your chat — no browser required.

Heads up: If you want bugs to close automatically when you push a commit with Fixes CP-<n>, see Auto-close via commit — no IDE plugin or MCP call needed.

Prerequisite: clickprobe-proxy login with agent:resolve in the consent screen. If your current token lacks the scope, re-run login and re-consent. See troubleshooting.md for 403 and scope errors.

Three-tool cheat sheet

Full parameter schemas for each tool are in the quick-reference sections below.

⚠ Prerequisites — bug FSM. Freshly-filed bugs land in status new. The server FSM forbids new → resolved; resolve_bug requires the bug to be in confirmed, retesting, or exported first. If the agent calls resolve_bug on a new bug, the response is HTTP 422 with body:

{"detail": {"reason": "illegal_transition", "current": "new", "allowed": ["confirmed", "dismissed", "exported", "retesting"]}}

To advance a new bug to confirmed, either:

• Ask the operator to click Confirm in the dashboard, or
• PATCH /api/bugs/{bug_id} with body {"status": "confirmed"} using the operator’s session cookie (this is not an MCP tool in v1).

See the worked example below (“Workflow: confirming a new bug before resolving it”) for the recommended sequence.

clickprobe.resolve_bug — quick reference

{
  "tool": "clickprobe.resolve_bug",
  "arguments": {
    "bug_id":     "<uuid>",
    "resolution": "resolved",
    "commit_sha": "abc1234",
    "notes":      "Fixed null dereference in checkout — PR #42"
  }
}

resolution is one of resolved, wont_fix, or duplicate. commit_sha and notes are optional.

clickprobe.annotate_bug — quick reference

{
  "tool": "clickprobe.annotate_bug",
  "arguments": {
    "bug_id": "<uuid>",
    "note":   "Investigated — root cause is a race condition in the cart reducer."
  }
}

clickprobe.link_pr — quick reference

{
  "tool": "clickprobe.link_pr",
  "arguments": {
    "bug_id":     "<uuid>",
    "pr_url":     "https://github.com/acme/app/pull/42",
    "commit_sha": "abc1234"
  }
}

Workflow: confirming a new bug before resolving it

Session-runner-filed bugs land in status new. The recommended sequence for a coding agent is:

1. Agent: clickprobe.get_bug_detail(bug_id="abc-123")
   → returns { ..., "status": "new", ... }
   → agent observes the bug is unconfirmed.

2. Agent: writes the fix locally; runs tests; commits as "abc1234".

3. Operator (human): opens https://app.clickprobe.ai/app/bugs/abc-123 and
   clicks Confirm. The bug moves to status `confirmed`.

   Equivalent API call (operator-auth, not token-auth):
     PATCH /api/bugs/abc-123
     Cookie: <operator session>
     Body:   {"status": "confirmed"}

4. Agent: clickprobe.resolve_bug(
       bug_id="abc-123",
       resolution="resolved",
       commit_sha="abc1234",
       notes="Fixed null deref in cart_reducer.ts"
   )
   → 200 OK, bug is now `resolved`.

Why the operator step? The Confirm gate is a deliberate quality bar — a human reviews the screenshot + repro steps before downstream automation acts.

Future direction. A clickprobe.confirm_bug MCP tool that lets the agent confirm without an operator round-trip is on the C-014 follow-up backlog (C-014-F01); whether to ship it is a v1.x decision driven by beta-customer feedback.

End-to-end example transcript

This is a copy-pasteable Claude Code session that walks through finding and resolving a bug. Replace the bug UUID and repo URL with your own values.

User: Fix the checkout null-pointer crash — it's tracked in ClickProbe.

Claude:
  1. Let me fetch the open bugs.

     [calls clickprobe.get_bugs with status=new]
     → returns list including bug abc-123: "Null pointer on /checkout"

  2. Getting the full detail and repro steps.

     [calls clickprobe.get_bug_detail with bug_id="abc-123"]
     → repro: "Add item to cart → checkout → crash at cart_reducer.ts:42"

  3. I can see the issue — `items` is undefined when the cart is empty.
     Adding a guard:

     [edits cart_reducer.ts, adds `items ?? []` guard]
     [runs tests — pass]

  4. Annotating the bug with a summary before I close it.

     [calls clickprobe.annotate_bug]
     arguments: { bug_id: "abc-123", note: "Root cause: items undefined on empty cart. Fixed with nullish coalescing in cart_reducer.ts:42." }

  5. Resolving the bug with the fix commit SHA.

     [calls clickprobe.resolve_bug]
     arguments: { bug_id: "abc-123", resolution: "resolved", commit_sha: "a1b2c3d4e5f6", notes: "Fixed in cart_reducer.ts — PR #42" }

  6. Linking the PR for traceability.

     [calls clickprobe.link_pr]
     arguments: { bug_id: "abc-123", pr_url: "https://github.com/acme/app/pull/42", commit_sha: "a1b2c3d4e5f6" }

     → Bug abc-123 is now resolved. The ClickProbe dashboard shows the
       "Resolved" badge, the commit chip "a1b2c3", and the PR link.
       A Slack notification fires if a webhook is configured.

Troubleshooting

403 — missing scope

this token lacks required scope "agent:resolve"; run 'clickprobe-proxy login' to re-consent

Re-run clickprobe-proxy login. On the consent screen make sure agent:resolve is checked alongside agent:read and agent:write.

422 — illegal transition

{"detail": {"reason": "illegal_transition", "current": "new", "allowed": ["confirmed", "dismissed", "exported", "retesting"]}}

The bug must be in confirmed, retesting, or exported status before it can be resolved. Most commonly: confirm the bug first via the dashboard, then retry resolve_bug. The full troubleshooting recipe is in troubleshooting.md § 9.

422 — invalid PR URL

{"detail":"pr_url must start with http:// or https://"}

Pass a full https:// URL. SSH URLs and bare paths are not accepted.