pantheon-opencode 1.6.3-beta.9 → 1.7.0-beta.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 (69) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +187 -6
  4. package/README.md +7 -1
  5. package/README.pt-BR.md +1 -1
  6. package/bin/pantheon-init.mjs +46 -28
  7. package/package.json +2 -2
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/decision-router-budget.mjs +102 -2
  11. package/scripts/decision-router-v2-budget.mjs +2 -2
  12. package/scripts/decision-router.mjs +82 -25
  13. package/scripts/doctor.mjs +4 -1
  14. package/scripts/install/cli-ui.mjs +2 -1
  15. package/scripts/install/decision-router-config.mjs +12 -4
  16. package/scripts/install/interactive.mjs +45 -28
  17. package/scripts/install/opencode.mjs +151 -30
  18. package/scripts/jev-live-probe.mjs +114 -86
  19. package/scripts/skill-search.mjs +273 -0
  20. package/skills-lock.json +3 -1
  21. package/src/agents/aphrodite.md +34 -1
  22. package/src/agents/apollo.md +227 -0
  23. package/src/agents/athena.md +26 -0
  24. package/src/agents/demeter.md +33 -0
  25. package/src/agents/gaia.md +24 -0
  26. package/src/agents/hephaestus.md +24 -0
  27. package/src/agents/hermes.md +33 -0
  28. package/src/agents/iris.md +24 -0
  29. package/src/agents/mnemosyne.md +25 -3
  30. package/src/agents/nyx.md +50 -22
  31. package/src/agents/prometheus.md +242 -1
  32. package/src/agents/talos.md +24 -0
  33. package/src/agents/themis.md +24 -0
  34. package/src/agents/zeus.md +71 -20
  35. package/src/pantheon/j1-approvals.ts +123 -0
  36. package/src/pantheon/jev-decision-tool.ts +148 -17
  37. package/src/pantheon/jev-decisions.ts +95 -12
  38. package/src/pantheon/jev-escalation.ts +1 -1
  39. package/src/pantheon/jev-quality-score.ts +45 -10
  40. package/src/pantheon/jev-rank-verify.ts +244 -14
  41. package/src/pantheon/jev-risk-gate.ts +82 -12
  42. package/src/pantheon/local-decision-budget.ts +169 -2
  43. package/src/pantheon/local-decision-prompt.ts +2 -0
  44. package/src/pantheon/local-decision-router.ts +16 -0
  45. package/src/pantheon/local-decision-turn.ts +110 -4
  46. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  47. package/src/pantheon/pantheon-decision-catalog.ts +9 -2
  48. package/src/pantheon/v2-decision-budget.ts +4 -2
  49. package/src/pantheon/v2-tools.ts +42 -0
  50. package/src/plugin-v2.ts +85 -5
  51. package/src/plugins/tui/dist/server-v2.d.ts +14 -6
  52. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  53. package/src/plugins/tui/dist/server-v2.js +16 -9
  54. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  55. package/src/plugins/tui/dist/tui-v2.js +128 -25
  56. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  57. package/src/plugins/tui/dist/tui.js +1 -1
  58. package/src/plugins/tui/package-lock.json +2 -2
  59. package/src/plugins/tui/package.json +1 -1
  60. package/src/plugins/tui/src/server-v2.ts +14 -7
  61. package/src/plugins/tui/src/whats-new-highlights.ts +59 -5
  62. package/src/plugins/tui/src/whats-new-open.ts +41 -1
  63. package/src/plugins/tui/src/whats-new.tsx +61 -8
  64. package/src/routing.yml +2 -0
  65. package/src/skills/README.md +1 -1
  66. package/src/skills/agent-forge/SKILL.md +76 -0
  67. package/src/skills/auto-continue/SKILL.md +12 -163
  68. package/src/skills/auto-continue/references/auto-continue-details.md +175 -0
  69. package/src/skills/prompt-refinery/SKILL.md +60 -0
