pantheon-opencode 1.6.0-beta.9 → 1.6.1

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.
Files changed (140) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +144 -365
  4. package/README.md +124 -607
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +504 -141
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +22 -13
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +850 -45
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +99 -383
  29. package/scripts/install/interrupt.mjs +78 -0
  30. package/scripts/install/migrate.mjs +49 -25
  31. package/scripts/install/model-picker.mjs +218 -250
  32. package/scripts/install/opencode-state.mjs +91 -0
  33. package/scripts/install/opencode-version.mjs +83 -21
  34. package/scripts/install/opencode.mjs +1675 -187
  35. package/scripts/install/plan-artifact.mjs +517 -0
  36. package/scripts/install/plan.mjs +475 -0
  37. package/scripts/install/plugin.mjs +214 -27
  38. package/scripts/install/prompt-result.mjs +2 -0
  39. package/scripts/install/run-record.mjs +115 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +93 -8
  43. package/scripts/install/v2-capabilities.mjs +205 -0
  44. package/scripts/install/venv.mjs +90 -47
  45. package/scripts/install/verify.mjs +128 -0
  46. package/scripts/install/vision-prompt.mjs +173 -0
  47. package/scripts/install-mcp.mjs +2 -2
  48. package/scripts/manifest-inventory.mjs +49 -3
  49. package/scripts/mcp_persistence.py +1535 -1050
  50. package/scripts/memory_mcp.py +12 -843
  51. package/scripts/node-engine-policy.mjs +85 -0
  52. package/scripts/package-evidence.mjs +10 -2
  53. package/scripts/postinstall.mjs +26 -26
  54. package/scripts/probe-pantheon-cost.mjs +118 -19
  55. package/scripts/prune.mjs +9 -3
  56. package/scripts/reconcile.mjs +325 -0
  57. package/scripts/release-gates.mjs +687 -0
  58. package/scripts/restore.mjs +222 -0
  59. package/scripts/run-node-tests.mjs +24 -8
  60. package/scripts/sync-artifacts.mjs +19 -7
  61. package/scripts/sync-tui.mjs +5 -1
  62. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  63. package/scripts/uninstall.mjs +369 -34
  64. package/scripts/update.mjs +164 -0
  65. package/scripts/validate-node-engine-policy.mjs +13 -0
  66. package/scripts/version-check.mjs +34 -1
  67. package/scripts/versioning.mjs +23 -3
  68. package/scripts/vision-status.mjs +682 -0
  69. package/skills-lock.json +8 -8
  70. package/src/agents/aphrodite.md +13 -10
  71. package/src/agents/apollo.md +4 -5
  72. package/src/agents/athena.md +74 -46
  73. package/src/agents/demeter.md +10 -7
  74. package/src/agents/gaia.md +0 -1
  75. package/src/agents/hephaestus.md +4 -3
  76. package/src/agents/hermes.md +10 -9
  77. package/src/agents/iris.md +6 -1
  78. package/src/agents/mnemosyne.md +10 -4
  79. package/src/agents/nyx.md +4 -4
  80. package/src/agents/prometheus.md +12 -11
  81. package/src/agents/talos.md +6 -0
  82. package/src/agents/zeus.md +84 -56
  83. package/src/instructions/agent-return-format.instructions.md +12 -41
  84. package/src/instructions/memory-protocol.instructions.md +5 -11
  85. package/src/instructions/test-economy.instructions.md +12 -0
  86. package/src/instructions/yagni.instructions.md +6 -15
  87. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  88. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  89. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  90. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  91. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  92. package/src/mcp/_pantheon_paths.py +24 -0
  93. package/src/mcp/mcp_codemap_module.py +86 -18
  94. package/src/mcp/mcp_persistence.py +1535 -1050
  95. package/src/mcp/memory_mcp.py +444 -94
  96. package/src/mcp/pantheon_vision.py +285 -41
  97. package/src/mcp/requirements-mcp.txt +6 -1
  98. package/src/mcp/requirements-vision.txt +1 -1
  99. package/src/pantheon/context-pruner.ts +541 -0
  100. package/src/pantheon/cost-command.ts +901 -60
  101. package/src/pantheon/delegation-enforce.ts +160 -23
  102. package/src/pantheon/goal-loop.ts +11 -8
  103. package/src/pantheon/guard-path.ts +162 -0
  104. package/src/pantheon/memory-context.ts +1017 -0
  105. package/src/pantheon/model-agents.ts +19 -0
  106. package/src/pantheon/model-command.ts +218 -56
  107. package/src/pantheon/model-pricing.ts +536 -0
  108. package/src/pantheon/presets.mjs +2 -0
  109. package/src/pantheon/task-result-guard.ts +50 -14
  110. package/src/pantheon/v2-bounded-read.ts +654 -0
  111. package/src/pantheon/v2-bridge.ts +27 -0
  112. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  113. package/src/pantheon/v2-execute-after.ts +135 -24
  114. package/src/pantheon/v2-model-overrides.ts +275 -0
  115. package/src/pantheon/v2-shell-hooks.ts +260 -0
  116. package/src/pantheon/v2-tools.ts +89 -35
  117. package/src/pantheon/v2-unsupported.mjs +34 -7
  118. package/src/pantheon/v2-vision.ts +622 -0
  119. package/src/pantheon/vision-local.ts +531 -0
  120. package/src/pantheon/vision.ts +1166 -116
  121. package/src/plugin-v2.ts +1039 -171
  122. package/src/plugin.ts +37 -13
  123. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  124. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  125. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  126. package/src/plugins/tui/dist/tui.js +1 -1
  127. package/src/plugins/tui/package-lock.json +15 -15
  128. package/src/plugins/tui/package.json +7 -5
  129. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  130. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  131. package/src/routing.yml +50 -5
  132. package/src/skills/agent-coordination/SKILL.md +7 -2
  133. package/src/skills/artifact-management/SKILL.md +5 -1
  134. package/src/skills/auto-continue/SKILL.md +14 -6
  135. package/src/skills/codemap/SKILL.md +1 -1
  136. package/src/skills/memory-bank/SKILL.md +21 -13
  137. package/src/skills/session-goal/SKILL.md +12 -22
  138. package/src/skills/spec-driven-development/SKILL.md +3 -1
  139. package/src/skills/worktrees/SKILL.md +30 -11
  140. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -0,0 +1,260 @@
