Provider: Cursor Agent CLI

Keep the gateway's Cursor (cursor-agent) integration aligned with the upstream CLI. This skill does not define argv or environment behaviour. The single mechanical source of truth is UPSTREAM_CLI_CONTRACTS.cursor in src/upstream-contracts.ts, enforced by validateUpstreamCliArgs and validateUpstreamCliEnv. Do not re-encode flags, execution modes, ACP rules, or session rules here or in TOML.

Identity

These values mirror UPSTREAM_CLI_CONTRACTS.cursor.upstreamMetadata and docs/upstream/provider-sources.dag.toml ([providers.cursor]). The TypeScript metadata is authoritative; the TOML is scanner input only.

Gateway use

1. Discover the live gateway surface before relying on Cursor-specific controls:

   provider_tool_capabilities({cli:"cursor"})

   For a cached read-only resource, use provider-tools://cursor.
2. Use cursor_request for normal work and cursor_request_async for long-running work. Sync calls may auto-defer; poll llm_job_status and fetch with llm_job_result when that happens.
3. Omit model unless the caller explicitly requests one. Use only controls reported by provider_tool_capabilities, especially execution mode, sandbox, workspace, and session controls. Cursor must use approvalStrategy:"legacy": it rejects mcp_managed before launch because ambient MCP configuration cannot be isolated, and approvalPolicy has no effect.
4. Keep provider-owned MCP configuration separate from gateway metadata. Do not assume every Cursor CLI control is safe to expose through a request.
5. Cursor accepts flat prompt only, not promptParts. workingDir selects the child process cwd on transport:"cli", as it does for every other provider. It is CLI-only: transport:"acp" rejects it in rejectUnsupportedCursorAcpParams alongside addDir, because the ACP route resolves its own scope and would otherwise discard it silently. Its workspace field is separate and selects a local target directory, registered alias, or provider-native .code-workspace file. A directory/alias establishes child cwd; a workspace file remains a native argument and is not misused as spawn.cwd. Because both inputs can name a cwd, resolveCursorWorkingDir rejects an absolute workspace path that disagrees with workingDir instead of ranking them; identical values are admitted. Verify the target before reviewing concurrent repositories. An unregistered relative value remains a provider-native saved-workspace name and is passed through verbatim, never resolved against the gateway process cwd. Use an absolute path when selecting an unregistered local directory as child cwd.
6. Use a real resumable Cursor chat only when the response reports it as resumable. Gateway bookkeeping IDs are not automatically valid Cursor chat IDs. Continuation remains provider-native under legacy. A cwd-scoped resumeLatest needs a stable selected target.
7. Native ACP is capability-gated. It rejects approvalStrategy:"mcp_managed" and any approvalPolicy, as does the Cursor CLI gateway path. Probe cursor-agent acp --help when validating the installed entrypoint.
8. An unscoped CLI child uses a fresh neutral temporary cwd, not the gateway repository. Cursor's argv-bound prompt rejects oversized UTF-8 input as non-retryable input_too_large; the gateway never truncates it. All other caller-controlled argv values are admitted in their final encoded form before spawn. Embedded NUL bytes return non-retryable invalid_input without exposing the rejected value.

Full-access review handoff

For a user-authorized exhaustive review that needs full provider permissions and native MCP access, do not infer the launch controls from this maintenance guide. Follow multi-llm-review's full-access protocol, inspect the current request schema and live capability response, and use a fresh target-checkout node dist/index.js --transport=stdio gateway rather than a global process. Reapply the grant on every new job, preserve native MCP configuration without a pretend gateway allowlist, send the corrective-program report and exact diff/file identity, set no caller caps, and honor a user-required 90-second progress cadence. The reviewer must independently inspect code, docs, tests, and commands before it can approve.

Scan for upstream change

npm run upstream:scan -- --provider cursor
npm run upstream:scan -- --live --provider cursor --fail-on-critical
npm run upstream:scan -- --provider cursor --probe-installed --fail-on-critical
npm run upstream:scan -- --live --provider cursor --probe-installed --write-snapshot --write-report

A failed source fetch is advisory unless --fail-on-critical is passed. Use the installed help probe as the primary signal for rapidly changing command surface.

Update procedure

1. Edit UPSTREAM_CLI_CONTRACTS.cursor in src/upstream-contracts.ts: flags, arities, enums, execution modes, session rules, ACP probe commands, and catalogued subcommands belong there.
2. Add conformance fixtures that prove every new accept and reject behavior.
3. If a source URL or watch category changes, update TypeScript metadata first, then mirror it in docs/upstream/provider-sources.dag.toml.
4. Verify with npm run build, npm run upstream:contracts, and targeted provider tests before the full suite.

Cursor-specific notes

• Tested against cursor-agent 2026.09.02-c22c1a3.
• Root commands include authentication, MCP, worker, update, chat/session, and rule-management surfaces. Catalog them with an explicit risk and exposure tier before exposing any of them through gateway admin or request tools.
• Keep destructive or interactive commands, including worker startup and any session mutation, catalog-only unless an approval-gated product surface is deliberately added.