@open-agent-toolkit/cli 0.2.18 → 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.
@@ -1,8 +1,11 @@
1
1
  ---
2
- guidance_version: 2026-07-22
3
- last_verified: 2026-07-22
2
+ guidance_version: 2026-07-25
3
+ last_verified: 2026-07-25
4
4
  review_after: 2026-09-04
5
- catalog_basis: user-supplied Cursor snapshot plus current Cursor documentation
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
- measured wall-clock latency justifies the premium.
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 were present in the
40
- user's 2026-07-21 snapshot.
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
- | Task class | Default | Economy | Escalation | Floor notes |
43
- | ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
- | `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. |
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 Sol, Fable, or Opus reviewer.
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;CACzB;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;AA0BD,eAAO,MAAM,yBAAyB,oWA2Ee,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
+ {"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
  ];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-agent-toolkit/cli",
3
- "version": "0.2.18",
3
+ "version": "0.2.20",
4
4
  "private": false,
5
5
  "description": "Open Agent Toolkit CLI",
6
6
  "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
34
34
  "ora": "^9.0.0",
35
35
  "yaml": "2.8.2",
36
36
  "zod": "^3.25.76",
37
- "@open-agent-toolkit/control-plane": "0.2.18"
37
+ "@open-agent-toolkit/control-plane": "0.2.20"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/node": "^22.10.0",