Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat(mcp): register pinchtab_handoff, pinchtab_resume and pinchtab_handoff_status (PIN-345)

Luigi Agosti173a53517dd4
diff --git a/docs/mcp.md b/docs/mcp.md
index 905f91d4..174a18cf 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -114,7 +114,7 @@ PINCHTAB_TOKEN=<that-host-token> pinchtab --server http://remote:9867 mcp
## Available Tools
-PinchTab currently exposes 39 tools:
+PinchTab currently exposes 42 tools:
- Navigation: 9
- Interaction: 8
@@ -123,6 +123,7 @@ PinchTab currently exposes 39 tools:
- Recording: 1
- Site: 1
- Tab management: 5
+- Human handoff: 3
- Wait utilities: 1
- Network: 5
- Diagnostics: 2
@@ -178,6 +179,12 @@ PinchTab currently exposes 39 tools:
- `pinchtab_cookies_set` (requires `security.allowCookies`)
- `pinchtab_connect_profile`
+### Human Handoff
+
+- `pinchtab_handoff` — pause a tab (`tabId` required; `reason`, `timeoutMs` optional) so a human can finish a CAPTCHA, login or consent step; every action tool on that tab is refused with `tab_paused_handoff` until it resumes
+- `pinchtab_resume` — resume the tab (`tabId` required; `status` optional). Call it only after the user confirms they finished
+- `pinchtab_handoff_status` — report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`, so an agent can watch a `timeoutMs` auto-resume without resuming itself
+
### Wait Utilities
- `pinchtab_wait` — `for` is `ms`, `selector`, `text`, `url`, `load` or `function`, and `value` carries the condition
@@ -219,7 +226,7 @@ The normal MCP browser loop is:
1. Call `pinchtab_navigate` with a `url`
2. Call `pinchtab_snapshot` to inspect page structure and collect refs
3. Call `pinchtab_click`, `pinchtab_type`, or other action tools with structured arguments
-4. Call `pinchtab_wait_*` or `pinchtab_network` when needed
+4. Call `pinchtab_wait` or `pinchtab_network` when needed
5. Call `pinchtab_back` to leave a dead end, or `pinchtab_reload` to retry the page
`pinchtab_back`, `pinchtab_forward` and `pinchtab_reload` take an optional `tabId`
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index c3577e01..5a64b068 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -78,6 +78,14 @@ All element-action tools accept the unified `selector` and the legacy aliases `r
| `pinchtab_cookies_set` | `name`, `value` required; `url`, `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId` optional | Sets one cookie for session reuse; `url` defaults to the tab's current page and an empty `value` blanks the cookie; requires `security.allowCookies` |
| `pinchtab_connect_profile` | `profile` required | Returns the connect URL and instance status for a profile |
+## Human Handoff
+
+| Tool | Key Parameters | Notes |
+| --- | --- | --- |
+| `pinchtab_handoff` | `tabId` required; `reason`, `timeoutMs` optional | Pauses the tab for a human (CAPTCHA, login, consent); action tools on it answer `409 tab_paused_handoff` until resumed; `timeoutMs` auto-resumes |
+| `pinchtab_resume` | `tabId` required; `status` optional | Resumes the tab; call only after the user confirms they finished the manual step |
+| `pinchtab_handoff_status` | `tabId` required | Reports `paused_handoff` with `reason`, `pausedAt` and `expiresAt`, or `active` |
+
## Wait Utilities
| Tool | Key Parameters | Notes |
diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.go
index 84819106..b78857e9 100644
--- a/internal/mcp/handlers.go
+++ b/internal/mcp/handlers.go
@@ -54,6 +54,9 @@ func rawHandlerMap(c *Client) map[string]func(context.Context, mcp.CallToolReque
"pinchtab_cookies": handleCookies(c),
"pinchtab_cookies_set": handleCookiesSet(c),
"pinchtab_connect_profile": handleConnectProfile(c),
+ "pinchtab_handoff": handleHandoff(c),
+ "pinchtab_resume": handleResume(c),
+ "pinchtab_handoff_status": handleHandoffStatus(c),
"pinchtab_wait": handleWait(c),
diff --git a/internal/mcp/handlers_tabs.go b/internal/mcp/handlers_tabs.go
index 04572701..33707578 100644
--- a/internal/mcp/handlers_tabs.go
+++ b/internal/mcp/handlers_tabs.go
@@ -34,6 +34,63 @@ func handleCloseTab(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.
}
}
+func tabRoutePath(tabID, verb string) string {
+ return "/tabs/" + url.PathEscape(tabID) + "/" + verb
+}
+
+func handleHandoff(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ tabID, err := r.RequireString("tabId")
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ payload := map[string]any{}
+ if reason := optTrimmedString(r, "reason"); reason != "" {
+ payload["reason"] = reason
+ }
+ if timeoutMs, ok := optInt(r, "timeoutMs"); ok {
+ payload["timeoutMs"] = timeoutMs
+ }
+ body, code, err := c.Post(ctx, tabRoutePath(tabID, "handoff"), payload)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
+
+func handleResume(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ tabID, err := r.RequireString("tabId")
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ payload := map[string]any{}
+ if status := optTrimmedString(r, "status"); status != "" {
+ payload["status"] = status
+ }
+ body, code, err := c.Post(ctx, tabRoutePath(tabID, "resume"), payload)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
+
+func handleHandoffStatus(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ tabID, err := r.RequireString("tabId")
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ body, code, err := c.Get(ctx, tabRoutePath(tabID, "handoff"), nil)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ return resultFromBytes(body, code)
+ }
+}
+
func handleHealth(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return func(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {
body, code, err := c.Get(ctx, "/health", nil)
diff --git a/internal/mcp/handoff_tools_test.go b/internal/mcp/handoff_tools_test.go
new file mode 100644
index 00000000..0677f5b3
--- /dev/null
+++ b/internal/mcp/handoff_tools_test.go
@@ -0,0 +1,192 @@
+package mcp
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/handlers"
+ "github.com/pinchtab/pinchtab/internal/testbrowser"
+)
+
+func decodeToolJSON(t *testing.T, name string, args map[string]any, api *httptest.Server) (map[string]any, bool) {
+ t.Helper()
+ result := callTool(t, name, args, api)
+ text := resultText(t, result)
+ if start := strings.Index(text, "{"); start > 0 {
+ text = text[start:]
+ }
+ var body map[string]any
+ if err := json.Unmarshal([]byte(text), &body); err != nil {
+ t.Fatalf("%s answered non-JSON %q", name, text)
+ }
+ return body, result.IsError
+}
+
+func TestAnAgentRecoversFromAHandoffRefusalThroughTheMCPToolsAlone(t *testing.T) {
+ page := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/html; charset=utf-8")
+ _, _ = w.Write([]byte(`<button id="go" onclick="this.textContent='clicked'">go</button>`))
+ }))
+ defer page.Close()
+
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(testbrowser.Path(t)),
+ chromedp.UserDataDir(testbrowser.ProfileDir(t)),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ browserCtx, cancelBrowser := chromedp.NewContext(alloc)
+ browserCtx, cancelTimeout := context.WithTimeout(browserCtx, 30*time.Second)
+ defer cancelTimeout()
+ defer cancelBrowser()
+ defer cancelAlloc()
+ if err := chromedp.Run(browserCtx); err != nil {
+ t.Fatalf("start test browser: %v", err)
+ }
+ cfg := &config.RuntimeConfig{ActionTimeout: 10 * time.Second, DefaultBrowser: config.BrowserChrome, StateDir: t.TempDir()}
+ b := bridge.New(context.Background(), browserCtx, cfg)
+ tabID, _, _, err := b.CreateTab(page.URL)
+ if err != nil {
+ t.Fatalf("create tab: %v", err)
+ }
+ mux := http.NewServeMux()
+ handlers.New(b, cfg, nil, nil, nil).RegisterRoutes(mux, func() {})
+ api := httptest.NewServer(mux)
+ defer api.Close()
+ click := map[string]any{"tabId": tabID, "selector": "#go"}
+
+ paused, isErr := decodeToolJSON(t, "pinchtab_handoff", map[string]any{"tabId": tabID, "reason": "captcha_manual"}, api)
+ if isErr || paused["status"] != "paused_handoff" || paused["reason"] != "captcha_manual" {
+ t.Fatalf("pinchtab_handoff = %v (error=%v), want paused_handoff with the reason", paused, isErr)
+ }
+
+ refused, isErr := decodeToolJSON(t, "pinchtab_click", click, api)
+ if !isErr || refused["code"] != "tab_paused_handoff" {
+ t.Fatalf("click on a paused tab = %v (error=%v), want the tab_paused_handoff refusal", refused, isErr)
+ }
+
+ status, isErr := decodeToolJSON(t, "pinchtab_handoff_status", map[string]any{"tabId": tabID}, api)
+ if isErr || status["status"] != "paused_handoff" || status["reason"] != "captcha_manual" {
+ t.Fatalf("pinchtab_handoff_status while paused = %v (error=%v), want paused_handoff", status, isErr)
+ }
+
+ resumed, isErr := decodeToolJSON(t, "pinchtab_resume", map[string]any{"tabId": tabID, "status": "completed"}, api)
+ if isErr || resumed["status"] != "active" || resumed["resumeStatus"] != "completed" {
+ t.Fatalf("pinchtab_resume = %v (error=%v), want active carrying the status note", resumed, isErr)
+ }
+
+ status, isErr = decodeToolJSON(t, "pinchtab_handoff_status", map[string]any{"tabId": tabID}, api)
+ if isErr || status["status"] != "active" {
+ t.Fatalf("pinchtab_handoff_status after resume = %v (error=%v), want active", status, isErr)
+ }
+
+ clicked, isErr := decodeToolJSON(t, "pinchtab_click", click, api)
+ if isErr {
+ t.Fatalf("click after resume refused: %v", clicked)
+ }
+ text := resultText(t, callTool(t, "pinchtab_get_text", map[string]any{"tabId": tabID}, api))
+ if !strings.Contains(text, "clicked") {
+ t.Fatalf("page text after the resumed click = %q, want the button relabelled by the click", text)
+ }
+}
+
+func TestHandoffToolsRequireATabAndForwardTheirParameters(t *testing.T) {
+ type seen struct {
+ method, path string
+ body map[string]any
+ }
+ var last seen
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ last = seen{method: r.Method, path: r.URL.EscapedPath(), body: map[string]any{}}
+ _ = json.NewDecoder(r.Body).Decode(&last.body)
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"tabId":"t1","status":"active"}`))
+ }))
+ defer srv.Close()
+
+ for _, tc := range []struct {
+ tool string
+ args map[string]any
+ method string
+ path string
+ body map[string]any
+ }{
+ {"pinchtab_handoff", map[string]any{"tabId": "t/1", "reason": " login_required ", "timeoutMs": float64(1500)}, http.MethodPost, "/tabs/t%2F1/handoff", map[string]any{"reason": "login_required", "timeoutMs": float64(1500)}},
+ {"pinchtab_handoff", map[string]any{"tabId": "t1"}, http.MethodPost, "/tabs/t1/handoff", map[string]any{}},
+ {"pinchtab_resume", map[string]any{"tabId": "t1", "status": "completed"}, http.MethodPost, "/tabs/t1/resume", map[string]any{"status": "completed"}},
+ {"pinchtab_handoff_status", map[string]any{"tabId": "t1"}, http.MethodGet, "/tabs/t1/handoff", map[string]any{}},
+ } {
+ t.Run(tc.tool, func(t *testing.T) {
+ last = seen{}
+ if result := callTool(t, tc.tool, tc.args, srv); result.IsError {
+ t.Fatalf("%s errored: %s", tc.tool, resultText(t, result))
+ }
+ if last.method != tc.method || last.path != tc.path {
+ t.Fatalf("%s sent %s %s, want %s %s", tc.tool, last.method, last.path, tc.method, tc.path)
+ }
+ for k, want := range tc.body {
+ if last.body[k] != want {
+ t.Errorf("%s body[%s] = %v, want %v", tc.tool, k, last.body[k], want)
+ }
+ }
+ for k := range last.body {
+ if _, declared := tc.body[k]; !declared {
+ t.Errorf("%s sent undeclared body field %s=%v", tc.tool, k, last.body[k])
+ }
+ }
+ without := callTool(t, tc.tool, map[string]any{}, srv)
+ if !without.IsError || last.method != tc.method {
+ t.Fatalf("%s without a tabId did not refuse before forwarding", tc.tool)
+ }
+ })
+ }
+}
+
+func TestEveryToolNameInTheAgentFacingDocsResolves(t *testing.T) {
+ registered := map[string]bool{}
+ for _, tool := range allTools() {
+ registered[tool.Name] = true
+ }
+ name := regexp.MustCompile(`pinchtab_[a-z][a-z0-9_]*`)
+ root := filepath.Join("..", "..")
+ for _, doc := range []string{
+ "docs/mcp.md",
+ "docs/reference/mcp-tools.md",
+ "skills/pinchtab/references/mcp.md",
+ "skills/pinchtab-mcp/SKILL.md",
+ } {
+ data, err := os.ReadFile(filepath.Join(root, doc))
+ if err != nil {
+ t.Fatal(err)
+ }
+ found := map[string]bool{}
+ for _, hit := range name.FindAllString(string(data), -1) {
+ found[strings.TrimRight(hit, "_")] = true
+ }
+ if len(found) == 0 {
+ t.Fatalf("%s names no tool; the census is checking nothing", doc)
+ }
+ for _, tool := range []string{"pinchtab_handoff", "pinchtab_resume", "pinchtab_handoff_status"} {
+ if !found[tool] {
+ t.Errorf("%s does not document %s", doc, tool)
+ }
+ }
+ for hit := range found {
+ if !registered[hit] {
+ t.Errorf("%s names %s, which is not a registered tool", doc, hit)
+ }
+ }
+ }
+}
diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go
index 74ece2ec..73ea0f61 100644
--- a/internal/mcp/server_test.go
+++ b/internal/mcp/server_test.go
@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {
// The server should have registered all tools.
// We verify by checking that NewServer doesn't panic — the panic
// in NewServer fires if any tool lacks a handler.
- if len(tools) != 39 {
- t.Errorf("expected 39 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))
+ if len(tools) != 42 {
+ t.Errorf("expected 42 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))
}
}
diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.json
index 4cb2c7f3..967183f7 100644
--- a/internal/mcp/testdata/preamble_budget.json
+++ b/internal/mcp/testdata/preamble_budget.json
@@ -2,16 +2,16 @@
{
"surface": "mcp:allTools",
"minBytes": 18092,
- "maxBytes": 38200,
+ "maxBytes": 40000,
"takenOn": "2026-09-11",
- "commit": "d866267e"
+ "commit": "1e7b8132"
},
{
"surface": "skills/pinchtab-mcp/SKILL.md",
"minBytes": 6789,
- "maxBytes": 14581,
- "takenOn": "2026-09-03",
- "commit": "8a12cd4a"
+ "maxBytes": 15200,
+ "takenOn": "2026-09-11",
+ "commit": "1e7b8132"
},
{
"surface": "skills/pinchtab/SKILL.md",
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index e2cb5b31..1b2f7b17 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -237,6 +237,21 @@ func allTools() []mcp.Tool {
mcp.NewTool("pinchtab_health",
mcp.WithDescription("Check PinchTab server health status"),
),
+ mcp.NewTool("pinchtab_handoff",
+ mcp.WithDescription("Pause a tab for human handoff (a CAPTCHA, a login, a consent wall the agent must not solve). While paused every action tool on that tab is refused with tab_paused_handoff. Return control to the user, ask them to finish in the browser, then call pinchtab_resume. Other tabs are unaffected."),
+ requiredTabIDParam(),
+ mcp.WithString("reason", mcp.Description("Why the tab is handed off, e.g. captcha_manual or login_required (default manual_handoff)")),
+ mcp.WithNumber("timeoutMs", mcp.Description("Optional auto-resume after this many milliseconds; 0 or omitted means the tab stays paused until pinchtab_resume")),
+ ),
+ mcp.NewTool("pinchtab_resume",
+ mcp.WithDescription("Resume a tab paused for human handoff so action tools work again. Call it only after the user has confirmed they finished the manual step; check with pinchtab_handoff_status first when unsure."),
+ requiredTabIDParam(),
+ mcp.WithString("status", mcp.Description("Optional note recorded with the resume, e.g. completed or failed")),
+ ),
+ mcp.NewTool("pinchtab_handoff_status",
+ mcp.WithDescription("Report a tab's handoff state: status paused_handoff with reason, pausedAt and any expiresAt while a human holds it, or status active once resumed or auto-resumed by its timeout."),
+ requiredTabIDParam(),
+ ),
mcp.NewTool("pinchtab_cookies",
mcp.WithDescription("Get cookies for the current page"),
tabIDParam(),
diff --git a/plugins/grok/skills/pinchtab-mcp/SKILL.md b/plugins/grok/skills/pinchtab-mcp/SKILL.md
index 364050af..fc8d7588 100644
--- a/plugins/grok/skills/pinchtab-mcp/SKILL.md
+++ b/plugins/grok/skills/pinchtab-mcp/SKILL.md
@@ -289,6 +289,19 @@ pinchtab_close_tab(tabId="...") # Close a specific tab
---
+## Human Handoff
+
+```
+pinchtab_handoff(tabId="...", reason="captcha_manual") # Pause the tab; action tools answer tab_paused_handoff
+pinchtab_handoff_status(tabId="...") # paused_handoff (reason, pausedAt, expiresAt) or active
+pinchtab_resume(tabId="...") # Only after the user confirms they finished
+```
+
+- When an action is refused with `tab_paused_handoff`, hand control to the user and ask them to finish in the browser.
+- Resume only once the user says they are done; a `timeoutMs` handoff resumes on its own, which `pinchtab_handoff_status` shows.
+
+---
+
## Waiting
Use for async content (spinners, XHR, lazy-loaded elements):
diff --git a/plugins/grok/skills/pinchtab/references/mcp.md b/plugins/grok/skills/pinchtab/references/mcp.md
index 42f69cf1..fb35acca 100644
--- a/plugins/grok/skills/pinchtab/references/mcp.md
+++ b/plugins/grok/skills/pinchtab/references/mcp.md
@@ -63,7 +63,6 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch` as a broad low-level escape hatch), `tabId`. `mode` and `humanize` are mutually exclusive. |
| `pinchtab_type` | Type text keystroke-by-keystroke. Required: `selector` or legacy `ref`, plus `text`. Optional: `tabId`. |
| `pinchtab_fill` | Fill input via JS dispatch. Required: `selector` or legacy `ref`, plus `value` — send `value=""` to clear the field (omitting it is refused). Optional: `tabId`. |
-| `pinchtab_press` | Press a named key (`Enter`, `Tab`, `Escape`, etc.). Required: `key`. Optional: `tabId`. |
| `pinchtab_hover` | Hover over element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_focus` | Focus an element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_select` | Select dropdown option. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |
@@ -72,10 +71,7 @@ All tool names are prefixed with `pinchtab_`.
### Keyboard
| Tool | Description |
|------|-------------|
-| `pinchtab_keyboard_type` | Type text into the focused element with keystroke events. Required: `text`. Optional: `tabId`. |
-| `pinchtab_keyboard_inserttext` | Insert text into the focused element without key events. Required: `text`. Optional: `tabId`. |
-| `pinchtab_keydown` | Hold a key down. Required: `key`. Optional: `tabId`. |
-| `pinchtab_keyup` | Release a key. Required: `key`. Optional: `tabId`. |
+| `pinchtab_key` | Send keyboard input. Required: `action` (`press`, `down`, `up` need `key`; `type`, `insert` need `text`). Optional: `nodeId`, `tabId`. |
### Content
| Tool | Description |
@@ -94,15 +90,17 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_cookies_set` | Set one cookie on the current page (session reuse). Required: `name`, `value`. Optional: `url` (defaults to the tab's current page), `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId`. An empty `value` blanks the cookie. Requires `security.allowCookies: true`. |
| `pinchtab_connect_profile` | Return connect status for a profile. Required: `profile`. |
+### Human Handoff
+| Tool | Description |
+|------|-------------|
+| `pinchtab_handoff` | Pause a tab so the user can finish a CAPTCHA, login or consent step; action tools on it are refused with `tab_paused_handoff` until resumed. Required: `tabId`. Optional: `reason`, `timeoutMs` (auto-resume). |
+| `pinchtab_resume` | Resume a paused tab. Call only after the user confirms they finished. Required: `tabId`. Optional: `status`. |
+| `pinchtab_handoff_status` | Report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`. Required: `tabId`. |
+
### Utility
| Tool | Description |
|------|-------------|
-| `pinchtab_wait` | Wait N milliseconds. Required: `ms` (max 30000). |
-| `pinchtab_wait_for_selector` | Wait for selector to appear or disappear. Required: `selector`. Optional: `timeout`, `state`, `tabId`. |
-| `pinchtab_wait_for_text` | Wait for text to appear. Required: `text`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_url` | Wait for a URL glob match. Required: `url`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_load` | Wait for a load state. Required: `load`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_function` | Wait for a JavaScript expression to become truthy. Required: `fn`. Optional: `timeout`, `tabId`. |
+| `pinchtab_wait` | Wait for a condition. Required: `for` (`ms`, `selector`, `text`, `url`, `load` or `function`) and `value` carrying it. Optional: `timeout`, `state`, `tabId`. |
### Network
| Tool | Description |
@@ -110,7 +108,6 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_network` | List recent captured network requests. Optional: `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize`. |
| `pinchtab_network_detail` | Get one request's details. Required: `requestId`. Optional: `tabId`, `body`; inspect bodies only with explicit user approval. |
| `pinchtab_network_clear` | Clear captured network data. Optional: `tabId`. |
-| `pinchtab_network_export` | Export captured data as HAR or NDJSON file. Optional: `tabId`, `format` (har/ndjson), `body`, `filter`, `method`, `status`, `type`, `limit`. Obtain explicit approval, preserve redaction, and delete the artifact after use. Returns `{path, entries, format}`. |
### Dialog
| Tool | Description |
diff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.md
index 364050af..fc8d7588 100644
--- a/skills/pinchtab-mcp/SKILL.md
+++ b/skills/pinchtab-mcp/SKILL.md
@@ -289,6 +289,19 @@ pinchtab_close_tab(tabId="...") # Close a specific tab
---
+## Human Handoff
+
+```
+pinchtab_handoff(tabId="...", reason="captcha_manual") # Pause the tab; action tools answer tab_paused_handoff
+pinchtab_handoff_status(tabId="...") # paused_handoff (reason, pausedAt, expiresAt) or active
+pinchtab_resume(tabId="...") # Only after the user confirms they finished
+```
+
+- When an action is refused with `tab_paused_handoff`, hand control to the user and ask them to finish in the browser.
+- Resume only once the user says they are done; a `timeoutMs` handoff resumes on its own, which `pinchtab_handoff_status` shows.
+
+---
+
## Waiting
Use for async content (spinners, XHR, lazy-loaded elements):
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 42f69cf1..fb35acca 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -63,7 +63,6 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_click` | Click element by selector. Required: `selector` or legacy `ref`. Optional: `waitNav`, `mode` (`dom` or `dispatch` as a broad low-level escape hatch), `tabId`. `mode` and `humanize` are mutually exclusive. |
| `pinchtab_type` | Type text keystroke-by-keystroke. Required: `selector` or legacy `ref`, plus `text`. Optional: `tabId`. |
| `pinchtab_fill` | Fill input via JS dispatch. Required: `selector` or legacy `ref`, plus `value` — send `value=""` to clear the field (omitting it is refused). Optional: `tabId`. |
-| `pinchtab_press` | Press a named key (`Enter`, `Tab`, `Escape`, etc.). Required: `key`. Optional: `tabId`. |
| `pinchtab_hover` | Hover over element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_focus` | Focus an element. Required: `selector` or legacy `ref`. Optional: `tabId`. |
| `pinchtab_select` | Select dropdown option. Required: `selector` or legacy `ref`, plus `value`. Optional: `tabId`. |
@@ -72,10 +71,7 @@ All tool names are prefixed with `pinchtab_`.
### Keyboard
| Tool | Description |
|------|-------------|
-| `pinchtab_keyboard_type` | Type text into the focused element with keystroke events. Required: `text`. Optional: `tabId`. |
-| `pinchtab_keyboard_inserttext` | Insert text into the focused element without key events. Required: `text`. Optional: `tabId`. |
-| `pinchtab_keydown` | Hold a key down. Required: `key`. Optional: `tabId`. |
-| `pinchtab_keyup` | Release a key. Required: `key`. Optional: `tabId`. |
+| `pinchtab_key` | Send keyboard input. Required: `action` (`press`, `down`, `up` need `key`; `type`, `insert` need `text`). Optional: `nodeId`, `tabId`. |
### Content
| Tool | Description |
@@ -94,15 +90,17 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_cookies_set` | Set one cookie on the current page (session reuse). Required: `name`, `value`. Optional: `url` (defaults to the tab's current page), `domain`, `path`, `sameSite`, `secure`, `httpOnly`, `expires`, `tabId`. An empty `value` blanks the cookie. Requires `security.allowCookies: true`. |
| `pinchtab_connect_profile` | Return connect status for a profile. Required: `profile`. |
+### Human Handoff
+| Tool | Description |
+|------|-------------|
+| `pinchtab_handoff` | Pause a tab so the user can finish a CAPTCHA, login or consent step; action tools on it are refused with `tab_paused_handoff` until resumed. Required: `tabId`. Optional: `reason`, `timeoutMs` (auto-resume). |
+| `pinchtab_resume` | Resume a paused tab. Call only after the user confirms they finished. Required: `tabId`. Optional: `status`. |
+| `pinchtab_handoff_status` | Report `paused_handoff` (with `reason`, `pausedAt`, `expiresAt`) or `active`. Required: `tabId`. |
+
### Utility
| Tool | Description |
|------|-------------|
-| `pinchtab_wait` | Wait N milliseconds. Required: `ms` (max 30000). |
-| `pinchtab_wait_for_selector` | Wait for selector to appear or disappear. Required: `selector`. Optional: `timeout`, `state`, `tabId`. |
-| `pinchtab_wait_for_text` | Wait for text to appear. Required: `text`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_url` | Wait for a URL glob match. Required: `url`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_load` | Wait for a load state. Required: `load`. Optional: `timeout`, `tabId`. |
-| `pinchtab_wait_for_function` | Wait for a JavaScript expression to become truthy. Required: `fn`. Optional: `timeout`, `tabId`. |
+| `pinchtab_wait` | Wait for a condition. Required: `for` (`ms`, `selector`, `text`, `url`, `load` or `function`) and `value` carrying it. Optional: `timeout`, `state`, `tabId`. |
### Network
| Tool | Description |
@@ -110,7 +108,6 @@ All tool names are prefixed with `pinchtab_`.
| `pinchtab_network` | List recent captured network requests. Optional: `tabId`, `filter`, `method`, `status`, `type`, `limit`, `bufferSize`. |
| `pinchtab_network_detail` | Get one request's details. Required: `requestId`. Optional: `tabId`, `body`; inspect bodies only with explicit user approval. |
| `pinchtab_network_clear` | Clear captured network data. Optional: `tabId`. |
-| `pinchtab_network_export` | Export captured data as HAR or NDJSON file. Optional: `tabId`, `format` (har/ndjson), `body`, `filter`, `method`, `status`, `type`, `limit`. Obtain explicit approval, preserve redaction, and delete the artifact after use. Returns `{path, entries, format}`. |
### Dialog
| Tool | Description |