@@ -22,7 +22,8 @@
22
22
  * Zeus can check 1–4 named claims in ONE typed round-trip: one `predicate`
23
23
  * question per claim (within the 4-question bound), the claim text riding that
24
24
  * question's instructions. The consumer maps each answer: probability
25
- * ≥ {@link VERIFY_PASS_THRESHOLD} → `PASS`, below → `FAIL`, and every refusal,
25
+ * > {@link VERIFY_PASS_THRESHOLD} (0.65) → `PASS`; 0.35–0.65 → `UNVERIFIABLE`; below →
26
+ * `FAIL`; and every refusal,
26
27
  * timeout, duplicate or malformed answer → `BLOCK` (fail-closed: an
27
28
  * unanswered mandatory claim must never read as verified). The tool itself
28
29
  * never acts on a verdict — `effect` stays `none` — and a gate-chain refusal
@@ -46,7 +47,7 @@
46
47
  * @module jev-rank-verify
47
48
  */
48
49
 
49
- import { consumeJevDecisionResult } from './jev-decisions.ts'
50
+ import { consumeJevDecisionResult, JEV_DECISION_MAX_QUESTIONS } from './jev-decisions.ts'
50
51
  import type { NativeDecisionRequest, ResolvedNativeDecisionRoute } from './v2-native-decisions.ts'
51
52
  import { NATIVE_DECISION_MAX_PROMPT_LENGTH } from './v2-native-decisions.ts'
52
53
 
@@ -54,8 +55,8 @@ import { NATIVE_DECISION_MAX_PROMPT_LENGTH } from './v2-native-decisions.ts'
54
55
 
55
56
  /** A ranking needs at least two candidates to choose between. */
56
57
  export const RANK_MIN_CANDIDATES = 2
57
- /** Above eight, ranking degrades to explicit questions with a real rubric. */
58
- export const RANK_MAX_CANDIDATES = 8
58
+ /** Mirrors the typesafe_rank reference contract (1-20 accepted upstream). */
59
+ export const RANK_MAX_CANDIDATES = 20
59
60
 
60
61
  /** Question name of the rank's choice question. */
61
62
  export const RANK_WINNER_QUESTION_NAME = 'winner'
@@ -73,7 +74,13 @@ export const VERIFY_MAX_CLAIMS = 4
73
74
  export const CLAIM_MAX_LENGTH = 200
74
75
 
75
76
  /** Predicate probability at or above which a claim counts as PASS. */
76
- export const VERIFY_PASS_THRESHOLD = 0.5
77
+ /**
78
+ * PASS lives strictly ABOVE the UNVERIFIABLE band (QA beta.20: with PASS at
79
+ * 0.5 the documented 0.35-0.65 band was unreachable at its top half — 0.50
80
+ * and 0.65 returned PASS). Verdicts: < 0.35 FAIL, 0.35-0.65 UNVERIFIABLE,
81
+ * > 0.65 PASS.
82
+ */
83
+ export const VERIFY_PASS_THRESHOLD = 0.65
77
84
 
78
85
  const CANDIDATE_ID_MAX_LENGTH = 64
79
86
  const CLAIM_NAME_MAX_LENGTH = 64
@@ -164,7 +171,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
164
171
 
165
172
  // ─── Rank: request building ──────────────────────────────────────────────
166
173
 
167
- const RANK_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
174
+ export const RANK_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
168
175
  'schemaVersion',
169
176
  'mode',
170
177
  'state',
@@ -173,13 +180,24 @@ const RANK_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
173
180
 
174
181
  export type JevRankBuildFailure = 'RANK_INPUT_INVALID' | 'CANDIDATE_INVALID' | 'STATE_INVALID'
175
182
 
183
+ /** Per-cause token attached to a rank build refusal (e.g. the accepted count range). */
184
+ export type JevRankBuildDetail = 'RANK_CANDIDATE_COUNT_RANGE'
185
+
176
186
  export type JevRankBuild =