1
+ /**
2
+ * V2 shell-hook parity — the two V1 shell hooks that had no V2 equivalent.
3
+ *
4
+ * V1 runs them from `src/plugins/pantheon-hooks.ts` (`tool.execute.before` /
5
+ * `tool.execute.after`):
6
+ *
7
+ * - `format-multi-language.sh` on every completed tool call (post-write
8
+ * formatting);
9
+ * - `on-subagent-delegation-start.sh` / `-stop.sh`, which append the
10
+ * `delegations.log` audit records (start/stop joined on `delegation_id`).
11
+ *
12
+ * `pantheon-hooks.ts` is a SEPARATE plugin and is never loaded on a V2-only
13
+ * install — `opencode.json` `plugins` declares only `src/plugin-v2` — so both
14
+ * were dead on V2. The scripts themselves are environment-independent (they
15
+ * read the Claude Code payload from stdin and write their own log files), so
16
+ * they are run through the same `runHook` runner the secret scan already uses;
17
+ * no V1 plugin import is needed and none is introduced.
18
+ *
19
+ * What is derived here, and why it is not a second implementation of V1:
20
+ *
21
+ * - `delegation_id` — a UUID generated in the BEFORE hook and carried to the
22
+ * STOP hook through a callID-keyed record, which is how the two log lines
23
+ * join (V1 does the same in `pantheon-hooks.ts`).
24
+ * - `agent_id` — `tool_input.subagent_type` (or `agent`/`target`) first, the
25
+ * tool name last, mirroring V1's `delegationAgent`. The AFTER-time args are
26
+ * never used to derive it, because a background dispatch returns
27
+ * `{task_id, state}` there and no agent.
28
+ * - `status` — `failure` on an error event, `dispatched` when the result
29
+ * carries a `task_id` or a running/queued state, `success` otherwise. A
30
+ * background dispatch is DISPATCH, never a fabricated success.
31
+ *
32
+ * Fail-open by contract: every call is wrapped, so a missing script, a timeout
33
+ * or a malformed payload can never break the tool call it observes. The audit
34
+ * trail is telemetry; the security decisions live in the guards, not here.
35
+ *
36
+ * @module v2-shell-hooks
37
+ */
38
+
39
+ import { randomUUID } from 'node:crypto'
40
+ import { type HookPayload, type HookResult, runHook } from '../plugins/hook-runner.ts'
41
+
42
+ /**
43
+ * Delegation tool names. MIRRORS `DELEGATION_TOOL_RE` in
44
+ * `src/plugins/pantheon-hooks.ts` (V1). Duplicated rather than imported: that
45
+ * module is the V1 plugin, not loaded on a V2-only install, and importing it
46
+ * for one regex would resurrect the V1 coupling V2 exists to remove. The drift
47
+ * risk is asserted by tests/pantheon/v2-shell-hooks.test.ts.
48
+ */
49
+ export const V2_DELEGATION_TOOL_RE = /^(task|.*subagent.*)$/i
50
+
51
+ /** Scripts, by the names `scripts/hooks/` ships. */
52
+ export const FORMATTER_SCRIPT = 'format-multi-language.sh'
53
+ export const DELEGATION_START_SCRIPT = 'on-subagent-delegation-start.sh'
54
+ export const DELEGATION_STOP_SCRIPT = 'on-subagent-delegation-stop.sh'
55
+
56
+ /** One script invocation. Injected in tests to avoid spawning a shell. */
57
+ export type V2ShellRunner = (script: string, payload: HookPayload) => Promise<HookResult>
58
+
59
+ const defaultRunner: V2ShellRunner = (script, payload) => runHook(script, payload)
60
+
61
+ /** Hard cap on pending records — a tool result may never arrive. */
62
+ const MAX_PENDING_STARTS = 256
63
+
64
+ interface DelegationStart {
65
+ delegationId: string
66
+ agent: string
67
+ startedAt: number
68
+ }
69
+
70
+ /** The `execute.before` fields this module reads. */
71
+ interface V2BeforeEvent {
72
+ tool?: unknown
73
+ sessionID?: unknown
74
+ agent?: unknown
75
+ id?: unknown
76
+ input?: unknown
77
+ }
78
+
79
+ /** The `execute.after` fields this module reads. */
80
+ interface V2AfterEvent extends V2BeforeEvent {
81
+ status?: unknown
82
+ result?: unknown
83
+ }
84
+
85
+ /** Payload with the lifecycle keys the audit scripts read. */
86
+ type AuditPayload = HookPayload & Record<string, unknown>
87
+
88
+ function text(value: unknown): string {
89
+ return typeof value === 'string' ? value : ''
90
+ }
91
+
92
+ /** `tool_input.subagent_type` (or agent/target) first, the tool name last. */
93
+ export function delegationAgent(tool: string, args: unknown): string {
94
+ if (args !== null && typeof args === 'object') {
95
+ const record = args as Record<string, unknown>
96
+ for (const key of ['subagent_type', 'subagentType', 'agent', 'target']) {
97
+ const candidate = record[key]
98
+ if (typeof candidate === 'string' && candidate.trim() !== '') return candidate
99
+ }
100
+ }
101
+ return tool
102
+ }
103
+
104
+ /** Task id from a background dispatch result, or '' when absent. */
105
+ export function extractTaskID(result: unknown): string {
106
+ if (result === null || typeof result !== 'object') return ''
107
+ const record = result as Record<string, unknown>
108
+ const direct = record.task_id ?? record.taskID
109
+ if (typeof direct === 'string') return direct
110
+ const metadata = record.metadata
111
+ if (metadata !== null && typeof metadata === 'object') {
112
+ const nested = (metadata as Record<string, unknown>).task_id
113
+ if (typeof nested === 'string') return nested
114
+ }
115
+ return ''
116
+ }
117
+
118
+ /** `success` | `failure` | `dispatched`, never a fabricated success. */
119
+ export function delegationStatus(event: V2AfterEvent): string {
120
+ if (event.status === 'error') return 'failure'
121
+ const result = event.result
122
+ if (result !== null && typeof result === 'object') {
123
+ const metadata = (result as Record<string, unknown>).metadata
124
+ if (metadata !== null && typeof metadata === 'object') {
125
+ for (const key of ['status', 'state']) {
126
+ const value = (metadata as Record<string, unknown>)[key]
127
+ if (
128
+ typeof value === 'string' &&
129
+ /^(running|queued|pending|scheduled)$/i.test(value.trim())
130
+ ) {
131
+ return 'dispatched'
132
+ }
133
+ }
134
+ }
135
+ }
136
+ return extractTaskID(result) !== '' ? 'dispatched' : 'success'
137
+ }
138
+
139
+ /**
140
+ * Build the two V2 shell-hook handlers.
141
+ *
142
+ * `run` and `now` exist for tests; production uses `runHook` and `Date.now`.
143
+ */
144
+ export function createV2ShellHooks(
145
+ options: {
146
+ run?: V2ShellRunner
147
+ now?: () => number
148
+ /** Diagnostic sink for the unkeyed-event case (wired to hooks.log). */
149
+ onUnkeyed?: (message: string) => void
150
+ } = {},
151
+ ): {
152
+ before(event: unknown): Promise<void>
153
+ after(event: unknown): Promise<void>
154
+ } {
155
+ const run = options.run ?? defaultRunner
156
+ const now = options.now ?? Date.now
157
+ const starts = new Map<string, DelegationStart>()
158
+ /** Set once: a host that never sends `id` must not flood the log. */
159
+ let unkeyedWarned = false
160
+ const warnUnkeyed = (phase: string): void => {
161
+ if (unkeyedWarned) return
162
+ unkeyedWarned = true
163
+ options.onUnkeyed?.(
164
+ `[delegation-audit] ${phase} event carries no tool call id; the audit record was skipped ` +
165
+ 'because a START without a key can never be joined by its STOP',
166
+ )
167
+ }
168
+
169
+ /** Fire and swallow: telemetry must never break the observed tool call. */
170
+ const fire = async (script: string, payload: AuditPayload): Promise<void> => {
171
+ try {
172
+ await run(script, payload)
173
+ } catch {
174
+ // Deliberately silent: the scripts log their own failures, and a thrown
175
+ // audit hook would turn a completed tool call into an error.
176
+ }
177
+ }
178
+
179
+ const basePayload = (event: V2BeforeEvent): AuditPayload => ({
180
+ tool_name: text(event.tool),
181
+ tool_input: event.input ?? {},
182
+ agent_id: text(event.agent),
183
+ session_id: text(event.sessionID),
184
+ })
185
+
186
+ return {
187
+ async before(rawEvent: unknown): Promise<void> {
188
+ if (rawEvent === null || typeof rawEvent !== 'object') return
189
+ const event = rawEvent as V2BeforeEvent
190
+ const tool = text(event.tool)
191
+ if (!V2_DELEGATION_TOOL_RE.test(tool)) return
192
+ const callID = text(event.id)
193
+ if (callID === '') {
194
+ // A START record with no joinable key is a record that can never be
195
+ // closed: the after-event carries no id either, so the STOP would have
196
+ // to omit `delegation_id` and the audit log would hold an orphan line
197
+ // forever. Refuse to write it, and say so once.
198
+ warnUnkeyed('execute.before')
199
+ return
200
+ }
201
+ const start: DelegationStart = {
202
+ delegationId: randomUUID(),
203
+ agent: delegationAgent(tool, event.input),
204
+ startedAt: now(),
205
+ }
206
+ while (starts.size >= MAX_PENDING_STARTS) {
207
+ const oldest = starts.keys().next().value
208
+ if (oldest === undefined) break
209
+ starts.delete(oldest)
210
+ }
211
+ starts.set(callID, start)
212
+ await fire(DELEGATION_START_SCRIPT, {
213
+ ...basePayload(event),
214
+ agent_id: start.agent,
215
+ delegation_id: start.delegationId,
216
+ })
217
+ },
218
+
219
+ async after(rawEvent: unknown): Promise<void> {
220
+ if (rawEvent === null || typeof rawEvent !== 'object') return
221
+ const event = rawEvent as V2AfterEvent
222
+ const tool = text(event.tool)
223
+ const payload = basePayload(event)
224
+ // V1 runs the formatter on every after-event; the script no-ops when the
225
+ // tool call touched no file it recognises.
226
+ await fire(FORMATTER_SCRIPT, payload)
227
+ if (!V2_DELEGATION_TOOL_RE.test(tool)) return
228
+ const callID = text(event.id)
229
+ if (callID === '') {
230
+ // Mirrors the before-hook: no key means no join, so no record.
231
+ warnUnkeyed('execute.after')
232
+ return
233
+ }
234
+ const start = starts.get(callID)
235
+ starts.delete(callID)
236
+ const taskID = extractTaskID(event.result)
237
+ await fire(DELEGATION_STOP_SCRIPT, {
238
+ ...payload,
239
+ ...(start === undefined
240
+ ? {
241
+ // No BEFORE record (the call was rejected before the audit ran, or
242
+ // the record was evicted). The STOP still needs a key field to be a
243
+ // well-formed audit line, so it gets a fresh one — an orphan STOP,
244
+ // never an unkeyed one.
245
+ delegation_id: randomUUID(),
246
+ }
247
+ : {
248
+ // The BEFORE-time agent wins: the AFTER-time args may carry the
249
+ // merged background result, which has no subagent_type.
250
+ agent_id: start.agent,
251
+ delegation_id: start.delegationId,
252
+ duration_ms: Math.max(0, now() - start.startedAt),
253
+ }),
254
+ status: delegationStatus(event),
255
+ tool_output: event.result ?? null,
256
+ ...(taskID === '' ? {} : { task_id: taskID }),
257
+ })
258
+ },
259
+ }
260
+ }
@@ -2,7 +2,7 @@
2
2
  * V2 tool surface — the Pantheon tools that are self-sufficient on the
