pantheon-opencode 1.6.2-beta.15 → 1.6.2-beta.17

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/CHANGELOG.md CHANGED
@@ -10,6 +10,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
10
10
  <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
11
11
  move this section to a versioned entry and reset the template below. -->
12
12
 
13
+ ## [v1.6.2-beta.17] - 2026-11-03
14
+
15
+ ### Added
16
+
17
+ - **routing** — J2 skill-selection scorecard harness: an offline, rerunnable, dated scorecard (29 synthetic scenarios including adversarial injection and refusal shapes, every Jev reply faked — zero network) measuring the P2 prefilter and the skills preset against expected picks, with honest negatives recorded in `bench/results/`. Activation gate: two consecutive scorecards, separately reviewed.
18
+ - **hooks** — J3 turn-complexity escalation policy (shadow): when `PANTHEON_J3_ESCALATION` is on, delegate dispatches get one Jev complexity classification resolved cheap-vs-main through a pure policy with independent local rails (risk-word states never downgrade, user-pinned models always win, oversize context never downgrades, uncertainty resolves to main). Structurally shadow-only — the wiring cannot reach the override mechanism (contract-test enforced); the mechanism itself is proven by direct tests for the separately reviewed activation. Default off.
19
+ - **routing** — J4 output quality scoring: a new `mode: "review"` on `pantheon_jev_decide` scores a delegated result against caller-named criteria (one round-trip: quality score + needs-human-review predicate). The request carries no result content — only delegate id, result kind, shape metrics, and bounded criteria. Advisory flag only; nothing blocks. On demand (Zeus-only, same consent/caps/permission chain).
20
+
21
+ ## [v1.6.2-beta.16] - 2026-11-03
22
+
23
+ ### Added
24
+
25
+ - **hooks** — J1 risk-score advisory gate (shadow): when `PANTHEON_J1_RISK_SCORE` is on, exfil-capable tool calls get one Jev risk-score + intent-predicate observation through the same gate chain as `pantheon_jev_decide` (consent, budget caps, `decision.egress` permission). Shadow only — the verdict is always observed, never enforced; nothing blocks or delays (2s abandon, fail-open on every failure mode). The request carries zero user content: tool name token, scope class, input hash only. Default off.
26
+
13
27
  ## [v1.6.2-beta.15] - 2026-11-03
14
28
 
15
29
  ### Added
package/README.md CHANGED
@@ -212,7 +212,27 @@ credentials cannot activate it. Native child-session dispatch remains separate.
212
212
  The one native egress surface is the Zeus-only `pantheon_jev_decide` tool,
213
213
  available on hosts that expose the V2.2.5 native Decisions API; its full gate
214
214
  chain, routes, and settlement rules are documented once in
215
- [V2 native Decisions](docs/reference/native-decisions.md).
215
+ [V2 native Decisions](docs/reference/native-decisions.md). An opt-in second
216
+ consumer of that chain, the J1 risk-score shadow gate, fires one bounded
217
+ native decision per write/execute tool call behind `PANTHEON_J1_RISK_SCORE`
218
+ (off by default, zero overhead when off): the request carries no user content
219
+ (tool name token, scope class, input sha256 only), every failure mode skips
220
+ silently with a reason token, and the shadow record is the whole effect — it
221
+ never blocks, asks, or narrows a permission. A third opt-in consumer, the J3
222
+ turn-complexity escalation, runs in shadow behind `PANTHEON_J3_ESCALATION`
223
+ (off by default): it classifies each delegate dispatch with one bounded score
224
+ question (Brief sha256, length and a risk-word flag only — the Brief text
225
+ never leaves the machine), local rails (risk words, user-pinned models, large
226
+ context) and every unsure answer always favor the main model, and the recorded
227
+ verdict never changes the dispatched model — the per-agent override mechanism
228
+ is proved by test and reserved for a separately reviewed activation with its
229
+ own measured baseline. A fourth consumer needs no flag at all: the tool's
230
+ `mode: "review"` (J4 output-quality scoring) runs only when Zeus explicitly
231
+ asks, after a delegation completes — one typed round-trip returns an advisory
232
+ quality score against named criteria plus a needs-review flag. The result
233
+ content never leaves the machine (shape metrics and criteria only, hostile
234
+ criteria rejected outright), and the verdict is advisory telemetry plus a
235
+ flag: it never blocks, retries, or alters the delegated result.
216
236
 