177
187
  | { readonly ok: true; readonly request: Omit<NativeDecisionRequest, 'model'> }
178
- | { readonly ok: false; readonly reasonCode: JevRankBuildFailure }
188
+ | {
189
+ readonly ok: false
190
+ readonly reasonCode: JevRankBuildFailure
191
+ readonly detail?: JevRankBuildDetail
192
+ }
179
193
 
180
194
  export type JevRankPreparation =
181
195
  | { readonly ok: true; readonly request: NativeDecisionRequest }
182
- | { readonly ok: false; readonly reasonCode: JevRankBuildFailure }
196
+ | {
197
+ readonly ok: false
198
+ readonly reasonCode: JevRankBuildFailure
199
+ readonly detail?: JevRankBuildDetail
200
+ }
183
201
 
184
202
  /**
185
203
  * Validate the rank tool input and build the model-less request. The state is
@@ -205,7 +223,7 @@ export function buildJevRankRequest(input: unknown): JevRankBuild {
205
223
  if (rawCandidates === undefined) return { ok: false, reasonCode: 'RANK_INPUT_INVALID' }
206
224
  if (!Array.isArray(rawCandidates)) return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
207
225
  if (rawCandidates.length < RANK_MIN_CANDIDATES || rawCandidates.length > RANK_MAX_CANDIDATES) {
208
- return { ok: false, reasonCode: 'CANDIDATE_INVALID' }
226
+ return { ok: false, reasonCode: 'CANDIDATE_INVALID', detail: 'RANK_CANDIDATE_COUNT_RANGE' }
209
227
  }
210
228
  const seen = new Set<string>()
211
229
  const choices: Array<{ value: string; description?: string }> = []
@@ -272,9 +290,202 @@ export function prepareJevRankRequest(
272
290
  }
273
291
  }
274
292
 
293
+ // ─── Order: top-K ordering (2-4 candidates, one fit question each) ───────
294
+
295
+ export const ORDER_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
296
+ 'schemaVersion',
297
+ 'mode',
298
+ 'state',
299
+ 'candidates',
300
+ ])
301
+
302
+ export type JevOrderBuildFailure =
303
+ | 'ORDER_INPUT_INVALID'
304
+ | 'ORDER_CANDIDATE_INVALID'
305
+ | 'STATE_INVALID'
306
+
307
+ export type JevOrderBuildDetail = 'ORDER_CANDIDATE_COUNT_RANGE'
308
+
309
+ export type JevOrderBuild =
310
+ | {
311
+ readonly ok: true
312
+ readonly request: Omit<NativeDecisionRequest, 'model'>
313
+ /** The caller's candidate ids in question order (QA beta.20: the consumer must map scores back to THESE, not positional c1..cN). */
314
+ readonly candidates: readonly string[]
315
+ }
316
+ | {
317
+ readonly ok: false
318
+ readonly reasonCode: JevOrderBuildFailure
319
+ readonly detail?: JevOrderBuildDetail
320
+ }
321
+
322
+ export type JevOrderPreparation =
323
+ | {
324
+ readonly ok: true
325
+ readonly request: NativeDecisionRequest
326
+ readonly candidates: readonly string[]
327
+ }
328
+ | {
329
+ readonly ok: false
330
+ readonly reasonCode: JevOrderBuildFailure
331
+ readonly detail?: JevOrderBuildDetail
332
+ }
333
+
334
+ const ORDER_MAX_CANDIDATES = JEV_DECISION_MAX_QUESTIONS // one score question per candidate
335
+
336
+ const ORDER_STATE_TEMPLATE =
337
+ 'Advisory ordering. The caller supplied a task and 2-4 candidates; ' +
338
+ 'each question scores ONE candidate for fit against the stated task. ' +
339
+ 'Score each candidate on its own terms. Nothing is enforced. ' +
340
+ 'The score is an ORDINAL on the 2..10 rubric (10 = exact fit), never a probability.'
341
+
342
+ /**
343
+ * Build the order request: one SCORE question per candidate (the host answers
344
+ * one scalar per question, so 2-4 candidates is the honest ceiling). Ids ride
345
+ * the candidate validation reused from rank; question names are positional
346
+ * (`fit_1`..) so no id pattern can collide with the question-name grammar.
347
+ */
348
+ export function buildJevOrderRequest(input: unknown): JevOrderBuild {
349
+ if (!isRecord(input)) return { ok: false, reasonCode: 'ORDER_INPUT_INVALID' }
350
+ for (const key of Object.keys(input)) {
351
+ if (!ORDER_ENVELOPE_KEYS.has(key)) return { ok: false, reasonCode: 'ORDER_INPUT_INVALID' }
352
+ }
353
+ const state = input.state
354
+ if (!isBoundedNonBlankString(state, NATIVE_DECISION_MAX_PROMPT_LENGTH) || isHostileProse(state)) {
355
+ return { ok: false, reasonCode: 'STATE_INVALID' }
356
+ }
357
+ const rawCandidates = input.candidates
358
+ if (rawCandidates === undefined) return { ok: false, reasonCode: 'ORDER_INPUT_INVALID' }
359
+ if (!Array.isArray(rawCandidates)) return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
360
+ if (rawCandidates.length < 2 || rawCandidates.length > ORDER_MAX_CANDIDATES) {
361
+ return {
362
+ ok: false,
363
+ reasonCode: 'ORDER_CANDIDATE_INVALID',
364
+ detail: 'ORDER_CANDIDATE_COUNT_RANGE',
365
+ }
366
+ }
367
+ const seen = new Set<string>()
368
+ const candidates: Array<{ id: string; description?: string }> = []
369
+ for (const raw of rawCandidates) {
370
+ if (!isRecord(raw)) return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
371
+ const extraKeys = Object.keys(raw).filter((key) => key !== 'id' && key !== 'description')
372
+ if (extraKeys.length > 0) return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
373
+ const id = raw.id
374
+ if (typeof id !== 'string' || id.length < 1 || id.length > 64) {
375
+ return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
376
+ }
377
+ if (seen.has(id)) return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
378
+ seen.add(id)
379
+ const description = raw.description
380
+ if (description !== undefined) {
381
+ if (!isBoundedNonBlankString(description, 500) || isHostileProse(description)) {
382
+ return { ok: false, reasonCode: 'ORDER_CANDIDATE_INVALID' }
383
+ }
384
+ candidates.push({ id, description })
385
+ } else {
386
+ candidates.push({ id })
387
+ }
388
+ }
389
+ const levels = Array.from({ length: 9 }, (_, index) => ({
390
+ label: String(index + 2),
391
+ }))
392
+ // Position-bias regression (external ref: Zheng et al. 2023): the builder
393
+ // PRESERVES the caller's candidate order — any reordering is the model's
394
+ // verdict, never ours. The consumer maps scores back to caller ids.
395
+ const questions = candidates.map((candidate, index) => ({
396
+ type: 'score' as const,
397
+ name: `fit_${index + 1}`,
398
+ instructions:
399
+ `Score how well candidate "${candidate.id}"` +
400
+ (candidate.description ? ` (${candidate.description})` : '') +
401
+ ` fits the task. 2 = poor fit, 10 = exact fit.`,
402
+ levels,
403
+ }))
404
+ const request = {
405
+ input: Object.freeze([
406
+ Object.freeze({ type: 'text' as const, text: `${ORDER_STATE_TEMPLATE} Task: ${state}` }),
407
+ ]),
408
+ questions: Object.freeze(questions.map((question) => Object.freeze(question))),
409
+ } satisfies Omit<NativeDecisionRequest, 'model'>
410
+ return {
411
+ ok: true,
412
+ request: Object.freeze(request),
413
+ candidates: Object.freeze(candidates.map((c) => c.id)),
414
+ }
415
+ }
416
+
417
+ export function prepareJevOrderRequest(
418
+ route: ResolvedNativeDecisionRoute,
419
+ input: unknown,
420
+ ): JevOrderPreparation {
421
+ const built = buildJevOrderRequest(input)
422
+ if (!built.ok) return built
423
+ return {
424
+ ok: true,
425
+ request: {
426
+ model: route.model,
427
+ input: built.request.input,
428
+ questions: built.request.questions,
429
+ },
430
+ candidates: built.candidates,
431
+ }
432
+ }
433
+
434
+ /** One ordered entry: the candidate id and its fit score (null when the host answered nothing usable). */
435
+ export interface JevOrderEntry {
436
+ readonly id: string
437
+ readonly score: number | null
438
+ }
439
+
440
+ /**
441
+ * Consume the order result: map each positional score answer back to its
442
+ * candidate, sort by score descending (nulls last, stable), and return the
443
+ * ordering. A missing/invalid score stays visible as null — never guessed.
444
+ */
445
+ export function consumeJevOrderResult(
446
+ response: unknown,
447
+ request: NativeDecisionRequest,
448
+ candidates: readonly string[],
449
+ ): ReadonlyArray<JevOrderEntry> {
450
+ const advice = consumeJevDecisionResult(response, request)
451
+ const entries: Array<{ id: string; score: number | null; order: number }> = []
452
+ request.questions.forEach((question, index) => {
453
+ const answer = advice.answers.find((candidate) => candidate.name === question.name)
454
+ const score =
455
+ answer !== undefined && answer.type === 'score' && typeof answer.score === 'number'
456
+ ? answer.score
457
+ : null
458
+ // QA beta.20: map back to the CALLER's candidate id — positional c1..cN
459
+ // told the user nothing.
460
+ entries.push({ id: candidates[index] ?? `c${index + 1}`, score, order: index })
461
+ })
462
+ return Object.freeze(
463
+ entries
464
+ .sort((left, right) => {
465
+ if (left.score === null && right.score === null) return left.order - right.order
466
+ if (left.score === null) return 1
467
+ if (right.score === null) return -1
468
+ return right.score - left.score || left.order - right.order
469
+ })
470
+ .map(({ id, score }) => ({ id, score })),
471
+ )
472
+ }
473
+
275
474
  // ─── Verify: request building ────────────────────────────────────────────