3
3
  * OpenCode V2 host, declared for `ctx.tool.transform`'s `draft.add`.
4
4
  *
5
- * ## Why only three tools
5
+ * ## Why only three unconditional tools
6
6
  *
7
7
  * A V2 tool can only be served here when it needs no V1 infrastructure. The
8
8
  * three goal tools (`pantheon_goal_create`, `pantheon_goal_get`,
@@ -18,6 +18,15 @@
18
18
  * `pantheon_model` (reads/writes `active-preset.json`) need none of that, so
19
19
  * they are wired to their real V1 implementations.
20
20
  *
21
+ * ## Three unconditional tools, up to two host-dependent ones
22
+ *
23
+ * The three above are always built. Two more exist on the V2 host and are
24
+ * conditional: `vision_describe` is added here when the caller supplies a
25
+ * vision runtime (the host model catalog), and `pantheon_bounded_read` is
26
+ * appended by the plugin when the host exposes its permission and session APIs
27
+ * (root Zeus sessions only). The effective count is therefore 3 unconditional
28
+ * plus up to 2 host-dependent — never a flat 3.
29
+ *
21
30
  * ## The output declaration is mandatory
22
31
  *
23
32
  * The host enforces a biconditional between a tool's declared `output` and the
@@ -40,6 +49,7 @@ import { createCostCommand } from './cost-command.ts'
40
49
  import { createHashlineEditTool, type HashlineToolResult } from './hashline/tool.ts'
41
50
  import { createModelCommand } from './model-command.ts'
42
51
  import type { ToolContextLike } from './tool-context.ts'
52
+ import { createV2VisionTool, type V2VisionRuntime } from './v2-vision.ts'
43
53
 
44
54
  // ─── Contract types ─────────────────────────────────────────────────────
45
55
 
@@ -283,6 +293,17 @@ const COST_INPUT: Record<string, unknown> = {
283
293
  maximum: 365,
284
294
  description: 'Reporting window in days (default 7).',
285
295
  },
296
+ session: {
297
+ type: 'string',
298
+ minLength: 1,
299
+ description:
300
+ 'Root session id. The report is scoped to that session plus every descendant session in its subtree.',
301
+ },
302
+ refreshPricing: {
303
+ type: 'boolean',
304
+ description:
305
+ 'Await a models.dev price refresh (bounded by a short timeout) instead of using the cached catalog. This is the only path that waits on the network.',
306
+ },
286
307
  },
