vanyangyang/cursor-bridge/cursor-delegate

Cursor Delegate

Use Cursor as an execution partner. Keep direction, scope decisions, risk ownership, result review, and final verification with the primary agent.

Declare request_context for each call: an AI caller uses sender="model"; set source="user" for explicitly supplied user requirements, "model" for your own task/inference, or "mixed" when both appear. In mixed prompts, label user-confirmed requirements separately from your additions. Use "unknown" where provenance is unavailable; a user asking you to use Cursor does not make your authored message user-authored. These labels are declarations, not authentication or extra permission, and do not carry over to later session turns.

Bind a known workspace

For CCE or cursor_do, pass the intended absolute workspace_path when the installed tool schema supports it. Use the host-provided workspace root/current-task cwd unless the request explicitly targets another project. The field is a pre-send assertion: it never selects, switches, or registers a workspace. Do not infer the target from a repository basename or a saved default binding.

With an older schema, use cursor_status to verify the exact ready project path before sending. initialized=true only means a binding exists; it does not confirm the workspace for this request. cursor_init remains the only explicit initialization, registration, or switch operation.

On pre-send WORKSPACE_CONFIRMATION_REQUIRED, WORKSPACE_INITIALIZATION_REQUIRED, or WORKSPACE_MISMATCH with a known target, first call cursor_status. Only if it confirms idle, no queued or blocking work, and workspaceBusy=false when exposed, call cursor_init for the exact path. Require ready=true, workspaceConfirmationRequired=false, and the exact projectPath; in Agents Window also check workspaceBinding.ok, the local file-URI identity and workspace ID. Retry the original CCE query or cursor_do submission once. Do not run this recovery for needs_attention, uncertain send state, busy status, or ambiguous identity; report the condition and use the necessary local fallback. Do not cancel other work, change model settings, or retry in a loop.

Respect execution controls

• Do not call cursor_do when the user explicitly says not to use Cursor or not to delegate. A direct user opt-out always wins.
• If cursor_do is unavailable, or cursor_status reports delegation as disabled, do not bypass the setting, repeatedly retry, or ask Cursor to re-enable itself. Complete the work in the primary agent.
• Treat CURSOR_BRIDGE_DELEGATION=off as an administrator-level host switch. It disables delegated execution but does not by itself disable cursor_context_engine, cursor_init, or cursor_status.
• Cursor Bridge exposes one fixed delegation contract. Do not invent participation levels, call-frequency controls, or slash commands.
• cursor_model owns persistent model and reasoning-effort defaults. Call its set or reset action only when the user explicitly asks to change those defaults; ordinary delegation must inherit the stored cursor_do choice without silently changing it.

Follow the default workflow

Use this responsibility chain:

primary agent defines purpose, invariants, and risk boundaries -> form a bounded task envelope -> Cursor investigates locally and executes within the envelope -> poll compactly and retrieve the normal terminal reply with detail=result -> primary agent inspects the real changes and verifies them

• Decide what should be achieved, why it matters, what must not change, where Cursor may work, and what evidence makes the result acceptable. Do not delegate product direction, architecture boundaries, or state verdicts.
• Allow Cursor to locate relevant implementation, compare local approaches, and complete code, documentation, configuration, scripts, tests, and tooling inside those boundaries. Do not require the primary agent to pre-solve the task line by line.
• Once a task has been selected for delegation, normally call cursor_do once with background=true, receive its compact submission receipt, then continue non-conflicting primary-agent work. Bridge starts FIFO work in a clean chat automatically.
• Prefer execution=fifo unless the parallel contract is clearly satisfied.
• Do not inject a unique completion marker or impose a minimum response length. Rely on task state, stable task_id or agent_id, and the actual result.

Decide whether this task should go to Cursor

Send a bounded part of the task to Cursor when one or more of these are true:

• The task can be bounded to a path set or subsystem and checked through a diff, test, count, or documentation assertion.
• The work includes repeated lookup, mechanical edits, test or documentation completion, adapter wiring, configuration cleanup, or an independent second pass.
• The primary agent has higher-value design, cross-system judgment, or non-conflicting work to continue.
• Delegation value is uncertain, but a small read_only=true implementation-location probe or single-path task can measure it without transferring an unresolved product decision.

Keep the work in the primary agent when any of these are true:

• The user said not to use Cursor or not to delegate.
• It is a tiny direct edit whose dispatch and review would cost more than doing it locally.
• Cursor would have to decide product direction, architecture, creative intent, or governance state.
• The task requires exclusive GUI state or shared mutable runtime state.
• A safe scope, path boundary, checkable result, or way to preserve existing user changes cannot be established.

