Add Cursor CLI external workers

[arjitj2]

Closes #71

Changes

Let Codex and Claude Code delegate workers through an existing Cursor subscription using cursor:<exact-model-slug>@default. Reasoning variants remain part of the exact slug. The adapter calls cursor-agent explicitly because agent can refer to another tool.

Pin the model, parse structured output and optional usage, and remove each attempt's private configuration on exit. Read-only workers deny writes and shell execution; writers request Cursor's sandbox in their assigned workspace. Setup supports selected Cursor workers and panel verification.

OAuth uses Cursor's authentication status check. API-key-only installations instead verify CLI availability and defer authentication to the actual model invocation; invalid keys produce an unauthenticated receipt. Private configuration preserves the validated network.useHttp1ForAgent transport setting without copying user permissions or unrelated configuration.

Workers do not inherit the parent's conversation or MCP tools. Cursor may load project hooks, plugins, or recursive subagents, so workspaces must be trusted. Receipts record pinned-argv evidence, not provider-verified model identity.

Verification

• 188 Bun tests pass, including 30 focused Cursor tests.
• Strict typecheck, static invariants, manifest checks, Claude plugin validation, and git diff --check pass.
• Exact candidate installed in both affected harnesses.
• Changed behavior verified from the real Codex surface.
• Final-candidate Claude Code live checks complete.

Live evidence, 2026-09-16 on macOS: pstack 1.4.1, candidate 24c489167b1fb7359525ec200fd8129563e723e8. All 168 installed plugin files matched the committed snapshot byte-for-byte in Codex CLI 0.154.0 and Claude Code 2.1.179. Cursor CLI version was 2026.09.10-fd3934a with composer-2.5.

The real Codex parent passed known-file reads, exact workspace file creation, read-only file/shell restrictions, outside-workspace write containment, and SIGTERM cancellation with output/config cleanup. During these OAuth runs, an observer read each actual private configuration and verified HTTP/1 transport was retained while the source configuration's permissive settings were excluded. The source configuration remained byte-identical.

A separate installed run with a deliberately invalid test API key passed the CLI-version preflight, reached the model invocation, then returned unauthenticated with no output or private configuration left behind. The key did not appear in argv, configuration, or receipt. Valid-key-only success is covered by fixture tests; no real valid API key was available for a live positive test.

A fresh Claude Code parent passed the same exact-candidate checks: known-file read, exact file creation, read-only file/shell denials, outside-workspace containment, invalid-key authentication failure, and controlled cancellation. Independent assertions verified actual file bytes, preserved HTTP/1 transport, excluded permissive source settings, unchanged source configuration, and private configuration cleanup. Both real application surfaces now pass. Setup's requirement for unused baseline providers is handled separately in #73.

[greptile-apps]

Confidence Score: 5/5

The latest head appears safe to merge, with no actionable new defects or outstanding findings identified.

Summary

This PR adds optional Cursor CLI workers to the existing external-provider runner while preserving parent-owned routing and per-attempt evidence.

• Adds exact Cursor model descriptors using cursor:<slug>@default.
• Introduces Cursor authentication preflight, private per-run configuration, sandbox permissions, structured-output parsing, usage normalization, and cleanup.
• Extends setup and dispatch guidance for Cursor’s model, tool, trust, and isolation limitations.
• Adds comprehensive tests for both parent harnesses, API-key and OAuth flows, model validation, configuration preservation, output parsing, cancellation, failure classification, and cleanup.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Parent selects cursor model and workspace] --> B[Validate exact slug and default effort]
    B --> C[Reserve output and receipt paths]
    C --> D[Create private Cursor configuration]
    D --> E{CURSOR_API_KEY present?}
    E -->|Yes| F[Check cursor-agent version]
    E -->|No| G[Check stored OAuth status]
    F --> H[Invoke cursor-agent with pinned model]
    G --> H
    H --> I{Successful structured result?}
    I -->|Yes| J[Write output and complete receipt]
    I -->|No| K[Write classified dropout receipt]
    J --> L[Remove private configuration]
    K --> L

Loading

_{Reviews (3) · Last reviewed commit: "Preserve Cursor API-key authentication a..."}

[mergify]

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.

[openswebot]

Open SWE Review found 2 potential issues.

Open in Web

[arjitj2]

@OpenSWE review

[arjitj2]

@greptileai please review the latest head. The validation follow-ups are pushed; the PR remains draft pending the final Claude Code quota reset and installed test.

[ericlitman]

Thanks for this, @arjitj2. I appreciate the time you put into it. Open Pstack now accepts contributions as detailed issues rather than pull requests, so I'm closing this one. If it's still relevant, please open an issue describing the problem, how to reproduce it, and the change you'd suggest. I'll take it from there.

[ericlitman]

Follow-up to the close: this work is already tracked in #71, so there is no need to open a new issue. This PR is noted there as prior art and will be credited when the fix lands.