287
308
  }
288
309
 
@@ -295,6 +316,28 @@ function coerceDays(value: unknown): { ok: true; days?: number } | { ok: false;
295
316
  return { ok: true, days: value }
296
317
  }
297
318
 
319
+ /** Validate `session` exactly as the V1 zod schema does; absent means no scope. */
320
+ function coerceSession(
321
+ value: unknown,
322
+ ): { ok: true; session?: string } | { ok: false; error: string } {
323
+ if (value === undefined) return { ok: true }
324
+ if (typeof value !== 'string' || value.length === 0) {
325
+ return { ok: false, error: 'pantheon_cost: "session" must be a non-empty string' }
326
+ }
327
+ return { ok: true, session: value }
328
+ }
329
+
330
+ /** Validate `refreshPricing` exactly as the V1 zod schema does; absent means cached. */
331
+ function coerceRefreshPricing(
332
+ value: unknown,
333
+ ): { ok: true; refreshPricing?: boolean } | { ok: false; error: string } {
334
+ if (value === undefined) return { ok: true }
335
+ if (typeof value !== 'boolean') {
336
+ return { ok: false, error: 'pantheon_cost: "refreshPricing" must be a boolean' }
337
+ }
338
+ return { ok: true, refreshPricing: value }
339
+ }
340
+
298
341
  const costCommand = createCostCommand()
