@open-agent-toolkit/cli 0.2.19 → 0.2.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/config/dispatch-matrix-recommendation.json +15 -5
- package/assets/docs/cli-utilities/configuration.md +10 -5
- package/assets/docs/contributing/index.md +1 -0
- package/assets/docs/contributing/verifying-cursor-pins.md +282 -0
- package/assets/docs/workflows/projects/dispatch-ceiling.md +50 -4
- package/assets/public-package-versions.json +4 -4
- package/assets/skills/subagent-orchestration/SKILL.md +1 -1
- package/assets/skills/subagent-orchestration/references/evidence-and-refresh.md +153 -15
- package/assets/skills/subagent-orchestration/references/model-selection-principles.md +75 -3
- package/assets/skills/subagent-orchestration/references/provider-claude.md +95 -35
- package/assets/skills/subagent-orchestration/references/provider-codex.md +36 -10
- package/assets/skills/subagent-orchestration/references/provider-cursor.md +91 -15
- package/dist/providers/cursor/codec/catalog.d.ts +19 -1
- package/dist/providers/cursor/codec/catalog.d.ts.map +1 -1
- package/dist/providers/cursor/codec/catalog.js +54 -0
- package/package.json +2 -2
|
@@ -12,11 +12,24 @@ Never select from a model family name alone. Preserve these axes separately:
|
|
|
12
12
|
- provider-native effort or reasoning selector;
|
|
13
13
|
- service tier, including fast or priority variants;
|
|
14
14
|
- reasoning mode when the provider exposes one independently of effort;
|
|
15
|
+
- task class and the reasoning depth the work requires;
|
|
16
|
+
- consequence and the independent-review requirement it creates;
|
|
17
|
+
- reviewer role and the anticipated failure mode that reviewer should catch;
|
|
18
|
+
- eligibility, including selector availability, retention policy, access,
|
|
19
|
+
context, safeguards, and harness-version constraints;
|
|
15
20
|
- role, context inheritance, authority, deadline, and route.
|
|
16
21
|
|
|
17
22
|
Do not normalize effort labels across providers. `medium`, `high`, `xhigh`,
|
|
18
23
|
`max`, extended thinking, adaptive thinking, and provider-specific modes have
|
|
19
|
-
different semantics.
|
|
24
|
+
different semantics. Compare same-labelled rungs only as an analysis view
|
|
25
|
+
within a named harness, never as evidence that the labels are equivalent. The
|
|
26
|
+
exact pair or tuple is the route.
|
|
27
|
+
|
|
28
|
+
Task class, effort, consequence, reviewer role, and eligibility are related but
|
|
29
|
+
independent decisions. Reasoning depth determines effort escalation.
|
|
30
|
+
Consequence normally adds independent review, root-owned authorization, or
|
|
31
|
+
stronger verification; it does not automatically force the highest effort.
|
|
32
|
+
Eligibility filters the candidate set before capability or economy is compared.
|
|
20
33
|
|
|
21
34
|
## Five Task Classes
|
|
22
35
|
|
|
@@ -59,7 +72,27 @@ the task.
|
|
|
59
72
|
adversarial behavior, or expensive failure dominates.
|
|
60
73
|
|
|
61
74
|
Narrow a poorly decomposed task before escalating its model. Model capability
|
|
62
|
-
never repairs an over-broad objective.
|
|
75
|
+
never repairs an over-broad objective. A consequential classification does not
|
|
76
|
+
by itself justify top effort; raise effort only when deeper reasoning is also a
|
|
77
|
+
bottleneck.
|
|
78
|
+
|
|
79
|
+
## Eligibility
|
|
80
|
+
|
|
81
|
+
Eliminate ineligible routes before ranking capability, cost, or speed. Verify:
|
|
82
|
+
|
|
83
|
+
- the exact selector and required effort or thinking control exist in the live
|
|
84
|
+
launching surface;
|
|
85
|
+
- retention, data-handling, authorization, and safeguard behavior permit the
|
|
86
|
+
workload;
|
|
87
|
+
- account access, rate limits, service-tier commitments, and harness version
|
|
88
|
+
permit the route;
|
|
89
|
+
- the context window, long-context quality, and threshold pricing fit the
|
|
90
|
+
input;
|
|
91
|
+
- tool support and fallback behavior are understood and do not silently change
|
|
92
|
+
the selected route.
|
|
93
|
+
|
|
94
|
+
Provider evidence can nominate a candidate. It cannot prove that another
|
|
95
|
+
harness exposes the same selector or control.
|
|
63
96
|
|
|
64
97
|
## Long Context
|
|
65
98
|
|
|
@@ -88,9 +121,41 @@ the final answer is short.
|
|
|
88
121
|
|
|
89
122
|
A fast or priority tier is a latency control unless the provider explicitly
|
|
90
123
|
documents a capability difference. It does not satisfy a higher task-class
|
|
91
|
-
floor. Choose it only when
|
|
124
|
+
floor. Choose it only when measured latency is worth the price and record it
|
|
92
125
|
separately from the model and effort.
|
|
93
126
|
|
|
127
|
+
Speed is a multi-measure contract, not a single throughput number. This section
|
|
128
|
+
defines that contract; other references cite it rather than restating their own
|
|
129
|
+
version.
|
|
130
|
+
|
|
131
|
+
Required in any speed claim:
|
|
132
|
+
|
|
133
|
+
- time to first token;
|
|
134
|
+
- active agent runtime;
|
|
135
|
+
- total user-observed elapsed time;
|
|
136
|
+
- output tokens;
|
|
137
|
+
- steps, turns, or tool calls;
|
|
138
|
+
- completion rate and variance.
|
|
139
|
+
|
|
140
|
+
Time to first token is required, not substitutable. Where a harness cannot
|
|
141
|
+
expose it, record it explicitly as not-reported rather than silently omitting
|
|
142
|
+
it or supplying a different measure in its place; an absent measure and an
|
|
143
|
+
unmeasurable one are different claims.
|
|
144
|
+
|
|
145
|
+
Record additionally when available:
|
|
146
|
+
|
|
147
|
+
- first useful action, which is a complement to time to first token and never
|
|
148
|
+
a replacement for it;
|
|
149
|
+
- output rate;
|
|
150
|
+
- input and cached-input tokens;
|
|
151
|
+
- retries, recoveries, refusals, and operator interventions;
|
|
152
|
+
- service tier, rate limits, and agent-slot occupancy;
|
|
153
|
+
- cost per attempted and completed task.
|
|
154
|
+
|
|
155
|
+
Do not relabel active runtime as total elapsed time, and do not infer latency
|
|
156
|
+
from tokens or steps. Trajectory measures cannot substitute for measured
|
|
157
|
+
latency. Compare list pricing separately from total trajectory cost.
|
|
158
|
+
|
|
94
159
|
## Independent Review
|
|
95
160
|
|
|
96
161
|
For high-risk diffs and foundational decisions, prefer an author and reviewer
|
|
@@ -98,6 +163,13 @@ from different model families or providers. Agreement is not proof; disagreement
|
|
|
98
163
|
is evidence that the root must resolve. The root verifies every load-bearing
|
|
99
164
|
claim and retains final judgment.
|
|
100
165
|
|
|
166
|
+
Choose the reviewer according to the failure mode the reviewer should catch:
|
|
167
|
+
engineering execution, tool trajectory, missing domain concepts, factual
|
|
168
|
+
knowledge, policy interpretation, or adversarial weakness. Named reviewer
|
|
169
|
+
instantiations in provider guidance are dated and provisional unless a relevant
|
|
170
|
+
evaluation qualifies them. Reviewer independence never transfers authorization
|
|
171
|
+
away from the root.
|
|
172
|
+
|
|
101
173
|
## Staleness
|
|
102
174
|
|
|
103
175
|
Read `evidence-and-refresh.md` when provider guidance is review-required or
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
guidance_version: 2026-07-
|
|
3
|
-
last_verified: 2026-07-
|
|
4
|
-
review_after: 2026-09-
|
|
2
|
+
guidance_version: 2026-07-25
|
|
3
|
+
last_verified: 2026-07-25
|
|
4
|
+
review_after: 2026-09-08
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Claude Model Selection
|
|
@@ -15,12 +15,15 @@ the dated model examples below. Launch mechanics for OAT dispatch live in
|
|
|
15
15
|
|
|
16
16
|
- `claude-haiku-4-5`: fastest economical class for straightforward,
|
|
17
17
|
high-volume, mechanically verified work.
|
|
18
|
-
- `claude-
|
|
19
|
-
|
|
20
|
-
- `claude-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
- `claude-opus-5`: normal substantive route and the default for
|
|
19
|
+
interpretation-heavy implementation, hard reasoning, and consequential work.
|
|
20
|
+
- `claude-sonnet-5`: conditional route when measured latency, throughput,
|
|
21
|
+
access, rate limits, or established-workflow economics beat the relevant
|
|
22
|
+
Opus route.
|
|
23
|
+
- `claude-fable-5`: eligibility-gated specialist for a directly relevant
|
|
24
|
+
failure mode, not a universal escalation above Opus.
|
|
25
|
+
- `claude-opus-4-8`: compatibility or documented safeguard fallback, not the
|
|
26
|
+
current general primary.
|
|
24
27
|
|
|
25
28
|
Claude Mythos 5 is invitation-only and intended for approved defensive cyber
|
|
26
29
|
work. It is not a general routing candidate unless the organization explicitly
|
|
@@ -30,52 +33,109 @@ provisions and authorizes it.
|
|
|
30
33
|
|
|
31
34
|
Never normalize Claude effort against OpenAI or Cursor labels.
|
|
32
35
|
|
|
33
|
-
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
36
|
+
- Opus 5: use medium for normal substantive work and high for hard reasoning,
|
|
37
|
+
architecture, ambiguity, and deep review. Use xhigh only when reasoning depth
|
|
38
|
+
is the bottleneck or an evaluated long-horizon workload benefits. Max is
|
|
39
|
+
exceptional and requires a workload-specific effort sweep or an explicit
|
|
40
|
+
quality-first exception.
|
|
41
|
+
- Sonnet 5: use medium or high only when measured latency, throughput, access,
|
|
42
|
+
or workload economics justify the conditional route. Do not preserve xhigh
|
|
43
|
+
or max as generic workhorse settings.
|
|
44
|
+
- Fable 5: use high or xhigh only for a qualified specialist case. Max is
|
|
45
|
+
exceptional; medium or low are not routine economy substitutes for Opus.
|
|
40
46
|
- Haiku 4.5 does not expose the same adaptive-effort surface. Use only controls
|
|
41
47
|
present in the live schema.
|
|
42
48
|
|
|
43
49
|
Effort changes tool-call behavior as well as prose. Record it independently.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
50
|
+
Opus 5 adaptive thinking is on by default; current direct-API behavior rejects
|
|
51
|
+
disabling thinking at xhigh or max. Verify the live schema before launch.
|
|
52
|
+
Changing effort or speed can invalidate prompt caches. Fable adaptive thinking
|
|
53
|
+
is always on in the current API.
|
|
47
54
|
|
|
48
55
|
## Dated Task-Class Matrix
|
|
49
56
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
| `
|
|
57
|
+
These routes are dated guidance and benchmark-derived routing hypotheses.
|
|
58
|
+
Evaluate them on representative local work before treating fine boundaries as
|
|
59
|
+
stable.
|
|
60
|
+
|
|
61
|
+
| Task class | Default | Economy | Escalation | Floor notes |
|
|
62
|
+
| ------------------------ | ----------------------------------- | ------------------------------------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
63
|
+
| `mechanical-recon` | Haiku 4.5 | Same, with strict output and mechanical verification | Opus 5 medium | Haiku is below floor for semantic audits and silent-miss-prone exploration. |
|
|
64
|
+
| `intelligent-recon` | Opus 5 medium | Sonnet 5 medium/high only when its measured route wins | Opus 5 high | Do not use Sonnet low for coding or open-ended recon. |
|
|
65
|
+
| `default-implementation` | Opus 5 medium | Sonnet 5 medium/high for evaluated bounded throughput | Opus 5 high | Fable is not a routine implementation or economy route. |
|
|
66
|
+
| `hard-reasoning` | Opus 5 high | Opus 5 medium only after narrowing and evaluation | Opus 5 xhigh for a reasoning-depth bottleneck | Use max only after a workload-specific effort sweep. |
|
|
67
|
+
| `consequential` | Opus 5 high plus independent review | No routine economy route | Opus 5 xhigh when deeper reasoning is also required | Consequence adds review and root authorization; it does not automatically require xhigh or max. |
|
|
57
68
|
|
|
58
69
|
## Root and Subagent Cost Posture
|
|
59
70
|
|
|
60
71
|
Preserve strong, low-volume root orchestration. Root calls are
|
|
61
72
|
coherence-critical and comparatively infrequent, while bounded subagents carry
|
|
62
73
|
most execution volume. Capture routine savings in higher-volume subagents by
|
|
63
|
-
routing mechanical work to Haiku and
|
|
64
|
-
of weakening the root orchestrator.
|
|
74
|
+
routing mechanical work to Haiku and using Sonnet only where a measured
|
|
75
|
+
high-volume route wins instead of weakening the root orchestrator.
|
|
65
76
|
|
|
66
77
|
Opus remains the hard-reasoning and consequential root default. Escalate the
|
|
67
78
|
root from Opus to Fable only when unresolved ambiguity, exceptional novelty or
|
|
68
|
-
consequence, or a directly relevant Fable strength
|
|
69
|
-
|
|
79
|
+
consequence, or a directly relevant Fable strength exposes a failure mode that
|
|
80
|
+
Fable is expected to catch and eligibility permits it. This named Fable
|
|
81
|
+
instantiation is provisional.
|
|
82
|
+
|
|
83
|
+
A consequential classification by itself is insufficient.
|
|
84
|
+
|
|
85
|
+
## Conditional and Specialist Routes
|
|
86
|
+
|
|
87
|
+
Sonnet remains available when time to first token, active runtime, total elapsed
|
|
88
|
+
time, throughput, access, rate limits, or end-to-end workload economics win for
|
|
89
|
+
the actual harness. Compare against the relevant Opus effort and service tier,
|
|
90
|
+
not an unrelated maximum-effort latency row. A lower token price alone does not
|
|
91
|
+
prove lower trajectory cost.
|
|
92
|
+
|
|
93
|
+
Choose specialist reviewers by anticipated failure mode. Fable is a
|
|
94
|
+
provisional candidate for latent-knowledge, missing-domain-concept,
|
|
95
|
+
sparse-context, long-horizon, or additional-perspective work. It is unavailable
|
|
96
|
+
where zero data retention is required because the current route requires
|
|
97
|
+
30-day retention. Provider availability, retention, and controls must be
|
|
98
|
+
verified before selection.
|
|
99
|
+
|
|
100
|
+
## Eligibility, Retention, and Service Constraints
|
|
101
|
+
|
|
102
|
+
Eligibility filters the candidate set before capability or economy is compared.
|
|
103
|
+
A route that fails one of these gates is unavailable regardless of benchmark
|
|
104
|
+
standing. These are dated facts verified 2026-07-25; reverify against the live
|
|
105
|
+
schema and the organization's actual plan before launch.
|
|
106
|
+
|
|
107
|
+
| Constraint | Opus 5 | Sonnet 5 | Fable 5 | Haiku 4.5 |
|
|
108
|
+
| ------------------- | ---------------------- | ------------- | -------------------------- | ------------- |
|
|
109
|
+
| Zero data retention | eligible | eligible | **unavailable**, needs 30d | eligible |
|
|
110
|
+
| Priority Tier | not supported | not supported | supported | verify live |
|
|
111
|
+
| Fast mode | gated research preview | no | no | no |
|
|
112
|
+
| Long context | 1M at standard rates | 1M standard | 1M standard | verify live |
|
|
113
|
+
| Claude Code minimum | version-gated | version-gated | version-gated | version-gated |
|
|
114
|
+
|
|
115
|
+
- Zero data retention removes Fable from the route set outright. Check the
|
|
116
|
+
retention requirement before selecting a specialist reviewer.
|
|
117
|
+
- Priority Tier commitments are closed to new buyers, so this matters only for
|
|
118
|
+
an existing commitment. Do not infer availability from another Claude family.
|
|
119
|
+
- Fast mode is a gated latency purchase, not a capability rung.
|
|
120
|
+
- Claude 4.6 and later families use their full 1M context windows at standard
|
|
121
|
+
rates. Do not carry a competitor's long-context surcharge model across to
|
|
122
|
+
Claude; the Codex Sol threshold step is a Sol fact, not a general one.
|
|
123
|
+
- Claude Code enforces family-specific minimum versions. Verify the installed
|
|
124
|
+
runtime rather than assuming the catalog entry is launchable.
|
|
125
|
+
|
|
126
|
+
Record service tier independently and apply the multi-measure speed contract
|
|
127
|
+
from `model-selection-principles.md`.
|
|
70
128
|
|
|
71
129
|
## Cyber-Sensitive Evidence
|
|
72
130
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
consequential findings with an independent provider review.
|
|
131
|
+
For security review, vulnerability triage, auth boundaries, permissions, and
|
|
132
|
+
other valid dual-use workflows, start with Opus 5 at the effort warranted by
|
|
133
|
+
reasoning depth and pair consequential findings with an independent provider
|
|
134
|
+
review.
|
|
78
135
|
|
|
136
|
+
If a safeguard blocks a valid workflow, record the refusal, preserve the
|
|
137
|
+
authorization boundary, and use a documented compatible fallback. Opus 4.8 is
|
|
138
|
+
the current fallback target where necessary, not the universal cyber primary.
|
|
79
139
|
Do not infer that a stronger safety classifier is a capability weakness. It is
|
|
80
140
|
evidence about predictable workflow completion and refusal behavior, not an
|
|
81
141
|
exception that inverts the general Opus-first policy.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
guidance_version: 2026-07-
|
|
3
|
-
last_verified: 2026-07-
|
|
4
|
-
review_after: 2026-09-
|
|
2
|
+
guidance_version: 2026-07-25
|
|
3
|
+
last_verified: 2026-07-25
|
|
4
|
+
review_after: 2026-09-08
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Codex and OpenAI Model Selection
|
|
@@ -33,24 +33,50 @@ name includes `codex`.
|
|
|
33
33
|
|
|
34
34
|
## Dated Task-Class Matrix
|
|
35
35
|
|
|
36
|
-
| Task class | Default
|
|
37
|
-
| ------------------------ |
|
|
38
|
-
| `mechanical-recon` | `gpt-5.6-luna`, `high`
|
|
39
|
-
| `intelligent-recon` | `gpt-5.6-terra`, `high`
|
|
40
|
-
| `default-implementation` | `gpt-5.6-sol`, `medium`
|
|
41
|
-
| `hard-reasoning` | `gpt-5.6-sol`, `high`
|
|
42
|
-
| `consequential` | `gpt-5.6-sol`, `
|
|
36
|
+
| Task class | Default | Economy | Escalation | Floor notes |
|
|
37
|
+
| ------------------------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
38
|
+
| `mechanical-recon` | `gpt-5.6-luna`, `high` | Direct API only: `gpt-5.4-mini` medium; `gpt-5.4-nano` medium for strict extraction/classification | `gpt-5.6-terra`, medium or high | Do not use Luna none/low for broad repository work. |
|
|
39
|
+
| `intelligent-recon` | `gpt-5.6-terra`, `high` | Terra `medium` with tight scope and verification | Sol `medium`, then `high` | A silent miss disqualifies Terra none/low. |
|
|
40
|
+
| `default-implementation` | `gpt-5.6-sol`, `medium` | Terra `high` for independently bounded, strongly tested work | Sol `high` | Luna is not the normal implementation lead. |
|
|
41
|
+
| `hard-reasoning` | `gpt-5.6-sol`, `high` | Sol `medium` only after narrowing the problem | Sol `xhigh` | Do not automatically escalate Terra to xhigh/max; move to Sol. |
|
|
42
|
+
| `consequential` | `gpt-5.6-sol`, `high`, plus independent review | No routine economy route | Sol `xhigh` when deeper reasoning is required; `max` or a separately evaluated `pro` route only after evaluation | Consequence adds review and root authorization; it does not automatically require xhigh or max. |
|
|
43
43
|
|
|
44
44
|
`reasoning.mode: "pro"` is a separate quality/latency/cost control on GPT-5.6,
|
|
45
45
|
not a model slug and not an effort label. Record it independently. Evaluate it
|
|
46
46
|
against max or xhigh on representative consequential work before adopting it.
|
|
47
47
|
|
|
48
|
+
The task-class ladder is work-shape based. Sol is the code-first,
|
|
49
|
+
trajectory-efficient route for implementation and hard reasoning; this does
|
|
50
|
+
not establish a provider-independent ranking against interpretation-heavy
|
|
51
|
+
models in other harnesses. Consequential work requires independent review and
|
|
52
|
+
root-owned authorization. It does not automatically force Sol xhigh or max:
|
|
53
|
+
choose effort from reasoning depth, then add the consequence controls.
|
|
54
|
+
|
|
48
55
|
## Long-Context Floor
|
|
49
56
|
|
|
50
57
|
For very large context, prefer Sol or Terra. Published GPT-5.6 results show a
|
|
51
58
|
large Luna retention drop in the 256K-to-1M range. Large context does not change
|
|
52
59
|
the task class, but it may disqualify Luna, mini, or nano.
|
|
53
60
|
|
|
61
|
+
For Sol requests above 272K input tokens, the current direct-API price step is
|
|
62
|
+
2× input and 1.5× output. Apply the threshold to the whole request and verify
|
|
63
|
+
the live pricing contract before cost-sensitive dispatch. Crossing this
|
|
64
|
+
threshold can change the economical route even when Sol remains the capability
|
|
65
|
+
choice.
|
|
66
|
+
|
|
67
|
+
## Trajectory Economics
|
|
68
|
+
|
|
69
|
+
Token list price and total trajectory cost are separate. A model with a higher
|
|
70
|
+
output-token price can still cost less per completed task when it uses fewer
|
|
71
|
+
output tokens, steps, tool calls, retries, or recoveries. Conversely, a cheap
|
|
72
|
+
attempt is not economical when completion rate is low or operator intervention
|
|
73
|
+
is high.
|
|
74
|
+
|
|
75
|
+
Evaluate input, cached-input, and output tokens together with the multi-measure
|
|
76
|
+
speed contract from `model-selection-principles.md`. Do not use token price
|
|
77
|
+
alone as a proxy for wall-clock efficiency, and do not infer latency from
|
|
78
|
+
trajectory length without a measured runtime.
|
|
79
|
+
|
|
54
80
|
## Tool-Heavy Work
|
|
55
81
|
|
|
56
82
|
Use Programmatic Tool Calling only for bounded processing such as filtering,
|
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
---
|
|
2
|
-
guidance_version: 2026-07-
|
|
3
|
-
last_verified: 2026-07-
|
|
2
|
+
guidance_version: 2026-07-25
|
|
3
|
+
last_verified: 2026-07-25
|
|
4
4
|
review_after: 2026-09-04
|
|
5
|
-
catalog_basis:
|
|
5
|
+
catalog_basis:
|
|
6
|
+
live `cursor-agent models` catalog and CursorBench 3.2, with Opus 5
|
|
7
|
+
and Opus 4.8 pin selectors probe-verified against Cursor 3.12.30 via
|
|
8
|
+
subagentStart lifecycle hooks
|
|
6
9
|
---
|
|
7
10
|
|
|
8
11
|
# Cursor Model Selection
|
|
@@ -23,29 +26,102 @@ conflict.
|
|
|
23
26
|
The Cursor SDK exposes the Cursor runtime, harness, and models. It is not a
|
|
24
27
|
transparent raw OpenAI or Anthropic API call.
|
|
25
28
|
|
|
29
|
+
Every exact route below is dated and provisional. Verify the live root or
|
|
30
|
+
nested catalog, resolved identity, reasoning controls, and fallback behavior
|
|
31
|
+
before launch.
|
|
32
|
+
|
|
26
33
|
## Service-Tier Rule
|
|
27
34
|
|
|
28
35
|
Treat every alias ending in `-fast` as a service-tier selection, not a higher
|
|
29
36
|
capability class, unless current Cursor documentation explicitly says
|
|
30
37
|
otherwise. Composer 2.5 fast is documented as the same intelligence at a higher
|
|
31
38
|
price. Use standard aliases for background work and fast aliases only when
|
|
32
|
-
|
|
39
|
+
multi-measure latency evidence justifies the premium.
|
|
33
40
|
|
|
34
41
|
Record the model and the service tier separately even when Cursor encodes both
|
|
35
|
-
in one opaque alias
|
|
42
|
+
in one opaque alias, and apply the multi-measure speed contract from
|
|
43
|
+
`model-selection-principles.md`. A lower active runtime or higher output rate
|
|
44
|
+
does not by itself prove lower user-observed elapsed time.
|
|
36
45
|
|
|
37
46
|
## Dated Task-Class Matrix
|
|
38
47
|
|
|
39
|
-
Use exact aliases from the live catalog. The examples below
|
|
40
|
-
|
|
48
|
+
Use exact aliases from the live catalog. The examples below come from two
|
|
49
|
+
observations, not one. Most were present in a 2026-07-21 catalog snapshot. The
|
|
50
|
+
`claude-opus-5` and `claude-opus-4-8` routes postdate it — Opus 5 released
|
|
51
|
+
2026-07-24 — and were confirmed against the live catalog and probe-verified on
|
|
52
|
+
2026-07-25, as recorded under Verified Opus 5 Cursor Routes below. The
|
|
53
|
+
remainder of the catalog has not been re-snapshotted since 2026-07-21, so treat
|
|
54
|
+
non-Opus entries as the older and weaker observation.
|
|
55
|
+
|
|
56
|
+
| Task class | Default | Economy | Escalation | Floor notes |
|
|
57
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| `mechanical-recon` | `composer-2.5` | `composer-2.5` | `gpt-5.6-luna-high` | Use `composer-2.5-fast` or Luna fast only for latency, not capability. |
|
|
59
|
+
| `intelligent-recon` | `cursor-grok-4.5-medium` or `gpt-5.6-sol-medium` | `gpt-5.6-terra-high` | `gpt-5.6-sol-high` | Grok medium is a primary route; Sol medium is the conservative silent-miss alternative; Terra high is the cost-saving route. |
|
|
60
|
+
| `default-implementation` | `gpt-5.6-sol-medium` | `composer-2.5` for bounded, testable changes | `claude-opus-5-thinking-medium` | Sol is the code-first incumbent; Opus 5 medium is the substantive route for interpretation-heavy work; `cursor-grok-4.5-medium` remains a primary alternative. |
|
|
61
|
+
| `hard-reasoning` | `claude-opus-5-thinking-high` | `cursor-grok-4.5-high` for architecture, ambiguous debugging, and incident diagnosis | `claude-opus-5-thinking-xhigh`, then `gpt-5.6-sol-xhigh` for code-first work | Opus 5 high is the starting point. Escalate to xhigh only for a reasoning-depth bottleneck. Do not infer cross-provider effort equivalence. |
|
|
62
|
+
| `consequential` | The task's own reasoning-depth route, plus independent cross-family review: typically `gpt-5.6-sol-high` authoring with `claude-opus-5-thinking-high` review | No routine economy route | Raise the pair to xhigh for a reasoning-depth bottleneck; Sol max plus Opus 5 max only after a workload-specific sweep | Consequence adds independent cross-family review and root authorization, not automatic top effort. Select effort from reasoning depth exactly as the non-consequential row would, then add independence on top. For cyber-sensitive review, do not rely on Fable or Grok alone. |
|
|
63
|
+
|
|
64
|
+
## Verified Opus 5 Cursor Routes
|
|
65
|
+
|
|
66
|
+
Opus 5 is a qualified Cursor route. Five effort rungs plus an Opus 4.8 rung were
|
|
67
|
+
probe-verified on 2026-07-25 against Cursor 3.12.30, using `subagentStart`
|
|
68
|
+
lifecycle hooks to read the resolved model that Cursor itself reports:
|
|
69
|
+
|
|
70
|
+
| Selector | Resolves to |
|
|
71
|
+
| ------------------------------- | -------------------------------- |
|
|
72
|
+
| `claude-opus-5[effort=low]` | `claude-opus-5-thinking-low` |
|
|
73
|
+
| `claude-opus-5[effort=medium]` | `claude-opus-5-thinking-medium` |
|
|
74
|
+
| `claude-opus-5[effort=high]` | `claude-opus-5-thinking-high` |
|
|
75
|
+
| `claude-opus-5[effort=xhigh]` | `claude-opus-5-thinking-xhigh` |
|
|
76
|
+
| `claude-opus-5[effort=max]` | `claude-opus-5-thinking-max` |
|
|
77
|
+
| `claude-opus-4-8[effort=xhigh]` | `claude-opus-4-8-thinking-xhigh` |
|
|
78
|
+
|
|
79
|
+
Every rung resolves to the thinking variant. This is a verified fact, not an
|
|
80
|
+
inference: the catalog carries distinct non-thinking IDs at low, medium, and
|
|
81
|
+
high, and none were selected.
|
|
82
|
+
|
|
83
|
+
Routing follows the accepted conclusions rather than the effort ladder alone.
|
|
84
|
+
Opus 5 medium is the normal substantive route, high is the hard-reasoning
|
|
85
|
+
starting point, xhigh is selective for a reasoning-depth bottleneck or an
|
|
86
|
+
evaluated long-horizon benefit, and max requires a workload-specific sweep or an
|
|
87
|
+
explicit exception. Sol remains the code-first, trajectory-efficient engineering
|
|
88
|
+
route; Opus is generally stronger for interpretation-heavy work. Exact
|
|
89
|
+
cross-provider substitutions remain provisional.
|
|
90
|
+
|
|
91
|
+
Opus 4.8 xhigh is catalogued so the cyber-sensitive route is dispatchable, but it
|
|
92
|
+
is deliberately excluded from the bundled recommendation. Select it explicitly
|
|
93
|
+
when the cyber-sensitive refusal profile is required.
|
|
94
|
+
|
|
95
|
+
### Unresolvable selectors fall back to a default, silently
|
|
96
|
+
|
|
97
|
+
Probing showed that Cursor does not reject a malformed pin. It substitutes a
|
|
98
|
+
default for whichever component it cannot resolve, with no error or warning:
|
|
99
|
+
|
|
100
|
+
- An unknown family falls back to the default model. `claude-opus-9[effort=high]`
|
|
101
|
+
resolved to `cursor-grok-4.5-high-fast`.
|
|
102
|
+
- An unknown effort falls back to the family's default rung.
|
|
103
|
+
`claude-opus-5[effort=ultra]` resolved to `claude-opus-5-thinking-high`.
|
|
104
|
+
|
|
105
|
+
The default rung is family-specific, not a fixed value. In the live catalog
|
|
106
|
+
exactly one rung per family carries an unqualified display label, and that marks
|
|
107
|
+
the default: `claude-opus-5-high` shows as `Opus 5 1M` while
|
|
108
|
+
`claude-opus-5-medium` shows as `Opus 5 1M Medium`. The default is not always
|
|
109
|
+
high — `claude-opus-4-7-xhigh` shows as `Opus 4.7 1M` while
|
|
110
|
+
`claude-opus-4-7-high` is explicitly labeled `Opus 4.7 1M High`.
|
|
111
|
+
|
|
112
|
+
This makes a typo in a pinned selector more dangerous than a plain downgrade.
|
|
113
|
+
The pin silently tracks whatever Cursor currently designates as that family's
|
|
114
|
+
default, so a vendor-side change to the default rung alters capability with no
|
|
115
|
+
corresponding change in the repository.
|
|
116
|
+
|
|
117
|
+
Two consequences for pinning. A selector must be probe-verified per mapping
|
|
118
|
+
before it ships. And a probe whose requested rung happens to equal the family
|
|
119
|
+
default cannot, on its own, distinguish an honored effort parameter from an
|
|
120
|
+
ignored one; verify at least one non-default rung in the same family.
|
|
41
121
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
| `intelligent-recon` | `cursor-grok-4.5-medium` or `gpt-5.6-sol-medium` | `gpt-5.6-terra-high` | `gpt-5.6-sol-high` | Grok medium is a primary route; Sol medium is the conservative silent-miss alternative; Terra high is the cost-saving route. |
|
|
46
|
-
| `default-implementation` | `gpt-5.6-sol-medium` | `composer-2.5` for bounded, testable changes | `gpt-5.6-sol-high` or `claude-fable-5-thinking-high` | Sol is the conservative incumbent; `cursor-grok-4.5-medium` is a primary alternative for general implementation. Choose Fable for open-ended coherence; Sol for code-first execution. |
|
|
47
|
-
| `hard-reasoning` | `gpt-5.6-sol-high` | `cursor-grok-4.5-high` for architecture, ambiguous debugging, and incident diagnosis | `gpt-5.6-sol-xhigh` or `claude-fable-5-thinking-xhigh` | Narrow the task before downgrading. Do not infer equivalence between the two escalation efforts. |
|
|
48
|
-
| `consequential` | Cross-family author/reviewer pair, normally Sol xhigh plus Fable thinking xhigh | No routine economy route | Sol max plus Fable thinking max | For cyber-sensitive review, use `claude-opus-4-8-thinking-xhigh` or max instead of relying on Fable alone. Grok may contribute analysis but is never the sole reviewer. |
|
|
122
|
+
Neither an agent self-report nor a subagent card label is admissible evidence.
|
|
123
|
+
The card label drops the thinking qualifier and cannot distinguish the thinking
|
|
124
|
+
and non-thinking variants.
|
|
49
125
|
|
|
50
126
|
## Broader Cursor Routes
|
|
51
127
|
|
|
@@ -60,7 +136,7 @@ user's 2026-07-21 snapshot.
|
|
|
60
136
|
- Grok is never the sole final authority for a consequential factual, security,
|
|
61
137
|
incident, or architectural conclusion. Require tool evidence, citations,
|
|
62
138
|
logs, query results, or file references for load-bearing Grok claims, or
|
|
63
|
-
pair it with an independent
|
|
139
|
+
pair it with an eligible independent cross-family reviewer.
|
|
64
140
|
- CursorBench caveat: Cursor disclosed that Cursor repository data entered
|
|
65
141
|
Grok 4.5's training mixture. Treat its ranking as evidence of
|
|
66
142
|
competitiveness, not proof of superiority over nearby frontier models.
|
|
@@ -1,8 +1,26 @@
|
|
|
1
1
|
export type CursorPinSyntaxFamily = 'gpt-reasoning' | 'claude-effort' | 'composer-fast' | 'grok-effort-fast';
|
|
2
|
+
/**
|
|
3
|
+
* What a probe submitted and what the harness resolved it to, transcribed from
|
|
4
|
+
* the probe evidence.
|
|
5
|
+
*
|
|
6
|
+
* `submittedSelector` and `resolvedModel` restate the mapping's
|
|
7
|
+
* `frontmatterModel` and `ladderModelId`. That duplication is the mechanism and
|
|
8
|
+
* must not be refactored away: these fields are an independent transcription of
|
|
9
|
+
* an observation, so a mapping edited without re-probing disagrees with its own
|
|
10
|
+
* record and fails the consistency test. Deriving them from the mapping would
|
|
11
|
+
* make that test pass by construction and verify nothing.
|
|
12
|
+
*/
|
|
13
|
+
export interface CursorPinProbeRecord {
|
|
14
|
+
submittedSelector: string;
|
|
15
|
+
resolvedModel: string;
|
|
16
|
+
verifiedAt: string;
|
|
17
|
+
evidencePath: string;
|
|
18
|
+
}
|
|
2
19
|
export interface CursorPinGateEvidence {
|
|
3
20
|
gate: 'g01';
|
|
4
21
|
probeName: string;
|
|
5
22
|
disposition: 'approved';
|
|
23
|
+
probeRecord?: CursorPinProbeRecord;
|
|
6
24
|
}
|
|
7
25
|
export interface CursorModelPinMapping {
|
|
8
26
|
ladderModelId: string;
|
|
@@ -11,7 +29,7 @@ export interface CursorModelPinMapping {
|
|
|
11
29
|
gateEvidence: CursorPinGateEvidence;
|
|
12
30
|
catalogue: boolean;
|
|
13
31
|
}
|
|
14
|
-
export declare const CURSOR_MODEL_PIN_MAPPINGS: readonly [CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping];
|
|
32
|
+
export declare const CURSOR_MODEL_PIN_MAPPINGS: readonly [CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping, CursorModelPinMapping];
|
|
15
33
|
export declare const SUPPORTED_CURSOR_ROLE_TARGETS: CursorModelPinMapping[];
|
|
16
34
|
export declare const SUPPORTED_CURSOR_BASE_ROLES: readonly ['oat-phase-implementer', 'oat-reviewer'];
|
|
17
35
|
export declare function findCursorModelPinMapping(ladderModelId: string): CursorModelPinMapping | undefined;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/providers/cursor/codec/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GACf,eAAe,GACf,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../src/providers/cursor/codec/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GACf,eAAe,GACf,eAAe,GACf,kBAAkB,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,oBAAoB,CAAC;CACpC;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,qBAAqB,CAAC;IACpC,YAAY,EAAE,qBAAqB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;CACpB;AAqCD,eAAO,MAAM,yBAAyB,8eAyJe,CAAC;AAEtD,eAAO,MAAM,6BAA6B,yBAEzC,CAAC;AAEF,eAAO,MAAM,2BAA2B,YACtC,uBAAuB,EACvB,cAAc,CACN,CAAC;AAEX,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,qBAAqB,GAAG,SAAS,CAInC"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
function approvedMapping(ladderModelId, frontmatterModel, syntaxFamily, options = {}) {
|
|
2
|
+
const { probeRecord } = options;
|
|
2
3
|
return {
|
|
3
4
|
ladderModelId,
|
|
4
5
|
frontmatterModel,
|
|
@@ -8,10 +9,15 @@ function approvedMapping(ladderModelId, frontmatterModel, syntaxFamily, options
|
|
|
8
9
|
probeName: options.probeName ??
|
|
9
10
|
`oat-pin-probe-${ladderModelId.replaceAll('.', '-')}`,
|
|
10
11
|
disposition: 'approved',
|
|
12
|
+
...(probeRecord ? { probeRecord } : {}),
|
|
11
13
|
},
|
|
12
14
|
catalogue: options.catalogue ?? true,
|
|
13
15
|
};
|
|
14
16
|
}
|
|
17
|
+
const G01_PROBE_2026_07_25 = {
|
|
18
|
+
verifiedAt: '2026-07-25',
|
|
19
|
+
evidencePath: '.oat/projects/shared/opus-5-model-guidance/references/g01-probe-results.md',
|
|
20
|
+
};
|
|
15
21
|
export const CURSOR_MODEL_PIN_MAPPINGS = [
|
|
16
22
|
approvedMapping('composer-2.5', 'composer-2.5[fast=true]', 'composer-fast'),
|
|
17
23
|
approvedMapping('composer-2.5-fast', 'composer-2.5[fast=true]', 'composer-fast', { catalogue: false }),
|
|
@@ -26,6 +32,54 @@ export const CURSOR_MODEL_PIN_MAPPINGS = [
|
|
|
26
32
|
approvedMapping('claude-fable-5-thinking-high', 'claude-fable-5[effort=high]', 'claude-effort'),
|
|
27
33
|
approvedMapping('claude-fable-5-thinking-xhigh', 'claude-fable-5[effort=xhigh]', 'claude-effort'),
|
|
28
34
|
approvedMapping('claude-fable-5-xhigh', 'claude-fable-5[effort=xhigh]', 'claude-effort', { catalogue: false }),
|
|
35
|
+
approvedMapping('claude-opus-5-thinking-low', 'claude-opus-5[effort=low]', 'claude-effort', {
|
|
36
|
+
probeName: 'zz-pin-probe-opus5-low',
|
|
37
|
+
probeRecord: {
|
|
38
|
+
submittedSelector: 'claude-opus-5[effort=low]',
|
|
39
|
+
resolvedModel: 'claude-opus-5-thinking-low',
|
|
40
|
+
...G01_PROBE_2026_07_25,
|
|
41
|
+
},
|
|
42
|
+
}),
|
|
43
|
+
approvedMapping('claude-opus-5-thinking-medium', 'claude-opus-5[effort=medium]', 'claude-effort', {
|
|
44
|
+
probeName: 'zz-pin-probe-opus5-medium',
|
|
45
|
+
probeRecord: {
|
|
46
|
+
submittedSelector: 'claude-opus-5[effort=medium]',
|
|
47
|
+
resolvedModel: 'claude-opus-5-thinking-medium',
|
|
48
|
+
...G01_PROBE_2026_07_25,
|
|
49
|
+
},
|
|
50
|
+
}),
|
|
51
|
+
approvedMapping('claude-opus-5-thinking-high', 'claude-opus-5[effort=high]', 'claude-effort', {
|
|
52
|
+
probeName: 'zz-pin-probe-opus5-high',
|
|
53
|
+
probeRecord: {
|
|
54
|
+
submittedSelector: 'claude-opus-5[effort=high]',
|
|
55
|
+
resolvedModel: 'claude-opus-5-thinking-high',
|
|
56
|
+
...G01_PROBE_2026_07_25,
|
|
57
|
+
},
|
|
58
|
+
}),
|
|
59
|
+
approvedMapping('claude-opus-5-thinking-xhigh', 'claude-opus-5[effort=xhigh]', 'claude-effort', {
|
|
60
|
+
probeName: 'zz-pin-probe-opus5-xhigh',
|
|
61
|
+
probeRecord: {
|
|
62
|
+
submittedSelector: 'claude-opus-5[effort=xhigh]',
|
|
63
|
+
resolvedModel: 'claude-opus-5-thinking-xhigh',
|
|
64
|
+
...G01_PROBE_2026_07_25,
|
|
65
|
+
},
|
|
66
|
+
}),
|
|
67
|
+
approvedMapping('claude-opus-5-thinking-max', 'claude-opus-5[effort=max]', 'claude-effort', {
|
|
68
|
+
probeName: 'zz-pin-probe-opus5-max',
|
|
69
|
+
probeRecord: {
|
|
70
|
+
submittedSelector: 'claude-opus-5[effort=max]',
|
|
71
|
+
resolvedModel: 'claude-opus-5-thinking-max',
|
|
72
|
+
...G01_PROBE_2026_07_25,
|
|
73
|
+
},
|
|
74
|
+
}),
|
|
75
|
+
approvedMapping('claude-opus-4-8-thinking-xhigh', 'claude-opus-4-8[effort=xhigh]', 'claude-effort', {
|
|
76
|
+
probeName: 'zz-pin-probe-opus48-xhigh',
|
|
77
|
+
probeRecord: {
|
|
78
|
+
submittedSelector: 'claude-opus-4-8[effort=xhigh]',
|
|
79
|
+
resolvedModel: 'claude-opus-4-8-thinking-xhigh',
|
|
80
|
+
...G01_PROBE_2026_07_25,
|
|
81
|
+
},
|
|
82
|
+
}),
|
|
29
83
|
approvedMapping('gpt-5.6-sol-xhigh', 'gpt-5.6-sol[reasoning=xhigh]', 'gpt-reasoning'),
|
|
30
84
|
approvedMapping('gpt-5.6-sol-max', 'gpt-5.6-sol[reasoning=max]', 'gpt-reasoning'),
|
|
31
85
|
];
|