217
237
  The installer may retain a legacy target-specific preference; it does not control
218
238
  runtime routing. `npx pantheon-opencode decision-router ...` manages stored
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pantheon-opencode",
3
- "version": "1.6.2-beta.15",
3
+ "version": "1.6.2-beta.17",
4
4
  "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
5
5
  "type": "module",
6
6
  "workspaces": [
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pantheon",
3
3
  "publisher": "ils15",
4
- "version": "1.6.2-beta.15",
4
+ "version": "1.6.2-beta.17",
5
5
  "displayName": "Pantheon",
6
6
  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 20 skills, and OpenCode support.",
7
7
  "agents": "./src/agents",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
4
4
 
5
5
  [project]
6
6
  name = "pantheon"
7
- version = "1.6.2-beta.15"
7
+ version = "1.6.2-beta.17"
8
8
  description = "Multi-agent orchestration framework"
9
9
  requires-python = ">=3.11"
10
10
  # Python sources under src/mcp/ import fastmcp/pydantic at runtime, but those
@@ -12,6 +12,11 @@
12
12
  * preparer. Transport is the host's own provider layer: this module never
13
13
  * touches fetch, endpoints, or credentials.
14
14
  *
15
+ * The gate chain lives in {@link runGatedNativeJevCall} so a second caller (the
16
+ * J1 risk-score shadow gate in `jev-risk-gate.ts`) reuses the exact same
17
+ * config → route → permission → reserve → decide → reconcile sequence instead
18
+ * of duplicating it; only the request preparer is caller-supplied.
19
+ *
15
20
  * Settlement follows the fetch runner's fail-closed contract: reserve before
16
21
  * the call, reconcile from the host-reported cost after it, and leave the
17
22
  * reservation pending (budget held for the period) when no evidence can be
@@ -21,14 +26,26 @@ import { readUserDecisionRouterConfig } from '../../scripts/install/decision-rou
21
26
  import {
22
27
  consumeJevDecisionResult,
23
28
  isJevDecisionPreset,
29
+ type JevDecisionPreparation,
24
30
  type JevHostSkill,
25
31
  type NativeJevRouteFailure,
32
+ type NativeJevRouteSelection,
26
33
  prepareJevDecisionRequest,
27
34
  prepareJevPresetRequest,
28
35
  resolveNativeJevRoute,
29
36
  } from './jev-decisions.ts'
37
+ import {
38
+ buildJevReviewRequest,
39
+ encodeQualityScoreReason,
40
+ evaluateQualityScoreDecision,
41
+ J4_QUALITY_SCORE_POINT,
42
+ type QualityScoreEvaluation,
43
+ qualityVerdict,
44
+ } from './jev-quality-score.ts'
45
+ import { mapGateFailureToSkipReason } from './jev-risk-gate.ts'
30
46
  import {
31
47
  openLocalDecisionBudgetLedger,
48
+ type ReservationResult,
32
49
  resolveLocalDecisionBudgetDbPath,
33
50
  } from './local-decision-budget.ts'
34
51
  import {
@@ -36,7 +53,8 @@ import {
36
53
  buildDecisionEgressRequest,
37
54
  } from './local-decision-egress-gate.ts'
38
55
  import { verifyNativeUsageForReservation } from './local-decision-usage-evidence.internal.ts'
39
- import type { NativeDecisionRequest } from './v2-native-decisions.ts'
56
+ import { observeShadow, type ShadowSink } from './v2-decision-shadow.ts'
57
+ import type { NativeDecisionRequest, ResolvedNativeDecisionRoute } from './v2-native-decisions.ts'
40
58
  import type { V2ToolDef } from './v2-tools.ts'
41
59
 
42
60
  export interface V2JevDecisionRuntime {
@@ -56,6 +74,13 @@ export interface V2JevDecisionRuntime {
56
74
  readonly listSkills?: () => Promise<unknown>
57
75
  /** Host permission kill-switch (`ctx.permission.assert`), when present. */
58
76
  readonly permissionAssert?: (input: Record<string, unknown>) => Promise<unknown>
77
+ /**
78
+ * Shadow-record sink for the J4 output-quality review telemetry
79
+ * (`jev-quality-score.ts`); optional. The plugin wires the in-memory,
80
+ * bounded telemetry collector here; absent sink → no J4 records, nothing
81
+ * else changes.
82
+ */
83
+ readonly shadowSink?: ShadowSink
59
84
  }
60
85
 
61
86
  /** Logical permission resource: no endpoint URL exists on the native route. */
@@ -65,6 +90,8 @@ export function nativeJevPermissionResource(providerID: string, id: string): str
65
90
 
66
91
  export type JevDecisionRunFailure =
67
92
  | 'CALLER_NOT_ZEUS'
93
+ | 'REVIEW_INPUT_INVALID'
94
+ | 'CRITERIA_INVALID'
68
95
  | 'CONTEXT_UNAVAILABLE'
69
96
  | 'CONFIG_UNAVAILABLE'
70
97
  | 'DISABLED'
@@ -90,80 +117,106 @@ function refusal(reasonCode: JevDecisionRunFailure): string {
90
117
  return JSON.stringify({ advisory: false, effect: 'none', reasonCode })
91
118
  }
92
119
 
93
- /**
94
- * Refusal with the error CLASS only (`TypeError`, `RangeError`, …). The
95
- * message never crosses into the chat: it can carry paths, config or provider
96
- * detail, and the class alone already separates a detached-call failure from
97
- * a host-side data failure.
98
- */
99
- function refusalDetail(reasonCode: JevDecisionRunFailure, err: unknown): string {
100
- const detail = err instanceof Error ? err.name : 'UnknownFailure'
101
- return JSON.stringify({ advisory: false, effect: 'none', reasonCode, detail })
102
- }
103
-
104
120
  function isNonBlankString(value: unknown): value is string {
105
121
  return typeof value === 'string' && value.trim().length > 0
106
122
  }
107
123
 
124
+ /** Map a review-mode refusal to its telemetry skip token. */
125
+ function reviewRefusalSkipReason(reasonCode: JevDecisionRunFailure): string {
126
+ if (reasonCode === 'REVIEW_INPUT_INVALID') return 'skip-review-input-invalid'
127
+ if (reasonCode === 'CRITERIA_INVALID') return 'skip-criteria-invalid'
128
+ return mapGateFailureToSkipReason(reasonCode)
129
+ }
130
+
131
+ // ─── Shared gate chain ───────────────────────────────────────────────────
132
+
108
133
  /**
109
- * Read the host's installed skills for the stacking preset. Anything that is
110
- * not a plain {id, description?} record is skipped; a missing or hostile
111
- * registry degrades to the catalog-only preset. Reading the registry applies
112
- * no trust: installation already was the user's manual, reviewed act.
134
+ * Every gate-chain failure the shared runner can produce. It is
135
+ * {@link JevDecisionRunFailure} minus the tool-surface properties:
136
+ * `CALLER_NOT_ZEUS` (the caller check) and the review mode's input
137
+ * validation (`REVIEW_INPUT_INVALID` / `CRITERIA_INVALID`) — all three are
138
+ * properties of the explicit tool surface, whose input the caller supplies
139
+ * directly, not of the gate chain; the J1/J3 shadow observers run the same
140
+ * chain for any agent and can never produce them.
113
141
  */
114
- async function readHostSkills(runtime: V2JevDecisionRuntime): Promise<JevHostSkill[] | undefined> {
115
- if (typeof runtime.listSkills !== 'function') return undefined
116
- let raw: unknown
117
- try {
118
- raw = await runtime.listSkills()
119
- } catch {
120
- return undefined
121
- }
122
- if (!Array.isArray(raw)) return undefined
123
- const skills: JevHostSkill[] = []
124
- for (const entry of raw) {
125
- if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
126
- const record = entry as { id?: unknown; description?: unknown }
127
- if (typeof record.id !== 'string' || record.id.length === 0) continue
128
- skills.push({
129
- id: record.id,
130
- ...(typeof record.description === 'string' && record.description.length > 0
131
- ? { description: record.description }
132
- : {}),
133
- })
134
- }
135
- return skills
142
+ export type GatedNativeJevFailure = Exclude<
143
+ JevDecisionRunFailure,
144
+ 'CALLER_NOT_ZEUS' | 'REVIEW_INPUT_INVALID' | 'CRITERIA_INVALID'
145
+ >
146
+
147
+ /** The minimal runtime slice the gate chain needs. */
148
+ export type GatedNativeJevRuntime = Pick<V2JevDecisionRuntime, 'decide'> & {
149
+ /** Host permission kill-switch (`ctx.permission.assert`), when present. */
150
+ readonly permissionAssert?: (input: Record<string, unknown>) => Promise<unknown>
136
151
  }
137
152
 
153
+ /** One completed, settled native Jev call: gates passed, usage reconciled. */
154
+ export interface GatedNativeJevCall {
155
+ /** The route the config + ledger gates selected. */
156
+ readonly selection: NativeJevRouteSelection
157
+ /** The prepared, bounded request this call ran. */
158
+ readonly request: NativeDecisionRequest
159
+ /** The raw host response; consume it through `consumeJevDecisionResult`. */
160
+ readonly response: unknown
161
+ /** The frozen ledger reconciliation state. */
162
+ readonly frozen: boolean
163
+ }
164
+
165
+ export type GatedNativeJevCallResult =
166
+ | { readonly ok: true; readonly call: GatedNativeJevCall }
167
+ | {
168
+ readonly ok: false
169
+ readonly reasonCode: GatedNativeJevFailure
170
+ /** Sanitized error CLASS only (`TypeError`, …); set for call failures. */
171
+ readonly detail?: string
172
+ }
173
+
138
174
  /**
139
- * Run one explicit, gate-checked native Jev decision. Every failure path
140
- * returns a bounded refusal JSON; the only caller-visible success output is
141
- * the validated advice with `effect: 'none'`.
175
+ * Run ONE native Jev decision through the full gate chain — the exact chain
176
+ * `runJevDecision` has always run, extracted so a second caller (the J1
177
+ * risk-score shadow gate) reuses it instead of duplicating it:
178
+ * user-level config (`enabled`, `egress_consent`) → route via
179
+ * `resolveNativeJevRoute` with the ledger's admission check → host permission
180
+ * kill-switch on `decision.egress` → caller-supplied request preparation →
181
+ * reservation → the single host call → usage verification and reconciliation.
182
+ *
183
+ * The request preparer is injected because the two callers prepare differently
184
+ * (the tool from model input, J1 from a prebuilt bounded request); everything
185
+ * before and after it is shared. Settlement keeps the fetch runner's
186
+ * fail-closed contract: reserve before the call, reconcile from the
187
+ * host-reported cost after it, leave the reservation pending when no evidence
188
+ * can be minted.
189
+ *
190
+ * Rejects only when the budget ledger itself cannot be opened (the explicit
191
+ * tool surface propagates that as a tool error, unchanged); every gate failure
192
+ * is a structured `{ ok: false }` result, never a throw.
142
193
  */
143
- export async function runJevDecision(
144
- input: unknown,
145
- toolContext: unknown,
146
- runtime: V2JevDecisionRuntime,
147
- ): Promise<string> {
148
- const context =
149
- toolContext !== null && typeof toolContext === 'object' && !Array.isArray(toolContext)
150
- ? (toolContext as JevToolContext)
151
- : undefined
152
- if (context?.agent !== 'zeus') return refusal('CALLER_NOT_ZEUS')
153
- const sessionID = context?.sessionID
154
- const messageID = context?.messageID
155
- if (!isNonBlankString(sessionID) || !isNonBlankString(messageID)) {
156
- return refusal('CONTEXT_UNAVAILABLE')
194
+ export async function runGatedNativeJevCall(params: {
195
+ readonly sessionID: unknown
196
+ readonly messageID: unknown
197
+ /** Current agent, only when the caller actually knows it. */
198
+ readonly agent?: unknown
199
+ readonly runtime: GatedNativeJevRuntime
200
+ readonly prepare: (
201
+ route: ResolvedNativeDecisionRoute,
202
+ ) => JevDecisionPreparation | Promise<JevDecisionPreparation>
203
+ }): Promise<GatedNativeJevCallResult> {
204
+ if (!isNonBlankString(params.sessionID) || !isNonBlankString(params.messageID)) {
205
+ return { ok: false, reasonCode: 'CONTEXT_UNAVAILABLE' }
157
206
  }
207
+ const sessionID = params.sessionID
208
+ const messageID = params.messageID
209
+ const agent =
210
+ typeof params.agent === 'string' && params.agent.trim().length > 0 ? params.agent : undefined
158
211
 
159
212
  let config: ReturnType<typeof readUserDecisionRouterConfig>
160
213
  try {
161
214
  config = readUserDecisionRouterConfig()
162
215
  } catch {
163
- return refusal('CONFIG_UNAVAILABLE')
216
+ return { ok: false, reasonCode: 'CONFIG_UNAVAILABLE' }
164
217
  }
165
- if (!config.enabled) return refusal('DISABLED')
166
- if (!config.egress_consent) return refusal('CONSENT_MISSING')
218
+ if (!config.enabled) return { ok: false, reasonCode: 'DISABLED' }
219
+ if (!config.egress_consent) return { ok: false, reasonCode: 'CONSENT_MISSING' }
167
220
 
168
221
  const ledger = openLocalDecisionBudgetLedger({ dbPath: resolveLocalDecisionBudgetDbPath() })
169
222
  try {
@@ -171,11 +224,13 @@ export async function runJevDecision(
171
224
  config,
172
225
  (provider, model) => ledger.canReserve(provider, model).status === 'eligible',
173
226
  )
174
- if (!selection.ok) return refusal(selection.reasonCode)
227
+ if (!selection.ok) return { ok: false, reasonCode: selection.reasonCode }
175
228
 
176
- if (typeof runtime.permissionAssert !== 'function') return refusal('PERMISSION_UNAVAILABLE')
229
+ if (typeof params.runtime.permissionAssert !== 'function') {
230
+ return { ok: false, reasonCode: 'PERMISSION_UNAVAILABLE' }
231
+ }
177
232
  const assertion = await assertDecisionEgressPermission(
178
- runtime.permissionAssert,
233
+ params.runtime.permissionAssert,
179
234
  buildDecisionEgressRequest({
180
235
  sessionID,
181
236
  messageID,
@@ -183,36 +238,29 @@ export async function runJevDecision(
183
238
  selection.selection.route.model.providerID,
184
239
  selection.selection.route.model.id,
185
240
  ),
186
- agent: 'zeus',
241
+ ...(agent === undefined ? {} : { agent }),
187
242
  }),
188
243
  )
189
- if (assertion === 'deny') return refusal('PERMISSION_DENIED')
244
+ if (assertion === 'deny') return { ok: false, reasonCode: 'PERMISSION_DENIED' }
190
245
 
191
- const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
192
- const prepared =
193
- requested.mode === undefined
194
- ? prepareJevDecisionRequest(selection.selection.route, input ?? {})
195
- : isJevDecisionPreset(requested.mode)
196
- ? prepareJevPresetRequest(
197
- selection.selection.route,
198
- requested.mode,
199
- input ?? {},
200
- requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
201
- )
202
- : { ok: false as const, reasonCode: 'PRESET_INVALID' as const }
203
- if (!prepared.ok) return refusal(prepared.reasonCode)
246
+ const prepared = await params.prepare(selection.selection.route)
247
+ if (!prepared.ok) return { ok: false, reasonCode: prepared.reasonCode }
204
248
 
205
- const reservation = ledger.reserve(
249
+ const reservation: ReservationResult = ledger.reserve(
206
250
  selection.selection.accountingProvider,
207
251
  selection.selection.model,
208
252
  )
209
- if (reservation.status !== 'reserved') return refusal('RESERVATION_DENIED')
253
+ if (reservation.status !== 'reserved') return { ok: false, reasonCode: 'RESERVATION_DENIED' }
210
254
 
211
255
  let response: unknown
212
256
  try {
213
- response = await runtime.decide(prepared.request)
257
+ response = await params.runtime.decide(prepared.request)
214
258
  } catch (err) {
215
- return refusalDetail('DECISION_CALL_FAILED', err)
259
+ return {
260
+ ok: false,
261
+ reasonCode: 'DECISION_CALL_FAILED',
262
+ detail: err instanceof Error ? err.name : 'UnknownFailure',
263
+ }
216
264
  }
217
265
 
218
266
  const evidence = verifyNativeUsageForReservation(
@@ -224,40 +272,220 @@ export async function runJevDecision(
224
272
  },
225
273
  response,
226
274
  )
227
- if (evidence === null) return refusal('USAGE_UNRECONCILED')
275
+ if (evidence === null) return { ok: false, reasonCode: 'USAGE_UNRECONCILED' }
228
276
  const reconciliation = ledger.reconcileVerified(reservation.reservationId, evidence)
229
- if (reconciliation.status !== 'reconciled') return refusal('USAGE_UNRECONCILED')
277
+ if (reconciliation.status !== 'reconciled') {
278
+ return { ok: false, reasonCode: 'USAGE_UNRECONCILED' }
279
+ }
230
280
 
231
- const advice = consumeJevDecisionResult(response, prepared.request)
281
+ return {
282
+ ok: true,
283
+ call: {
284
+ selection: selection.selection,
285
+ request: prepared.request,
286
+ response,
287
+ frozen: reconciliation.frozen,
288
+ },
289
+ }
290
+ } finally {
291
+ ledger.close()
292
+ }
293
+ }
294
+
295
+ /**
296
+ * Read the host's installed skills for the stacking preset. Anything that is
297
+ * not a plain {id, description?} record is skipped; a missing or hostile
298
+ * registry degrades to the catalog-only preset. Reading the registry applies
299
+ * no trust: installation already was the user's manual, reviewed act.
300
+ */
301
+ async function readHostSkills(runtime: V2JevDecisionRuntime): Promise<JevHostSkill[] | undefined> {
302
+ if (typeof runtime.listSkills !== 'function') return undefined
303
+ let raw: unknown
304
+ try {
305
+ raw = await runtime.listSkills()
306
+ } catch {
307
+ return undefined
308
+ }
309
+ if (!Array.isArray(raw)) return undefined
310
+ const skills: JevHostSkill[] = []
311
+ for (const entry of raw) {
312
+ if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
313
+ const record = entry as { id?: unknown; description?: unknown }
314
+ if (typeof record.id !== 'string' || record.id.length === 0) continue
315
+ skills.push({
316
+ id: record.id,
317
+ ...(typeof record.description === 'string' && record.description.length > 0
318
+ ? { description: record.description }
319
+ : {}),
320
+ })
321
+ }
322
+ return skills
323
+ }
324
+
325
+ /**
326
+ * Run one explicit, gate-checked native Jev decision. Every failure path
327
+ * returns a bounded refusal JSON; the only caller-visible success output is
328
+ * the validated advice with `effect: 'none'`.
329
+ *
330
+ * The `mode: "review"` branch (J4 output-quality scoring, advisory only)
331
+ * validates and builds its bounded request BEFORE the gate chain — the same
332
+ * prebuilt-request pattern the J1/J3 observers use — so a malformed review
333
+ * never spends gate work, and its failure codes stay tool-surface properties.
334
+ * It records ONE J4 telemetry record per run (q-token on an answered review,
335
+ * skip tokens on every refusal path) and returns the evaluation plus the
336
+ * verdict flag; the verdict never blocks, retries, or alters anything.
337
+ */
338
+ export async function runJevDecision(
339
+ input: unknown,
340
+ toolContext: unknown,
341
+ runtime: V2JevDecisionRuntime,
342
+ ): Promise<string> {
343
+ const context =
344
+ toolContext !== null && typeof toolContext === 'object' && !Array.isArray(toolContext)
345
+ ? (toolContext as JevToolContext)
346
+ : undefined
347
+ if (context?.agent !== 'zeus') return refusal('CALLER_NOT_ZEUS')
348
+
349
+ const requested = (input ?? {}) as { mode?: unknown; questions?: unknown }
350
+ // Review mode (J4): the bounded request is built before any gate work, and
351
+ // an invalid review input is a tool-surface refusal — same class as the
352
+ // caller check, never a gate failure.
353
+ let reviewRequest: Omit<NativeDecisionRequest, 'model'> | undefined
354
+ if (requested.mode === 'review') {
355
+ const prepared = buildJevReviewRequest(input ?? {})
356
+ if (!prepared.ok) {
357
+ observeShadow(
358
+ J4_QUALITY_SCORE_POINT,
359
+ prepared.reasonCode,
360
+ () => ({
361
+ decision: 'unavailable',
362
+ reason: reviewRefusalSkipReason(prepared.reasonCode),
363
+ }),
364
+ runtime.shadowSink,
365
+ )
366
+ return refusal(prepared.reasonCode)
367
+ }
368
+ reviewRequest = prepared.request
369
+ }
370
+ const result = await runGatedNativeJevCall({
371
+ sessionID: context?.sessionID,
372
+ messageID: context?.messageID,
373
+ agent: 'zeus',
374
+ runtime,
375
+ prepare: async (route) =>
376
+ reviewRequest !== undefined
377
+ ? {
378
+ ok: true as const,
379
+ request: {
380
+ model: route.model,
381
+ input: reviewRequest.input,
382
+ questions: reviewRequest.questions,
383
+ },
384
+ }
385
+ : requested.mode === undefined
386
+ ? prepareJevDecisionRequest(route, input ?? {})
387
+ : isJevDecisionPreset(requested.mode)
388
+ ? prepareJevPresetRequest(
389
+ route,
390
+ requested.mode,
391
+ input ?? {},
392
+ requested.mode === 'skills' ? await readHostSkills(runtime) : undefined,
393
+ )
394
+ : { ok: false as const, reasonCode: 'PRESET_INVALID' as const },
395
+ })
396
+ if (!result.ok) {
397
+ if (requested.mode === 'review') {
398
+ // The review observed a gate refusal: one skip record, the refusal
399
+ // itself is unchanged.
400
+ observeShadow(
401
+ J4_QUALITY_SCORE_POINT,
402
+ result.reasonCode,
403
+ () => ({
404
+ decision: 'unavailable',
405
+ reason: reviewRefusalSkipReason(result.reasonCode),
406
+ }),
407
+ runtime.shadowSink,
408
+ )
409
+ }
410
+ if (result.detail === undefined) return refusal(result.reasonCode)
411
+ // Refusal with the error CLASS only (`TypeError`, `RangeError`, …): the
412
+ // message can carry paths, config or provider detail and never crosses
413
+ // into the chat.
414
+ return JSON.stringify({
415
+ advisory: false,
416
+ effect: 'none',
417
+ reasonCode: result.reasonCode,
418
+ detail: result.detail,
419
+ })
420
+ }
421
+
422
+ const advice = consumeJevDecisionResult(result.call.response, result.call.request)
423
+ if (requested.mode === 'review') {
424
+ // J4 advisory evaluation: strict validation, the verdict is telemetry
425
+ // plus a returned flag — it never blocks, retries, or alters the result.
426
+ const evaluation: QualityScoreEvaluation = evaluateQualityScoreDecision(
427
+ result.call.response,
428
+ result.call.request,
429
+ )
430
+ observeShadow(
431
+ J4_QUALITY_SCORE_POINT,
432
+ evaluation,
433
+ (isolated) => {
434
+ const scored = isolated as QualityScoreEvaluation
435
+ return {
436
+ decision: qualityVerdict(scored),
437
+ reason: encodeQualityScoreReason(scored),
438
+ }
439
+ },
440
+ runtime.shadowSink,
441
+ )
232
442
  return JSON.stringify({
233
443
  advisory: true,
234
444
  effect: 'none',
235
445
  reason: 'JEV_DECISION',
236
446
  route: {
237
- providerID: selection.selection.route.model.providerID,
238
- id: selection.selection.route.model.id,
239
- billing: selection.selection.route.billing,
447
+ providerID: result.call.selection.route.model.providerID,
448
+ id: result.call.selection.route.model.id,
449
+ billing: result.call.selection.route.billing,
240
450
  },
241
- ...(requested.mode === undefined ? {} : { preset: requested.mode }),
451
+ mode: 'review',
452
+ quality: evaluation.quality,
453
+ needsReview: evaluation.needsReview,
454
+ verdict: qualityVerdict(evaluation),
242
455
  answers: advice.answers,
243
456
  missing: advice.missing,
244
457
  usage: { costUsd: advice.costUsd, tokens: advice.tokens },
245
- frozen: reconciliation.frozen,
458
+ frozen: result.call.frozen,
246
459
  })
247
- } finally {
248
- ledger.close()
249
460
  }
461
+ return JSON.stringify({
462
+ advisory: true,
463
+ effect: 'none',
464
+ reason: 'JEV_DECISION',
465
+ route: {
466
+ providerID: result.call.selection.route.model.providerID,
467
+ id: result.call.selection.route.model.id,
468
+ billing: result.call.selection.route.billing,
469
+ },
470
+ ...(requested.mode === undefined ? {} : { preset: requested.mode }),
471
+ answers: advice.answers,
472
+ missing: advice.missing,
473
+ usage: { costUsd: advice.costUsd, tokens: advice.tokens },
474
+ frozen: result.call.frozen,
475
+ })
250
476
  }
251
477
 
252
478
  const TOOL_DESCRIPTION =
253
479
  'Zeus-only advisory typed decisions via the host native Jev route (OpenCode Console or a ' +
254
- 'configured decision model). Two ways to ask: pass `mode: "skills"` to stack skills for the ' +
480
+ 'configured decision model). Ways to ask: pass `mode: "skills"` to stack skills for the ' +
255
481
  'state text (local prefilter shortlist, catalog fallback, plus every skill installed in the ' +
256
482
  'host), `mode: "delegation"` to pick ' +
257
- 'a specialist, or pass explicit typed `questions` (choice, score, predicate). Returns ' +
258
- 'probabilistic answers with confidence. Requires decision-router egress consent and budget ' +
259
- 'caps; asks host permission first. It never dispatches agents, runs skills, executes tools, ' +
260
- 'or alters permissions — results are advisory only.'
483
+ 'a specialist, `mode: "review"` to score a finished delegated result against named criteria ' +
484
+ '(advisory quality score + needs-review flag; the result content itself is never sent — ' +
485
+ 'shape metrics and criteria only), or pass explicit typed `questions` (choice, score, ' +
486
+ 'predicate). Returns probabilistic answers with confidence. Requires decision-router egress ' +
487
+ 'consent and budget caps; asks host permission first. It never dispatches agents, runs ' +
488
+ 'skills, executes tools, blocks, retries, or alters permissions — results are advisory only.'
261
489
 
262
490
  const questionSchema = {
263
491
  type: 'object',
@@ -298,15 +526,51 @@ const questionSchema = {
298
526
  },
299
527
  }
300
528
 
529
+ const REVIEW_METRICS_SCHEMA = {
530
+ type: 'object',
531
+ additionalProperties: false,
532
+ required: ['outputChars', 'taskDurationMs'],
533
+ properties: {
534
+ outputChars: { type: 'integer', minimum: 0, maximum: 100_000_000 },
535
+ taskDurationMs: { type: ['integer', 'null'], minimum: 0, maximum: 100_000_000 },
536
+ },
537
+ } as const
538
+
539
+ /**
540
+ * One schema, two disjoint payloads: the state branch (presets and explicit
541
+ * questions carry the state text) and the review branch (J4 takes structural
542
+ * shape metrics, a delegate id and named criteria — never a state text, never
543
+ * result content; the criteria are the only free text, bounded at the DSH
544
+ * caps: at most 4, each 1–120 chars). The preparers are the authority; the
545
+ * schema is the model-facing contract.
546
+ */
301
547
  const JEV_INPUT_SCHEMA: Record<string, unknown> = {
302
548
  type: 'object',
303
549
  additionalProperties: false,
304
- required: ['schemaVersion', 'state'],
550
+ required: ['schemaVersion'],
551
+ anyOf: [
552
+ { required: ['state'] },
553
+ { required: ['delegateId', 'resultSummaryKind', 'resultMetrics', 'criteria'] },
554
+ ],
305
555
  properties: {
306
556
  schemaVersion: { type: 'integer', const: 1 },
307
557
  state: { type: 'string', minLength: 1, maxLength: 12_000 },
308
- mode: { type: 'string', enum: ['skills', 'delegation'] },
558
+ mode: { type: 'string', enum: ['skills', 'delegation', 'review'] },
309
559
  questions: { type: 'array', minItems: 1, maxItems: 4, items: questionSchema },
560
+ delegateId: {
561
+ type: 'string',
562
+ minLength: 1,
563
+ maxLength: 64,
564
+ pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$',
565
+ },
566
+ resultSummaryKind: { type: 'string', enum: ['ok', 'empty', 'error'] },
567
+ resultMetrics: REVIEW_METRICS_SCHEMA,
568
+ criteria: {
569
+ type: 'array',
570
+ minItems: 1,
571
+ maxItems: 4,
572
+ items: { type: 'string', minLength: 1, maxLength: 120 },
573
+ },
310
574
  },
311
575
  }
312
576