299
342
 
300
343
  async function executeCost(
@@ -303,14 +346,29 @@ async function executeCost(
303
346
  ): Promise<V2ToolResult> {
304
347
  const days = coerceDays(input.days)
305
348
  if (!days.ok) return { output: days.error }
349
+ const session = coerceSession(input.session)
350
+ if (!session.ok) return { output: session.error }
351
+ const refreshPricing = coerceRefreshPricing(input.refreshPricing)
352
+ if (!refreshPricing.ok) return { output: refreshPricing.error }
353
+ // Every accepted option is forwarded: a schema the host validates but the
354
+ // wrapper drops would be a tool that silently ignores its own arguments.
306
355
  // The V1 tool already wraps its whole body and reports failures as text.
307
- const output = await costCommand.pantheon_cost.execute({ days: days.days }, toolContext(context))
356
+ const output = await costCommand.pantheon_cost.execute(
357
+ {
358
+ ...(days.days === undefined ? {} : { days: days.days }),
359
+ ...(session.session === undefined ? {} : { session: session.session }),
360
+ ...(refreshPricing.refreshPricing === undefined
361
+ ? {}
362
+ : { refreshPricing: refreshPricing.refreshPricing }),
363
+ },
364
+ toolContext(context),
365
+ )
308
366
  return { output }
309
367
  }
310
368
 
311
369
  // ─── pantheon_model ─────────────────────────────────────────────────────
312
370
 
313
- /** JSON Schema for `pantheon_model`, mirroring the V1 zod args. */
371
+ /** JSON Schema for V2 `pantheon_model`; global scope is intentionally absent. */
314
372
  const MODEL_INPUT: Record<string, unknown> = {
315
373
  type: 'object',
316
374
  additionalProperties: false,
@@ -329,39 +387,27 @@ const MODEL_INPUT: Record<string, unknown> = {
329
387
  },
330
388
  scope: {
331
389
  type: 'string',
332
- enum: ['project', 'global'],
333
- description: 'Scope for active-preset.json (default project).',
334
- },
335
- confirm: {
336
- type: 'boolean',
337
- description: 'Explicit confirmation for a mutating operation; required for global changes.',
338
- },
339
- authorize_global: {
340
- type: 'boolean',
341
- description: 'Separate authorization for global configuration; not implied by confirm.',
390
+ enum: ['project'],
391
+ description: 'Project scope only; global overrides are not supported in V2.',
342
392
  },
343
393
  },
344
394
  }
