pantheon-opencode 1.6.2-beta.4 → 1.6.2-beta.5

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 (54) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +174 -3
  3. package/bin/pantheon-init.mjs +6 -1
  4. package/package.json +1 -1
  5. package/plugin.json +1 -1
  6. package/pyproject.toml +1 -1
  7. package/scripts/decision-router-budget.mjs +3 -3
  8. package/scripts/decision-router-v2-budget.mjs +218 -0
  9. package/scripts/decision-router-v2-egress.mjs +272 -0
  10. package/scripts/decision-router.mjs +268 -46
  11. package/scripts/docs-check-changelog.mjs +5 -3
  12. package/scripts/install/decision-layer-preview.mjs +376 -0
  13. package/scripts/install/decision-router-config.mjs +158 -11
  14. package/scripts/mcp_resources.py +11 -9
  15. package/scripts/release-notes.mjs +30 -7
  16. package/scripts/versioning.mjs +41 -5
  17. package/src/mcp/eval_store.py +11 -4
  18. package/src/mcp/mcp_resources.py +11 -9
  19. package/src/mcp/memory_mcp.py +293 -150
  20. package/src/pantheon/local-decision-prompt.ts +181 -36
  21. package/src/pantheon/local-decision-skills.ts +115 -5
  22. package/src/pantheon/local-decision-tool.ts +35 -1
  23. package/src/pantheon/v2-decision-budget.ts +456 -0
  24. package/src/pantheon/v2-decision-contracts.ts +300 -0
  25. package/src/pantheon/v2-decision-egress.ts +203 -0
  26. package/src/pantheon/v2-decision-events.ts +180 -0
  27. package/src/pantheon/v2-decision-heuristic.ts +121 -0
  28. package/src/pantheon/v2-decision-points/p1-agent.ts +91 -0
  29. package/src/pantheon/v2-decision-points/p10-claims.ts +243 -0
  30. package/src/pantheon/v2-decision-points/p11-catalog.ts +220 -0
  31. package/src/pantheon/v2-decision-points/p2-skill.ts +83 -0
  32. package/src/pantheon/v2-decision-points/p3-complexity.ts +108 -0
  33. package/src/pantheon/v2-decision-points/p4-memory.ts +137 -0
  34. package/src/pantheon/v2-decision-points/p5-themis-verify.ts +190 -0
  35. package/src/pantheon/v2-decision-points/p6-council.ts +161 -0
  36. package/src/pantheon/v2-decision-points/p7-loop.ts +263 -0
  37. package/src/pantheon/v2-decision-points/p8-guardrail.ts +366 -0
  38. package/src/pantheon/v2-decision-points/p9-memory-compaction.ts +304 -0
  39. package/src/pantheon/v2-decision-points.ts +242 -0
  40. package/src/pantheon/v2-decision-policy.ts +166 -0
  41. package/src/pantheon/v2-decision-premises.ts +146 -0
  42. package/src/pantheon/v2-decision-prompt-surface.ts +115 -0
  43. package/src/pantheon/v2-decision-rank.ts +91 -0
  44. package/src/pantheon/v2-decision-registry.ts +391 -0
  45. package/src/pantheon/v2-decision-resource-ids.ts +127 -0
  46. package/src/pantheon/v2-decision-shadow.ts +123 -0
  47. package/src/pantheon/v2-decision-telemetry.ts +214 -0
  48. package/src/pantheon/v2-decision-verify.ts +51 -0
  49. package/src/pantheon/v2-tools.ts +21 -2
  50. package/src/plugin-v2.ts +305 -3
  51. package/src/plugins/tui/dist/tui-v2.js +3 -3
  52. package/src/plugins/tui/dist/tui.js +1 -1
  53. package/src/plugins/tui/package-lock.json +2 -2
  54. package/src/plugins/tui/package.json +1 -1
@@ -4,9 +4,61 @@ import { isPantheonAgentId, isPantheonSkillId } from './pantheon-decision-catalo
4
4
  const MARKER_PREFIX = '<!-- pantheon-decision-router:v1'