276
475
 
277
- const VERIFY_ENVELOPE_KEYS: ReadonlySet<string> = new Set(['schemaVersion', 'mode', 'claims'])
476
+ export const VERIFY_ENVELOPE_KEYS: ReadonlySet<string> = new Set([
477
+ 'schemaVersion',
478
+ 'mode',
479
+ 'claims',
480
+ // Optional evidence: the environment/context the claims are judged against
481
+ // (field report beta.13 §6 — without it, environment-dependent claims are
482
+ // unanswerable and the honest verdict is UNVERIFIABLE, not FAIL).
483
+ 'state',
484
+ ])
485
+
486
+ /** The verdict band treated as "the model could not tell" (neither PASS nor FAIL). */
487
+ export const VERIFY_UNVERIFIABLE_LOW = 0.35
488
+ export const VERIFY_UNVERIFIABLE_HIGH = 0.65
278
489
 
279
490
  export type JevVerifyBuildFailure = 'VERIFY_INPUT_INVALID' | 'CLAIM_INVALID'
280
491
 
@@ -339,8 +550,21 @@ export function buildJevVerifyRequest(input: unknown): JevVerifyBuild {
339
550
  seen.add(name)
340
551
  questions.push({ type: 'predicate', name, instructions: verifyInstructions(claim) })
341
552
  }