345
395
 
346
- const WIZARD_UNAVAILABLE =
347
- 'the interactive wizard has no user in the V2 tool surface — pass action="status" to read ' +
348
- 'the current overrides, or pass agent and model explicitly for action="set"'
349
-
350
- /**
351
- * The V1 command falls back to an interactive readline prompt when invoked
352
- * with no arguments. A tool call has no user at the terminal, so that fallback
353
- * would block the call until it timed out. `ask` is injected to refuse
354
- * deterministically instead, which routes through the command's own
355
- * `wizard canceled` error path rather than forking its logic.
356
- */
357
- const modelCommand = createModelCommand({
358
- ask: () => Promise.reject(new Error(WIZARD_UNAVAILABLE)),
359
- })
396
+ const modelCommand = createModelCommand({ v2Mode: true })
360
397
 
361
398
  async function executeModel(
362
399
  input: Record<string, unknown>,
363
400
  context: unknown,
364
401
  ): Promise<V2ToolResult> {
402
+ if (input.scope !== undefined && input.scope !== 'project') {
403
+ return { output: 'Error: V2 pantheon_model is project-only; global scope is not supported.' }
404
+ }
405
+ if (Object.hasOwn(input, 'confirm') || Object.hasOwn(input, 'authorize_global')) {
406
+ return {
407
+ output:
408
+ 'Error: V2 pantheon_model does not accept authorization flags; global authorization is not supported by this tool.',
409
+ }
410
+ }
365
411
  // The V1 tool validates its own args (zod) and reports failures as text.
366
412
  const output = await modelCommand.pantheon_model.execute(
367
413
  input as Parameters<typeof modelCommand.pantheon_model.execute>[0],
@@ -388,8 +434,8 @@ async function executeModel(
388
434
  * performs filesystem or database work at construction, so importing this
389
435
  * module stays side-effect free.
390
436
  */
391
- export function createV2ToolDefinitions(): V2ToolDef[] {
392
- return [
437
+ export function createV2ToolDefinitions(visionRuntime?: V2VisionRuntime): V2ToolDef[] {
438
+ const definitions: V2ToolDef[] = [
393
439
  {
394
440
  name: 'hashline_edit',
395
441
  description:
@@ -405,8 +451,13 @@ export function createV2ToolDefinitions(): V2ToolDef[] {
405
451
  {
406
452
  name: 'pantheon_cost',
407
453
  description:
408
- 'Report input, output, and total token usage by agent and phase over the last N days, ' +
409
- 'read from opencode.db (read-only, no monetary values).',
454
+ 'Report token usage and USD cost by agent and phase, by model, and by session, over the ' +
455
+ 'last N days from opencode.db (read-only). Costs come from the models.dev catalog cached ' +
456
+ 'on disk: a call reads that cache and never waits on the network unless refreshPricing is ' +
457
+ 'set, a stale cache is refreshed in the background and the report says so, and an unpriced ' +
458
+ 'model reads — and is excluded from the totals, which then say partial. Pass session=<root ' +
459
+ 'session id> to aggregate that session plus its descendant sessions. Phase may be unknown ' +
460
+ 'on V2; costs are catalog list prices, not an invoice.',
410
461
  input: COST_INPUT,
411
462
  output: {},
412
463
  execute: executeCost,
@@ -414,13 +465,16 @@ export function createV2ToolDefinitions(): V2ToolDef[] {
414
465
  {
415
466
  name: 'pantheon_model',
416
467
  description:
417
- 'Show, set, or reset per-agent model overrides in active-preset.json (project or global). ' +
418
- 'Overrides win over preset; env preset wins over file. Never writes .env or top-level ' +
419
- 'model/small_model. Pass action="status" to read the current overrides; unlike the V1 ' +
420
- 'command there is no interactive wizard on this surface.',
468
+ 'Show, set, or reset explicit per-agent project-scoped model overrides in active-preset.json. ' +
469
+ 'V2 ignores static preset names and PANTHEON_MODEL_PRESET; no wizard or implicit model ' +
470
+ 'selection. Global overrides are not read or written in V2; future global support requires ' +
471
+ 'separate explicit authorization. Pass action="status" to read project-scoped overrides. ' +
472
+ 'Never writes .env or top-level model/small_model.',
421
473
  input: MODEL_INPUT,
422
474
  output: {},
423
475
  execute: executeModel,
424
476
  },
425
477
  ]
478
+ if (visionRuntime) definitions.push(createV2VisionTool(visionRuntime))
479
+ return definitions
426
480
  }
@@ -21,9 +21,8 @@
21
21
  * So a `.mjs` import is the only form all three consumers can share, and it
22
22
  * matches the existing `src/pantheon/presets.mjs` + `.d.mts` precedent.
23
23
  *
24
- * NOT the reason: type-stripping. `package.json#engines` admits
25
- * `^22.22.2 || ^24.15.0 || >=26.0.0`, every admitted version already defaults to
26
- * unflagged type-stripping (it landed in 22.18.0), so that argument would not
24
+ * NOT the reason: type-stripping. `package.json#engines` admits Node >=26.4.0,
25
+ * which defaults to unflagged type-stripping (it landed in 22.18.0), so that argument would not
27
26
  * have held on any admitted version. The live hazard is that `engines` is not
28
27
  * ENFORCED: a Node 20 user can run `doctor` and would get no type-stripping,
29
28
  * which is an argument for a runtime version check, not for this file's shape.
@@ -69,11 +68,39 @@ export const V2_UNSUPPORTED_FEATURE_SEED = Object.freeze([
69
68
  // transform, which a live 2.0.22 host does provide.
70
69
  'skill-transform',
71
70
  // Adapter limitation, not a host gap: the goal loop needs a GoalStore, a
72
- // GoalLoopClient and a BackgroundJobBoard, none of which the V2
73
- // PluginContext exposes, and the V1 bridge resolves to null outside V1.
74
- // pantheon_goal_create/get/update are therefore absent from the V2 surface
75
- // rather than registered as non-functional placeholders.
71
+ // GoalLoopClient and a BackgroundJobBoard. V2 has no `client` to build the
72
+ // loop's session calls, and the bridge the V2 entry injects deliberately
73
+ // carries the board and the todo enforcer only, so
74
+ // pantheon_goal_create/get/update stay absent from the V2 surface rather
75
+ // than being registered as non-functional placeholders.
76
76
  'goal-tools',
77
+ // CONDITIONAL reduction (issue #265/#267): the V2 entry DOES construct the
78
+ // V1 TodoEnforcer and inject it through the bridge, but only when the host's
79
+ // `session` domain exposes the four methods the enforcer uses (`todo`,
80
+ // `messages`, `children`, `promptAsync`). The measured 2.1.4 domain exposes
81
+ // `hook`/`get`/`list`/`create`/`remove`/`prompt`/`generate`/… and NOT the
82
+ // four, so on that host idle continuation does not run and the enforcer is
83
+ // not constructed — the limitation is announced here instead of being hidden
84
+ // behind a null bridge. V1 reaches those calls through `client.session`.
85
+ 'idle-todo-enforcer',
86
+ // Todo preservation across compaction (`todo-preserve.ts`): V1 captures the
87
+ // session's todo list in `experimental.session.compacting`, activates the
88
+ // snapshot on `session.compacted` and rewrites the first post-compaction
89
+ // `todowrite`. V2 has no todo API to capture from, so the snapshot is absent
90
+ // and the first `todowrite` is not rewritten.
91
+ 'todo-restore',
92
+ // The `<tool_ceiling>` block fed by `handleToolCeilingEvent` on V1
93
+ // (`message.updated`). V2's event route handles session.* events only, so
94
+ // there is no producer for the host-reported remaining context budget and
95
+ // the block is not injected into the compaction context.
96
+ 'tool-ceiling',
97
+ // BackgroundJobBoard bookkeeping: the shared board INSTANCE is reachable on
98
+ // V2 through the injected bridge, but the transitions that make it useful
99
+ // (onTerminal audit line, terminal reports on session.idle, dispatch mirror
100
+ // for native background tasks) are driven from V1's event hook and from
101
+ // pantheon-hooks.ts, neither of which a V2-only install loads. The board is
102
+ // present; nothing on V2 writes to it.
103
+ 'board-transitions',
77
104
  ])
78
105
 
79
106
  /**