5
5
  const MARKER_PATTERN = /<!-- pantheon-decision-router:v1\b[^>]*-->/
6
6
 
7
+ /** The host sends the *string* `"undefined"` for absent prompt fields (F-08). */
8
+ const MEASURED_SENTINELS: ReadonlySet<string> = new Set(['undefined', 'null'])
9
+
10
+ /** Where the observed skill list came from: the prompt array, the draft, or nowhere. */
11
+ export type SkillsSource = 'none' | 'prompt' | 'draft'
12
+
13
+ /**
14
+ * Why the skill outcome is what it is. Tokens only — no content, no count of
15
+ * user text. Every result carries one, so an empty selection is never silent.
16
+ */
17
+ export type PromptApplicationReason =
18
+ | 'invalid.payload'
19
+ | 'request.empty'
20
+ | 'marker.present'
21
+ | 'decision.inactive'
22
+ | 'selection.empty'
23
+ | 'skills.source.prompt'
24
+ | 'skills.source.draft'
25
+ | 'skills.source.absent'
26
+ | 'skills.source.empty'
27
+ | 'skills.source.unstable'
28
+ | 'skills.selection.disjoint'
29
+ | 'skills.synthetic.narrowed'
30
+
7
31
  export interface PromptApplicationResult {
8
32
  markerApplied: boolean
9
33
  skillsFiltered: boolean
34
+ /** Observable source of the skill list; `none` in the measured host shape (F-08). */
35
+ skillsSource: SkillsSource
36
+ /** Always present: explains the skill outcome, including every empty selection. */
37
+ reason: PromptApplicationReason
38
+ }
39
+
40
+ export interface SkillSourceResolution {
41
+ readonly skillsSource: SkillsSource
42
+ /** Stable identifiers found in the chosen source, deduplicated, in order. */
43
+ readonly skillIds: readonly string[]
44
+ readonly reason: PromptApplicationReason
45
+ }
46
+
47
+ interface SkillNarrowing {
48
+ readonly skillsFiltered: boolean
49
+ readonly skillsSource: SkillsSource
50
+ readonly reason: PromptApplicationReason
51
+ }
52
+
53
+ /** True when the value is the measured placeholder string, not real data. */
54
+ function isMeasuredSentinel(value: unknown): boolean {
55
+ return typeof value === 'string' && MEASURED_SENTINELS.has(value)
56
+ }
57
+
58
+ /** Normalize a measured prompt field: a sentinel string or null means "absent". */
59
+ export function normalizeMeasuredValue(value: unknown): unknown {
60
+ if (value === null || value === undefined) return undefined
61
+ return isMeasuredSentinel(value) ? undefined : value
10
62
  }
11
63
 