Before dispatch, make sure the purpose, invariants, allowed scope, and checkable outcome are reasonably clear. Cursor may resolve local implementation details inside that envelope; the primary agent does not need to prescribe every step.

For an exact known-file or known-symbol lookup, establish the cheapest deterministic local baseline first. For unknown ownership, behavior, call chains, data flow, registrations, or cross-module relationships, follow cce-routing and try cursor_context_engine before generic local discovery. Do not submit the same exact lookup through multiple systems.

Choose the execution mode

• Use execution=fifo for one ordinary task, dependent tasks, overlapping write scopes, shared mutable state, or any case where independence is uncertain. Submit the next dependent task only after accepting the previous result.
• Use execution=parallel_agent only for at least two independent, separately verifiable tasks whose write paths do not overlap.
• Set read_only=true for analysis-only work. Do not run read-only tasks in parallel against the same mutable external state.
• Set read_only=false only with a non-empty set of workspace-relative allowed_paths that contains no globs and cannot escape the workspace. Keep the set as small as practical. It is a scheduling declaration and prompt constraint, not a filesystem sandbox.

Do not choose parallel execution merely because there are many tasks. When dependency or path relationships are unclear, use fifo.

Choose isolated or continuous delivery

• Keep session_mode=isolated as the default. It preserves the existing clean-task behavior.
• Use session_mode=create only when the user explicitly asks to keep later Cursor turns in the same conversation, for example “开启 Cursor 持续会话”, “后续都在同一个 Cursor 会话处理”, or “keep using the same Cursor Agent”.
• Use session_mode=continue only with the exact session_id previously returned by Bridge. “继续 Cursor 会话 <session_id>” is explicit. “继续”, “接着做”, “再改一下”, or “发给 Cursor” alone must not select a session.
• “刚才的 Cursor 会话” may resolve without restating the ID only when the current host task has exactly one ready session for the current workspace. Otherwise report SESSION_REQUIRED or SESSION_AMBIGUOUS; never guess from the selected, newest, or similarly named Agent.
• “新开”, “独立”, “干净会话”, or “不要继承上下文” always means isolated/new work and overrides continuity.
• Start a new session when the workspace, product objective, model/effort, read-only/write boundary, or maximum allowed_paths changes. Independent review and final verification also use fresh context.
• Persistent sessions require parallel_agent and never fall back to FIFO. One session permits only one active turn; different sessions remain subject to the existing path-overlap rules.
• Every continued turn gets a new task_id, repeats read_only=true or an allowed_paths subset, and may provide a request_id so an immediate client retry returns the existing turn instead of sending twice.
• session_id is the stable public association. agent_id remains internal evidence and may be promoted from a provisional Cursor identity; never use it as the caller's session key.

Dispatch a task

1. Record the relevant pre-dispatch workspace state so later review can distinguish existing user changes.
2. Form one independent task envelope per task using delegation-contract.md. Write its narrative instructions in the language of the user's current substantive task unless the user explicitly requests another language. Do not persist an inferred language or replace a clear conversational signal with the host/OS locale.
3. Call cursor_do with background=true and save its compact submission receipt. Include workspace_path when the exact target is known and the schema supports it. Use background=false only when an immediate synchronous full result is required. Use only the documented session_mode and session_id fields when continuity is explicit; never infer continuity from the visible chat.
4. Save each returned task_id; for persistent work also save session_id. Treat agent_id as verification evidence, not the continuation handle.
5. If a parallel submission does not return a usable agent_id, stop expanding the parallel batch and use fifo or report the ambiguous state.

The envelope may contain a small number of local implementation open_questions, but it must also provide fixed_decisions, allowed_paths, prohibitions, and acceptance checks. Cursor may solve local questions; it must stop and report any branch that would change product direction, architecture, or scope.

Collect and verify

1. Always query cursor_status(task_id) for the exact task. Its default compact view is for normal polling; use detail="full" during progress only when detailed diagnostics are needed. Do not treat the currently visible Cursor chat as task identity.
2. Treat submitting, running, and collecting as normal in-progress states. More than two minutes is not itself a failure; wait for an explicit terminal state.
3. After a terminal state, call cursor_status(task_id, detail="result"). It returns the raw complete retained reply without a JSON wrapper and records explicit receipt; check isError before treating content as a reply. Repeat result reads remain allowed while the task is retained. Use detail="full" when the diagnostic task detail is needed.
4. Compare Cursor's claimed work with the real diff, allowed_paths, and acceptance contract.
5. When cursor_status reports a configured model default, confirm modelSelection.applied=true and preserve its configured/effective model and effort fields in any failure report.
6. Run risk-proportionate verification in the primary agent. Cursor's response alone cannot support a formal pass, verified state, or governance transition.
7. Record each task as complete, partial, failed, timed out, or ambiguous before summarizing the batch.