553
+ // Optional evidence: the caller's state rides as the input text the claims
554
+ // are judged against; without it the template keeps claims self-contained.
555
+ const rawState = (input as Record<string, unknown>).state
556
+ let evidence = VERIFY_STATE_TEMPLATE
557
+ if (rawState !== undefined) {
558
+ if (
559
+ !isBoundedNonBlankString(rawState, NATIVE_DECISION_MAX_PROMPT_LENGTH) ||
560
+ isHostileProse(rawState)
561
+ ) {
562
+ return { ok: false, reasonCode: 'VERIFY_INPUT_INVALID' }
563
+ }
564
+ evidence = `${VERIFY_STATE_TEMPLATE} Evidence/context supplied by the caller, to be trusted as given: ${rawState}`
565
+ }
342
566
  const request = {
343
- input: Object.freeze([Object.freeze({ type: 'text' as const, text: VERIFY_STATE_TEMPLATE })]),
567
+ input: Object.freeze([Object.freeze({ type: 'text' as const, text: evidence })]),
344
568
  questions: Object.freeze(questions.map((question) => Object.freeze(question))),
345
569
  } satisfies Omit<NativeDecisionRequest, 'model'>
346
570
  return { ok: true, request: Object.freeze(request) }
@@ -409,11 +633,11 @@ export function consumeJevRankResult(
409
633
  * verified (or as refuted — an unverifiable claim is unverifiable, not
410
634
  * false).
411
635
  */
412
- export type VerifyClaimVerdict = 'PASS' | 'FAIL' | 'BLOCK'
636
+ export type VerifyClaimVerdict = 'PASS' | 'FAIL' | 'UNVERIFIABLE' | 'BLOCK'
413
637
 
414
638
  /**
415
639
  * Consume a host Decisions response against the prepared verify request:
416
- * one verdict per claim name. Probability ≥ {@link VERIFY_PASS_THRESHOLD} is
640
+ * one verdict per claim name. Probability > {@link VERIFY_PASS_THRESHOLD} is
417
641
  * `PASS`, below is `FAIL`; error answers, missing answers and any unusable
418
642
  * response shape are `BLOCK` — fail-closed.
419
643
  */
@@ -426,7 +650,13 @@ export function consumeJevVerifyResult(
426
650
  for (const question of request.questions) {
427
651
  const answer = advice.answers.find((candidate) => candidate.name === question.name)
428
652
  if (answer !== undefined && answer.type === 'predicate') {
429
- verdicts[question.name] = (answer.probability ?? 0) >= VERIFY_PASS_THRESHOLD ? 'PASS' : 'FAIL'
653
+ const probability = answer.probability ?? 0
654
+ verdicts[question.name] =
655
+ probability > VERIFY_PASS_THRESHOLD
656
+ ? 'PASS'
657
+ : probability >= VERIFY_UNVERIFIABLE_LOW
658
+ ? 'UNVERIFIABLE'
659
+ : 'FAIL'
430
660
  } else {
431
661
  verdicts[question.name] = 'BLOCK'
432
662
  }
@@ -89,7 +89,7 @@ export const J1_RISK_GATE_STATE_MAX_LENGTH = 512
89
89
  /** Predicate probability at or above which the intent counts as consistent. */
90
90
  export const RISK_GATE_INTENT_THRESHOLD = 0.5
91
91
 
92
- const FLAG_ON = new Set(['1', 'on', 'true'])
92
+ const FLAG_ON = new Set(['1', 'on', 'true', 'shadow'])
93
93
  const TOOL_NAME_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/
94
94
  const SHA256_HEX = /^[0-9a-f]{64}$/
95
95
  const SCOPES: ReadonlySet<string> = new Set(['write', 'execute', 'read'])
@@ -120,12 +120,50 @@ const WRITE_TOOLS: ReadonlySet<string> = new Set([
120
120
  'hashline_edit',
121
121
  ])
122
122
 
123
- /** Whether the operator explicitly enabled the flag. Absence means off. */
123
+ /**
124
+ * The escalation ladder (field beta.14: the operator wants iterative
125
+ * escalation, not a binary flag). `on`/`1`/`true` map to `shadow` for
126
+ * back-compatibility with the shipped setup.
127
+ * off — nothing fires (hard zero)
128
+ * shadow — observe + record; invisible in the session (today's behavior)
129
+ * warn — RESERVED (needs a V2 client channel; currently behaves as shadow)
130
+ * enforce — an affirmative high-risk score DENIES the tool call (the host
131
+ * surfaces the block message in the session); gate unavailability
132
+ * never blocks (fail-open, documented)
133
+ */
134
+ export type J1RiskGateMode = 'off' | 'shadow' | 'warn' | 'enforce'
135
+
136
+ export const J1_ENFORCE_THRESHOLD_ENV = 'PANTHEON_J1_ENFORCE_THRESHOLD'
137
+ export const J1_ENFORCE_THRESHOLD_DEFAULT = 0.8
138
+
139
+ export function j1ModeFromEnv(
140
+ env: Record<string, string | undefined> = process.env,
141
+ ): J1RiskGateMode {
142
+ const raw = (env[J1_RISK_GATE_FLAG_ENV] ?? '').trim().toLowerCase()
143
+ if (raw === 'enforce') return 'enforce'
144
+ if (raw === 'warn') return 'warn'
145
+ return FLAG_ON.has(raw) ? 'shadow' : 'off'
146
+ }
147
+
148
+ /** Back-compatible: any non-off mode counts as enabled. */
124
149
  export function j1RiskGateEnabledFromEnv(
125
150
  env: Record<string, string | undefined> = process.env,
126
151
  ): boolean {
127
- const raw = (env[J1_RISK_GATE_FLAG_ENV] ?? '').trim().toLowerCase()
128
- return FLAG_ON.has(raw)
152
+ return j1ModeFromEnv(env) !== 'off'
153
+ }
154
+
155
+ /**
156
+ * The enforce-mode deny threshold (0..1). Invalid or out-of-range values fall
157
+ * back to the documented default — an operator typo must not disable the gate.
158
+ */
159
+ export function j1EnforceThresholdFromEnv(
160
+ env: Record<string, string | undefined> = process.env,
161
+ ): number {
162
+ const text = (env[J1_ENFORCE_THRESHOLD_ENV] ?? '').trim()
163
+ if (text === '') return J1_ENFORCE_THRESHOLD_DEFAULT
164
+ const raw = Number(text)
165
+ if (!Number.isFinite(raw) || raw < 0 || raw > 1) return J1_ENFORCE_THRESHOLD_DEFAULT
166
+ return raw
129
167
  }
130
168
 
131
169
  /**
@@ -154,7 +192,10 @@ export function isRiskGateTarget(tool: unknown): tool is string {
154
192
 
155
193
  /**
156
194
  * sha256 hex of the serialized tool input — an opaque correlation value, the
157
- * only content-derived field that ever leaves this process. Unserializable
195
+ * only content-derived field that ever leaves this process. The hash is a
196
+ * DETERMINISTIC pseudonymization (unsalted SHA-256 — same input, same hash by
197
+ * design, so approvals can be pinned to the exact call), NOT anonymization:
198
+ * someone holding the dictionary can reconstruct the input. Unserializable
158
199
  * inputs hash a stable marker; this never throws.
159
200
  */
160
201
  export function hashToolInput(input: unknown): string {
@@ -349,7 +390,10 @@ const SKIP_REASON_BY_GATE_FAILURE: Readonly<Record<GatedNativeJevFailure, string
349
390
  PRESET_INVALID: 'skip-request-invalid',
350
391
  RESERVATION_DENIED: 'skip-reservation-denied',
351
392
  DECISION_CALL_FAILED: 'skip-decision-call-failed',
393
+ USAGE_EVIDENCE_UNAVAILABLE: 'skip-usage-evidence-unavailable',
352
394
  USAGE_UNRECONCILED: 'skip-usage-unreconciled',
395
+ ORDER_INPUT_INVALID: 'skip-request-invalid',
396
+ ORDER_CANDIDATE_INVALID: 'skip-request-invalid',
353
397
  })
354
398
 
355
399
  /** Map a gate failure to its telemetry reason token; unknown → fail-open. */
@@ -407,15 +451,28 @@ function abortDeadline(signal: AbortSignal): Promise<'timeout'> {
407
451
  * settles its own ledger reservation in the background (settlement of an
408
452
  * already-fired call — not a retry, and it writes no record).
409
453
  */
454
+ export interface J1Verdict {
455
+ /** 'block' only in enforce mode with an affirmative high-risk score. */
456
+ block: boolean
457
+ riskScore: number | null
458
+ reason: string
459
+ }
460
+
410
461
  export function createJ1RiskGateObserver(
411
- options: J1RiskGateObserverOptions,
412
- ): (event: unknown) => Promise<void> {
462
+ options: J1RiskGateObserverOptions & {
463
+ /** enforce: the caller awaits and denies on { block: true }. */
464
+ mode?: J1RiskGateMode
465
+ threshold?: number
466
+ },
467
+ ): (event: unknown) => Promise<J1Verdict | undefined> {
413
468
  const timeoutMs = options.timeoutMs ?? J1_RISK_GATE_TIMEOUT_MS
414
469
  const sink = options.sink
415
- return async (event: unknown): Promise<void> => {
470
+ const enforce = options.mode === 'enforce'
471
+ const threshold = options.threshold ?? J1_ENFORCE_THRESHOLD_DEFAULT
472
+ return async (event: unknown): Promise<J1Verdict | undefined> => {
416
473
  try {
417
474
  const payload = (event ?? {}) as J1ExecuteBeforeEvent
418
- if (!isRiskGateTarget(payload.tool)) return
475
+ if (!isRiskGateTarget(payload.tool)) return undefined
419
476
  const tool = payload.tool
420
477
  const scope = classifyRiskGateScope(tool)
421
478
  const built = buildRiskGateRequest({
@@ -425,7 +482,7 @@ export function createJ1RiskGateObserver(
425
482
  })
426
483
  if (!built.ok) {
427
484
  recordSkip(sink, 'skip-input-invalid')
428
- return
485
+ return undefined
429
486
  }
430
487
  const controller = new AbortController()
431
488
  const timer = setTimeout(() => controller.abort(), timeoutMs)
@@ -450,11 +507,11 @@ export function createJ1RiskGateObserver(
450
507
  ])
451
508
  if (outcome === 'timeout') {
452
509
  recordSkip(sink, 'skip-timeout')
453
- return
510
+ return undefined
454
511
  }
455
512
  if (!outcome.ok) {
456
513
  recordSkip(sink, mapGateFailureToSkipReason(outcome.reasonCode))
457
- return
514
+ return undefined
458
515
  }
459
516
  const evaluation = evaluateRiskGateDecision(outcome.call.response, outcome.call.request)
460
517
  observeShadow(
@@ -466,6 +523,18 @@ export function createJ1RiskGateObserver(
466
523
  }),
467
524
  sink,
468
525
  )
526
+ if (enforce) {
527
+ const risk = evaluation.riskScore
528
+ const block = risk !== null && risk >= threshold
529
+ return {
530
+ block,
531
+ riskScore: risk,
532
+ reason: block
533
+ ? `J1 enforce: risco ${risk.toFixed(2)} >= threshold ${threshold}`
534
+ : 'allow',
535
+ }
536
+ }
537
+ return
469
538
  } finally {
470
539
  clearTimeout(timer)
471
540
  }
@@ -474,6 +543,7 @@ export function createJ1RiskGateObserver(
474
543
  // be opened; any other unexpected failure lands here too. One skip
475
544
  // record, no detail, no propagation into the tool call.
476
545
  recordSkip(sink, 'skip-gate-unavailable')
546
+ return undefined
477
547
  }
478
548
  }
479
549
  }