12
64
  function skillIdentifier(value: unknown): string | undefined {
@@ -19,28 +71,103 @@ function skillIdentifier(value: unknown): string | undefined {
19
71
  return undefined
20
72
  }
21
73
 
74
+ function identifiers(list: readonly unknown[]): { ids: string[]; unstable: boolean } {
75
+ const ids: string[] = []
76
+ let unstable = false
77
+ for (const item of list) {
78
+ const identifier = skillIdentifier(item)
79
+ if (identifier === undefined) unstable = true
80
+ else if (!ids.includes(identifier)) ids.push(identifier)
81
+ }
82
+ return { ids, unstable }
83
+ }
84
+
22
85
  /**
23
- * Best-effort rewrite of the host's pre-resolution skill list. If the host
24
- * list is absent/empty, has no stable identifiers, or the advisory selection is
25
- * empty or does not intersect the host list, everything is left untouched: an
26
- * empty advisory selection must never erase skills the host or user chose. This
27
- * is not measured as a token saving; it only narrows what the host may offer
28
- * for this turn.
86
+ * Resolve the observed skill list and say where it came from.
87
+ *
88
+ * The prompt list wins when it is a real array. Otherwise the per-turn draft
89
+ * (`ctx.skill.list()`, F-06) is reported as `draft`. The measured host shape
90
+ * carries the sentinel string `"undefined"` (F-08), which is treated as absent.
91
+ *
92
+ * The `draft` branch has **no production caller**: the shipped prompt hook calls
93
+ * `applyTurnDecisionToPrompt(prompt, decision)` without `skillsDraft`, and
94
+ * `ctx.skill.list()` is never read by it. At runtime `skillsSource` is therefore
95
+ * `none` or `prompt` only, and the `draft` source is exercised by tests alone.
29
96
  */
30
- function filterSkills(prompt: Record<string, unknown>, skillIds: readonly string[]): boolean {
31
- const skills = prompt.skills
32
- if (!Array.isArray(skills) || skills.length === 0) return false
33
- if (skillIds.length === 0) return false
34
- const identifiers = skills.map(skillIdentifier)
35
- if (identifiers.some((identifier) => identifier === undefined)) return false
36
- const selected = new Set(skillIds)
37
- const filtered = skills.filter((_, index) => {
38
- const identifier = identifiers[index]
97
+ export function resolveSkillSource(
98
+ promptSkills: unknown,
99
+ draftSkills?: unknown,
100
+ ): SkillSourceResolution {
101
+ const promptList = normalizeMeasuredValue(promptSkills)
102
+ const draftList = normalizeMeasuredValue(draftSkills)
103
+
104
+ if (Array.isArray(promptList) && promptList.length > 0) {
105
+ const resolved = identifiers(promptList)
106
+ return {
107
+ skillsSource: 'prompt',
108
+ skillIds: resolved.ids,
109
+ reason: resolved.unstable ? 'skills.source.unstable' : 'skills.source.prompt',
110
+ }
111
+ }
112
+ if (Array.isArray(draftList) && draftList.length > 0) {
113
+ const resolved = identifiers(draftList)
114
+ return {
115
+ skillsSource: 'draft',
116
+ skillIds: resolved.ids,
117
+ reason: resolved.unstable ? 'skills.source.unstable' : 'skills.source.draft',
118
+ }
119
+ }
120
+ return {
121
+ skillsSource: 'none',
122
+ skillIds: [],
123
+ reason: Array.isArray(promptList) ? 'skills.source.empty' : 'skills.source.absent',
124
+ }
125
+ }
126
+
127
+ /**
128
+ * Best-effort narrowing of the host's pre-resolution skill list.
129
+ *
130
+ * Only a real prompt array can be narrowed, and an empty advisory selection
131
+ * must never erase skills the host or user chose. The measured host shape is
132
+ * the sentinel string (F-08), so this is unreachable on the default path: P2 is
133
+ * an empirical no-op there (F-09). The array shape is synthetic — never
134
+ * observed — and its outcome is not a measured effect: PROBE-E measured no
135
+ * effect for any `prompt.skills`/`prompt.agents` mutation (F-24), while C6 as a
136
+ * question is closed for `skill.transform` and `prompt.text`.
137
+ */
138
+ function narrowSkills(
139
+ prompt: Record<string, unknown>,
140
+ selection: readonly string[],
141
+ draftSkills?: unknown,
142
+ ): SkillNarrowing {
143
+ const resolution = resolveSkillSource(prompt.skills, draftSkills)
144
+ if (selection.length === 0) {
145
+ return {
146
+ skillsFiltered: false,
147
+ skillsSource: resolution.skillsSource,
148
+ reason: 'selection.empty',
149
+ }
150
+ }
151
+ if (resolution.skillsSource !== 'prompt') {
152
+ return {
153
+ skillsFiltered: false,
154
+ skillsSource: resolution.skillsSource,
155
+ reason: resolution.reason,
156
+ }
157
+ }
158
+ if (resolution.skillIds.length === 0) {
159
+ return { skillsFiltered: false, skillsSource: 'prompt', reason: 'skills.source.unstable' }
160
+ }
161
+ const selected = new Set(selection)
162
+ const kept = (prompt.skills as readonly unknown[]).filter((item) => {
163
+ const identifier = skillIdentifier(item)
39
164
  return identifier !== undefined && selected.has(identifier)
40
165
  })
41
- if (filtered.length === 0) return false
42
- prompt.skills = filtered
43
- return true
166
+ if (kept.length === 0) {
167
+ return { skillsFiltered: false, skillsSource: 'prompt', reason: 'skills.selection.disjoint' }
168
+ }
169
+ prompt.skills = kept
170
+ return { skillsFiltered: true, skillsSource: 'prompt', reason: 'skills.synthetic.narrowed' }
44
171
  }
45
172
 
46
173
  function buildMarker(decision: TurnDecision): string | null {
@@ -56,32 +183,39 @@ function buildMarker(decision: TurnDecision): string | null {
56
183
  /**
57
184
  * Apply an advisory decision to the host prompt payload in place. It never
58
185
  * dispatches, changes permissions, or removes a pre-existing host marker.
186
+ * `skillsDraft` is the per-turn draft list; it is observed for `skillsSource`
187
+ * and never applied to admission.
59
188
  */
60
189
  export function applyTurnDecisionToPrompt(
61
190
  prompt: unknown,
62
191
  decision: TurnDecision | null,
192
+ skillsDraft?: unknown,
63
193
  ): PromptApplicationResult {
64
- const result: PromptApplicationResult = { markerApplied: false, skillsFiltered: false }
65
- if (
66
- prompt === null ||
67
- typeof prompt !== 'object' ||
68
- Array.isArray(prompt) ||
69
- decision === null ||
70
- !decision.active
71
- ) {
72
- return result
194
+ const invalid: PromptApplicationResult = {
195
+ markerApplied: false,
196
+ skillsFiltered: false,
197
+ skillsSource: 'none',
198
+ reason: 'invalid.payload',
73
199
  }
200
+ if (prompt === null || typeof prompt !== 'object' || Array.isArray(prompt)) return invalid
201
+ if (decision === null || !decision.active) return { ...invalid, reason: 'decision.inactive' }
74
202
  const target = prompt as Record<string, unknown>
75
- result.skillsFiltered = filterSkills(
203
+ const narrowing = narrowSkills(
76
204
  target,
77
205
  decision.skillIds.filter((id) => isPantheonSkillId(id)),
206
+ skillsDraft,
78
207
  )
208
+ const result: PromptApplicationResult = {
209
+ markerApplied: false,
210
+ skillsFiltered: narrowing.skillsFiltered,
211
+ skillsSource: narrowing.skillsSource,
212
+ reason: narrowing.reason,
213
+ }
79
214
  if (typeof target.text !== 'string' || target.text.includes(MARKER_PREFIX)) return result
80
215
  const marker = buildMarker(decision)
81
216
  if (marker === null) return result
82
217
  target.text = `${target.text}\n\n${marker}`
83
- result.markerApplied = true
84
- return result
218
+ return { ...result, markerApplied: true }
85
219
  }
86
220
 
87
221
  /** True when the prompt already carries a decision-router marker. */
@@ -99,16 +233,27 @@ export async function applyDecisionRouterToPrompt(
99
233
  permissionAssert?: TurnDecisionInput['permissionAssert'],
100
234
  requestText?: string,
101
235
  ): Promise<PromptApplicationResult> {
102
- const none: PromptApplicationResult = { markerApplied: false, skillsFiltered: false }
103
- if (admission === null || typeof admission !== 'object' || Array.isArray(admission)) return none
236
+ const none = (reason: PromptApplicationReason): PromptApplicationResult => ({
237
+ markerApplied: false,
238
+ skillsFiltered: false,
239
+ skillsSource: 'none',
240
+ reason,
241
+ })
242
+ if (admission === null || typeof admission !== 'object' || Array.isArray(admission)) {
243
+ return none('invalid.payload')
244
+ }
104
245
  const event = admission as { sessionID?: unknown; messageID?: unknown; prompt?: unknown }
105
246
  const prompt = event.prompt
106
- if (prompt === null || typeof prompt !== 'object' || Array.isArray(prompt)) return none
247
+ if (prompt === null || typeof prompt !== 'object' || Array.isArray(prompt)) {
248
+ return none('invalid.payload')
249
+ }
107
250
  const promptText = (prompt as { text?: unknown }).text
108
- if (typeof promptText !== 'string' || promptText.trim().length === 0) return none
251
+ if (typeof promptText !== 'string' || promptText.trim().length === 0) {
252
+ return none('request.empty')
253
+ }
109
254
  const text =
110
255
  typeof requestText === 'string' && requestText.trim().length > 0 ? requestText : promptText
111
- if (hasDecisionRouterMarker(text)) return none
256
+ if (hasDecisionRouterMarker(text)) return none('marker.present')
112
257
  try {
113
258
  const decision = await decideForTurn({
114
259
  request: text,
@@ -118,6 +263,6 @@ export async function applyDecisionRouterToPrompt(
118
263
  })
119
264
  return applyTurnDecisionToPrompt(prompt, decision)
120
265
  } catch {
121
- return none
266
+ return none('invalid.payload')
122
267
  }
123
268
  }
@@ -1,10 +1,19 @@
1
1
  import { PANTHEON_SKILL_CATALOG, PANTHEON_SKILL_IDS } from './pantheon-decision-catalog.ts'
2
2
 
3
- export type SkillSelectionReason = 'SELECTED_BY_KEYWORDS' | 'NO_LOCAL_MATCH' | 'INVALID_INPUT'
3
+ export type SkillSelectionReason =
4
+ | 'SELECTED_BY_KEYWORDS'
5
+ | 'SELECTED_BY_MATERIAL_REQUIREMENT'
6
+ | 'NO_LOCAL_MATCH'
7
+ | 'INVALID_INPUT'
8
+
9
+ /** Material requirement that must seat `artifact-management` (D2). */
10
+ export type MaterialRequirement = 'gate' | 'planning'
4
11
 
5
12
  export interface LocalSkillSelection {
6
13
  skillIds: string[]
7
14
  reasonCode: SkillSelectionReason
15
+ /** `null` unless the request materially requires a gate or a plan (D2). */
16
+ materialRequirement: MaterialRequirement | null
8
17
  }
9
18
 
10
19
  /** Bounded so a malformed or huge prompt can never fan out local work. */
@@ -106,6 +115,55 @@ const KEYWORDS: Readonly<Record<string, readonly string[]>> = Object.freeze({
106
115
  worktrees: ['worktree', 'worktrees', 'parallel', 'isolation', 'isolated'],
107
116
  })
108
117
 
118
+ /**
119
+ * Material gate/planning signals (D2).
120
+ *
121
+ * `artifact-management` exists for planned or materially risky work. Keyword
122
+ * scoring alone left it unreachable when the request demanded a gate or a plan
123
+ * without naming the artifact: "breaking change with human approval and a
124
+ * rollback plan" matched no keyword at all. These are static phrase/token
125
+ * lists, so detection stays local, deterministic, and bounded: no file, memory,
126
+ * catalog, or network read.
127
+ */
128
+ const MATERIAL_GATE_TOKENS: ReadonlySet<string> = new Set([
129
+ 'approval',
130
+ 'cutover',
131
+ 'gate',
132
+ 'irreversible',
133
+ 'signoff',
134
+ ])
135
+
136
+ const MATERIAL_GATE_PHRASES: readonly string[] = Object.freeze([
137
+ 'breaking change',
138
+ 'risk assessment',
139
+ 'risk review',
140
+ 'schema change',
141
+ 'sign off',
142
+ ])
143
+
144
+ const MATERIAL_PLANNING_TOKENS: ReadonlySet<string> = new Set([
145
+ 'deliverable',
146
+ 'deliverables',
147
+ 'milestone',
148
+ 'milestones',
149
+ 'plan',
150
+ 'planning',
151
+ 'roadmap',
152
+ 'rollback',
153
+ ])
154
+
155
+ const MATERIAL_PLANNING_PHRASES: readonly string[] = Object.freeze([
156
+ 'across phases',
157
+ 'break down',
158
+ 'design doc',
159
+ 'implementation plan',
160
+ 'migration plan',
161
+ 'rollout plan',
162
+ 'work breakdown',
163
+ ])
164
+
165
+ const ARTIFACT_SKILL_ID = 'artifact-management'
166
+
109
167
  const CATALOG_ORDER = new Map(PANTHEON_SKILL_CATALOG.map((entry, index) => [entry.id, index]))
110
168
 
111
169
  function normalize(value: string): string {
@@ -133,10 +191,53 @@ function scoreSkill(normalizedRequest: string, tokens: ReadonlySet<string>, skil
133
191
  return score
134
192
  }
135
193
 
194
+ function hasMaterialSignal(
195
+ normalizedRequest: string,
196
+ tokens: ReadonlySet<string>,
197
+ signalTokens: ReadonlySet<string>,
198
+ signalPhrases: readonly string[],
199
+ ): boolean {
200
+ for (const token of signalTokens) {
201
+ if (tokens.has(token)) return true
202
+ }
203
+ return signalPhrases.some((phrase) => normalizedRequest.includes(phrase))
204
+ }
205
+
206
+ /**
207
+ * Detect a material gate or planning requirement (D2). A gate requirement wins
208
+ * over a planning one, so the reported token is stable when both are present.
209
+ */
210
+ function detectMaterialRequirement(
211
+ normalizedRequest: string,
212
+ tokens: ReadonlySet<string>,
213
+ ): MaterialRequirement | null {
214
+ if (hasMaterialSignal(normalizedRequest, tokens, MATERIAL_GATE_TOKENS, MATERIAL_GATE_PHRASES)) {
215
+ return 'gate'
216
+ }
217
+ if (
218
+ hasMaterialSignal(
219
+ normalizedRequest,
220
+ tokens,
221
+ MATERIAL_PLANNING_TOKENS,
222
+ MATERIAL_PLANNING_PHRASES,
223
+ )
224
+ ) {
225
+ return 'planning'
226
+ }
227
+ return null
228
+ }
229
+
136
230
  /**
137
231
  * Select a small, deterministic set of allowlisted Pantheon skills for the
138
232
  * current request. This function never reads files, memory, transcripts, or
139
233
  * the network, and it never returns the whole catalog as a fallback.
234
+ *
235
+ * D2 — when the request materially requires a gate or a plan, the artifact
236
+ * skill is guaranteed a seat instead of depending on the literal keywords
237
+ * `artifact`/`planned`/`multi-phase`/`impl`. That seat is first, so a hard
238
+ * budget drops the lowest-scoring keyword skill rather than the required one.
239
+ * This only ranks identifiers: it does not filter or mutate any prompt, and P2
240
+ * remains an empirical no-op on the default path (F-09).
140
241
  */
141
242
  export function selectPantheonSkills(
142
243
  request: unknown,
@@ -150,22 +251,31 @@ export function selectPantheonSkills(
150
251
  maxSkills < 1 ||
151
252
  maxSkills > MAX_SELECTED_SKILLS
152
253
  ) {
153
- return { skillIds: [], reasonCode: 'INVALID_INPUT' }
254
+ return { skillIds: [], reasonCode: 'INVALID_INPUT', materialRequirement: null }
154
255
  }
155
256
 
156
257
  const normalizedRequest = normalize(request)
157
258
  const tokens = tokenize(normalizedRequest)
259
+ const material = detectMaterialRequirement(normalizedRequest, tokens)
158
260
  const scored: Array<{ id: string; score: number; order: number }> = []
159
261
  for (const skillId of PANTHEON_SKILL_IDS) {
160
262
  const score = scoreSkill(normalizedRequest, tokens, skillId)
161
263
  if (score <= 0) continue
162
264
  scored.push({ id: skillId, score, order: CATALOG_ORDER.get(skillId) ?? 0 })
163
265
  }
164
- if (scored.length === 0) return { skillIds: [], reasonCode: 'NO_LOCAL_MATCH' }
266
+ if (material === null && scored.length === 0) {
267
+ return { skillIds: [], reasonCode: 'NO_LOCAL_MATCH', materialRequirement: null }
268
+ }
165
269
 
166
270
  scored.sort((left, right) => right.score - left.score || left.order - right.order)
271
+ const ranked = scored.map((entry) => entry.id)
272
+ const ordered =
273
+ material === null
274
+ ? ranked
275
+ : [ARTIFACT_SKILL_ID, ...ranked.filter((id) => id !== ARTIFACT_SKILL_ID)]
167
276
  return {
168
- skillIds: scored.slice(0, maxSkills).map((entry) => entry.id),
169
- reasonCode: 'SELECTED_BY_KEYWORDS',
277
+ skillIds: ordered.slice(0, maxSkills),
278
+ reasonCode: material === null ? 'SELECTED_BY_KEYWORDS' : 'SELECTED_BY_MATERIAL_REQUIREMENT',
279
+ materialRequirement: material,
170
280
  }
171
281
  }
@@ -8,6 +8,8 @@ import {
8
8
  loadLocalDecisionPolicy,
9
9
  recommendLocalOrchestration,
10
10
  } from './local-orchestration.ts'
11
+ import { evaluateComplexityPoint } from './v2-decision-points/p3-complexity.ts'
12
+ import type { ShadowSink } from './v2-decision-shadow.ts'
11
13
 
12
14
  const TOOL_DESCRIPTION =
13
15
  'Zeus-only local advisory selector. Use selectively only when specialist routing is genuinely ' +
@@ -48,6 +50,32 @@ type LocalDecisionToolOptions = {
48
50
  loadPolicy?: () => Promise<LocalDecisionPolicy | undefined>
49
51
  }
50
52
 
53
+ /**
54
+ * Optional shadow observer for the V2 tool point.
55
+ *
56
+ * P3 declares `tool.invoke`, and the local selector's input is the surface that
57
+ * carries `complexity` and `gateStatus`. The sink is supplied by the plugin when
58
+ * it registers the tool; nothing here applies its record.
59
+ */
60
+ type LocalDecisionShadowOptions = {
61
+ sink?: ShadowSink
62
+ }
63
+
64
+ /**
65
+ * Observe P3 in shadow at `tool.invoke`.
66
+ *
67
+ * Contained on purpose: the adapter already contains its own failures, and
68
+ * this wrapper guarantees that even an unexpected throw cannot change the
69
+ * tool result. No input is mutated and no decision is applied.
70
+ */
71
+ function observeToolComplexity(input: unknown, sink?: ShadowSink): void {
72
+ try {
73
+ evaluateComplexityPoint(input, sink)
74
+ } catch {
75
+ // Shadow is best-effort; the tool result is unaffected.
76
+ }
77
+ }
78
+
51
79
  async function runDecision(
52
80
  input: unknown,
53
81
  callerAgent: unknown,
@@ -108,7 +136,9 @@ const v2InputSchema: Record<string, unknown> = {
108
136
  }
109
137
 
110
138
  /** Create a V2 transform definition with the same Zeus-only execution guard and local plan. */
111
- export function createV2LocalDecisionDefinition(options: LocalDecisionToolOptions = {}) {
139
+ export function createV2LocalDecisionDefinition(
140
+ options: LocalDecisionToolOptions & LocalDecisionShadowOptions = {},
141
+ ) {
112
142
  const policyLoader = options.loadPolicy ?? loadLocalDecisionPolicy
113
143
  return {
114
144
  name: 'pantheon_local_decision',
@@ -116,6 +146,10 @@ export function createV2LocalDecisionDefinition(options: LocalDecisionToolOption
116
146
  input: v2InputSchema,
117
147
  output: {},
118
148
  execute: async (input: Record<string, unknown>, context: unknown) => {
149
+ // P3 shadow observation at `tool.invoke`. The input schema declares
150
+ // `complexity` and `gateStatus`, so this is the one wired surface that
151
+ // can feed a complexity decision; the record never alters the result.
152
+ observeToolComplexity(input, options.sink)
119
153
  const callerAgent =
120
154
  context !== null && typeof context === 'object'
121
155
  ? (context as { agent?: unknown }).agent