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

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 (35) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +38 -1
  3. package/bin/pantheon-init.mjs +17 -0
  4. package/package.json +9 -3
  5. package/plugin.json +1 -1
  6. package/pyproject.toml +1 -1
  7. package/scripts/decision-router-budget.mjs +781 -0
  8. package/scripts/decision-router.mjs +297 -0
  9. package/scripts/install/decision-router-config.mjs +432 -0
  10. package/scripts/install/interactive.mjs +76 -5
  11. package/scripts/install/opencode.mjs +12 -0
  12. package/scripts/install/state.mjs +5 -0
  13. package/scripts/install/strings.mjs +4 -0
  14. package/src/agents/zeus.md +12 -0
  15. package/src/pantheon/local-decision-agents.ts +170 -0
  16. package/src/pantheon/local-decision-budget.ts +1043 -0
  17. package/src/pantheon/local-decision-egress-gate.ts +264 -0
  18. package/src/pantheon/local-decision-prompt.ts +123 -0
  19. package/src/pantheon/local-decision-provider-matrix.ts +92 -0
  20. package/src/pantheon/local-decision-provider-protocol.ts +335 -0
  21. package/src/pantheon/local-decision-provider.internal.ts +260 -0
  22. package/src/pantheon/local-decision-router.ts +225 -0
  23. package/src/pantheon/local-decision-skills.ts +171 -0
  24. package/src/pantheon/local-decision-tool.ts +126 -0
  25. package/src/pantheon/local-decision-turn.ts +338 -0
  26. package/src/pantheon/local-decision-usage-evidence.internal.ts +207 -0
  27. package/src/pantheon/local-orchestration.ts +322 -0
  28. package/src/pantheon/pantheon-decision-catalog.ts +101 -0
  29. package/src/pantheon/v2-tools.ts +15 -14
  30. package/src/plugin-v2.ts +52 -19
  31. package/src/plugin.ts +4 -0
  32. package/src/plugins/tui/dist/tui-v2.js +3 -3
  33. package/src/plugins/tui/dist/tui.js +1 -1
  34. package/src/plugins/tui/package-lock.json +2 -2
  35. package/src/plugins/tui/package.json +1 -1
@@ -0,0 +1,322 @@
1
+ import { readFile } from 'node:fs/promises'
2
+ import { load } from 'js-yaml'
3
+ import {
4
+ classifyLocalDecisionComplexity,
5
+ LOCAL_DECISION_COMPLEXITY_DIMENSIONS,
6
+ LOCAL_DECISION_ROUTER_POLICY_VERSION,
7
+ type LocalDecisionComplexityDimensions,
8
+ type LocalDecisionGateStatus,
9
+ } from './local-decision-router.ts'
10
+ import { isAgentAllowed, type PermissionTaskConfig } from './permission-globs.ts'
11
+ import { PANTHEON_AGENTS } from './v2-delegation-enforce.ts'
12
+
13
+ export interface LocalDecisionAgentPolicy {
14
+ canDelegateTo: readonly string[]
15
+ canReceiveDelegation: boolean
16
+ capabilities: readonly string[]
17
+ skills: readonly string[]
18
+ }
19
+
20
+ export interface LocalDecisionPolicy {
21
+ agents: Readonly<Record<string, LocalDecisionAgentPolicy>>
22
+ permissionTask: PermissionTaskConfig
23
+ }
24
+
25
+ export interface LocalOrchestrationInput {
26
+ schemaVersion: 1
27
+ candidateAgents: readonly string[]
28
+ domain: string | null
29
+ candidateSkillIds: readonly string[]
30
+ candidateResourceIds: readonly string[]
31
+ memorySearchRelevant: boolean
32
+ gateStatus: LocalDecisionGateStatus
33
+ complexity: LocalDecisionComplexityDimensions
34
+ }
35
+
36
+ export type LocalOrchestrationReasonCode =
37
+ | 'CALLER_NOT_ZEUS'
38
+ | 'INVALID_INPUT'
39
+ | 'POLICY_UNAVAILABLE'
40
+ | 'NO_ELIGIBLE_CANDIDATE'
41
+ | 'AMBIGUOUS_CANDIDATE'
42
+ | 'DOMAIN_NOT_ELIGIBLE'
43
+ | 'ADVISORY_ROUTE'
44
+ | 'PROVIDER_RECOMMENDATION'
45
+ | 'PROVIDER_ABSTENTION'
46
+
47
+ export interface LocalOrchestrationPlan {
48
+ schemaVersion: 1
49
+ policyVersion: typeof LOCAL_DECISION_ROUTER_POLICY_VERSION
50
+ decision: 'recommend' | 'abstain'
51
+ reasonCode: LocalOrchestrationReasonCode
52
+ agent: string | null
53
+ skillIds: string[]
54
+ resourceIds: string[]
55
+ recommendMemorySearch: boolean
56
+ gateStatus: LocalDecisionGateStatus
57
+ complexity: ReturnType<typeof classifyLocalDecisionComplexity>
58
+ action: 'advisory_only'
59
+ }
60
+
61
+ const GATE_STATUSES = new Set<LocalDecisionGateStatus>([
62
+ 'none',
63
+ 'review_required',
64
+ 'human_approval_required',
65
+ 'unresolved',
66
+ ])
67
+ const INPUT_KEYS = [
68
+ 'candidateAgents',
69
+ 'candidateResourceIds',
70
+ 'candidateSkillIds',
71
+ 'complexity',
72
+ 'domain',
73
+ 'gateStatus',
74
+ 'memorySearchRelevant',
75
+ 'schemaVersion',
76
+ ]
77
+ const RESOURCE_IDS = new Set(['pantheon://agents', 'pantheon://routing', 'pantheon://skills'])
78
+
79
+ function isRecord(value: unknown): value is Record<string, unknown> {
80
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
81
+ const prototype = Object.getPrototypeOf(value)
82
+ return prototype === Object.prototype || prototype === null
83
+ }
84
+
85
+ function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
86
+ const actual = Object.keys(value).sort()
87
+ const expected = [...keys].sort()
88
+ return actual.length === expected.length && actual.every((key, index) => key === expected[index])
89
+ }
90
+
91
+ function stringArray(value: unknown): value is string[] {
92
+ return Array.isArray(value) && value.every((item) => typeof item === 'string')
93
+ }
94
+
95
+ function hasUsablePolicy(policy: LocalDecisionPolicy | undefined): policy is LocalDecisionPolicy {
96
+ if (
97
+ policy === undefined ||
98
+ !isRecord(policy.agents) ||
99
+ !isRecord(policy.permissionTask) ||
100
+ !isRecord(policy.agents.zeus)
101
+ ) {
102
+ return false
103
+ }
104
+ const grants = Object.entries(policy.permissionTask)
105
+ return (
106
+ grants.length > 0 &&
107
+ grants.every(([, action]) => action === 'allow' || action === 'deny') &&
108
+ stringArray(policy.agents.zeus.canDelegateTo) &&
109
+ stringArray(policy.agents.zeus.capabilities)
110
+ )
111
+ }
112
+
113
+ function parsePolicy(raw: unknown): LocalDecisionPolicy | undefined {
114
+ if (!isRecord(raw) || !isRecord(raw.agents) || !isRecord(raw.permission)) return undefined
115
+ const permission = raw.permission.task
116
+ if (!isRecord(permission)) return undefined
117
+
118
+ const permissionTask: Record<string, 'allow' | 'deny'> = {}
119
+ for (const [pattern, action] of Object.entries(permission)) {
120
+ if (action !== 'allow' && action !== 'deny') return undefined
121
+ permissionTask[pattern] = action
122
+ }
123
+ if (Object.keys(permissionTask).length === 0) return undefined
124
+
125
+ const agents: Record<string, LocalDecisionAgentPolicy> = {}
126
+ for (const [id, value] of Object.entries(raw.agents)) {
127
+ if (!PANTHEON_AGENTS.has(id) || !isRecord(value)) continue
128
+ const canDelegateTo =
129
+ value.subagent_can_delegate_to === undefined && value.can_delegate === false
130
+ ? []
131
+ : value.subagent_can_delegate_to
132
+ if (
133
+ typeof value.can_receive_delegation !== 'boolean' ||
134
+ !stringArray(canDelegateTo) ||
135
+ !stringArray(value.skills) ||
136
+ !stringArray(value.capabilities)
137
+ ) {
138
+ return undefined
139
+ }
140
+ if (
141
+ canDelegateTo.some((target) => !PANTHEON_AGENTS.has(target)) ||
142
+ value.skills.some((skill) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill))
143
+ ) {
144
+ return undefined
145
+ }
146
+ agents[id] = {
147
+ canDelegateTo,
148
+ canReceiveDelegation: value.can_receive_delegation,
149
+ capabilities: value.capabilities,
150
+ skills: value.skills,
151
+ }
152
+ }
153
+ if (agents.zeus === undefined) return undefined
154
+ return { agents, permissionTask }
155
+ }
156
+
157
+ let policyCache: Promise<LocalDecisionPolicy | undefined> | undefined
158
+
159
+ /**
160
+ * Load only local, non-secret policy metadata; missing or invalid policy abstains.
161
+ * `routing.yml` is a static package asset, so the parsed policy is cached for
162
+ * the process lifetime. Failures are not cached: the next prompt retries, and a
163
+ * test/admin can call `clearLocalDecisionPolicyCache()` to invalidate safely.
164
+ */
165
+ export async function loadLocalDecisionPolicy(): Promise<LocalDecisionPolicy | undefined> {
166
+ if (policyCache === undefined) {
167
+ policyCache = readLocalDecisionPolicy().then(
168
+ (policy) => {
169
+ if (policy === undefined) policyCache = undefined
170
+ return policy
171
+ },
172
+ () => {
173
+ policyCache = undefined
174
+ return undefined
175
+ },
176
+ )
177
+ }
178
+ return policyCache
179
+ }
180
+
181
+ /** Test/admin seam: drop the process policy cache without discharging any state. */
182
+ export function clearLocalDecisionPolicyCache(): void {
183
+ policyCache = undefined
184
+ }
185
+
186
+ async function readLocalDecisionPolicy(): Promise<LocalDecisionPolicy | undefined> {
187
+ try {
188
+ const routingUrl = new URL('../routing.yml', import.meta.url)
189
+ const parsed = load(await readFile(routingUrl, 'utf8'))
190
+ return parsePolicy(parsed)
191
+ } catch {
192
+ return undefined
193
+ }
194
+ }
195
+
196
+ function isValidInput(value: unknown): value is LocalOrchestrationInput {
197
+ if (!isRecord(value) || !exactKeys(value, INPUT_KEYS) || value.schemaVersion !== 1) return false
198
+ if (
199
+ !stringArray(value.candidateAgents) ||
200
+ value.candidateAgents.length > 14 ||
201
+ !stringArray(value.candidateSkillIds) ||
202
+ value.candidateSkillIds.length > 64 ||
203
+ !stringArray(value.candidateResourceIds) ||
204
+ value.candidateResourceIds.length > 32 ||
205
+ (value.domain !== null && typeof value.domain !== 'string') ||
206
+ typeof value.memorySearchRelevant !== 'boolean' ||
207
+ typeof value.gateStatus !== 'string' ||
208
+ !GATE_STATUSES.has(value.gateStatus as LocalDecisionGateStatus) ||
209
+ !isRecord(value.complexity)
210
+ ) {
211
+ return false
212
+ }
213
+ return (
214
+ exactKeys(value.complexity, LOCAL_DECISION_COMPLEXITY_DIMENSIONS) &&
215
+ classifyLocalDecisionComplexity(value.complexity).label !== 'abstain'
216
+ )
217
+ }
218
+
219
+ function abstain(
220
+ reasonCode: LocalOrchestrationReasonCode,
221
+ gateStatus: LocalDecisionGateStatus = 'unresolved',
222
+ complexity?: unknown,
223
+ ): LocalOrchestrationPlan {
224
+ return {
225
+ schemaVersion: 1,
226
+ policyVersion: LOCAL_DECISION_ROUTER_POLICY_VERSION,
227
+ decision: 'abstain',
228
+ reasonCode,
229
+ agent: null,
230
+ skillIds: [],
231
+ resourceIds: [],
232
+ recommendMemorySearch: false,
233
+ gateStatus,
234
+ complexity: classifyLocalDecisionComplexity(complexity),
235
+ action: 'advisory_only',
236
+ }
237
+ }
238
+
239
+ /** Build an advisory plan from structured candidate IDs; this function never dispatches. */
240
+ export function recommendLocalOrchestration(
241
+ input: unknown,
242
+ callerAgent: unknown,
243
+ policy: LocalDecisionPolicy | undefined,
244
+ ): LocalOrchestrationPlan {
245
+ try {
246
+ return evaluateLocalOrchestration(input, callerAgent, policy)
247
+ } catch {
248
+ return abstain('INVALID_INPUT')
249
+ }
250
+ }
251
+
252
+ function evaluateLocalOrchestration(
253
+ input: unknown,
254
+ callerAgent: unknown,
255
+ policy: LocalDecisionPolicy | undefined,
256
+ ): LocalOrchestrationPlan {
257
+ if (callerAgent !== 'zeus') return abstain('CALLER_NOT_ZEUS')
258
+ if (!hasUsablePolicy(policy)) {
259
+ return abstain('POLICY_UNAVAILABLE')
260
+ }
261
+ if (!isValidInput(input)) return abstain('INVALID_INPUT')
262
+
263
+ const gateStatus = input.gateStatus
264
+ const complexity = classifyLocalDecisionComplexity(input.complexity)
265
+ const zeus = policy.agents.zeus
266
+ if (zeus === undefined) return abstain('POLICY_UNAVAILABLE', gateStatus, input.complexity)
267
+ const eligible = [...new Set(input.candidateAgents)].filter((candidate) => {
268
+ const target = policy.agents[candidate]
269
+ return (
270
+ candidate !== 'zeus' &&
271
+ PANTHEON_AGENTS.has(candidate) &&
272
+ target?.canReceiveDelegation === true &&
273
+ zeus.canDelegateTo.includes(candidate) &&
274
+ isAgentAllowed(policy.permissionTask, candidate)
275
+ )
276
+ })
277
+
278
+ if (eligible.length === 0) return abstain('NO_ELIGIBLE_CANDIDATE', gateStatus, input.complexity)
279
+
280
+ let agent: string
281
+ if (input.domain !== null) {
282
+ if (!eligible.includes(input.domain)) {
283
+ return abstain('DOMAIN_NOT_ELIGIBLE', gateStatus, input.complexity)
284
+ }
285
+ agent = input.domain
286
+ } else if (eligible.length === 1) {
287
+ const [onlyEligible] = eligible
288
+ if (onlyEligible === undefined) {
289
+ return abstain('NO_ELIGIBLE_CANDIDATE', gateStatus, input.complexity)
290
+ }
291
+ agent = onlyEligible
292
+ } else {
293
+ return abstain('AMBIGUOUS_CANDIDATE', gateStatus, input.complexity)
294
+ }
295
+
296
+ const agentPolicy = policy.agents[agent]
297
+ if (agentPolicy === undefined) return abstain('POLICY_UNAVAILABLE', gateStatus, input.complexity)
298
+ const skillIds = input.candidateSkillIds.filter(
299
+ (skill, index, all) => all.indexOf(skill) === index && agentPolicy.skills.includes(skill),
300
+ )
301
+ const allowedResources = new Set(RESOURCE_IDS)
302
+ for (const skill of skillIds) allowedResources.add(`pantheon://skills/${skill}`)
303
+ if (PANTHEON_AGENTS.has(agent)) allowedResources.add(`pantheon://agents/${agent}`)
304
+ const resourceIds = input.candidateResourceIds.filter(
305
+ (resource, index, all) => all.indexOf(resource) === index && allowedResources.has(resource),
306
+ )
307
+
308
+ return {
309
+ schemaVersion: 1,
310
+ policyVersion: LOCAL_DECISION_ROUTER_POLICY_VERSION,
311
+ decision: 'recommend',
312
+ reasonCode: 'ADVISORY_ROUTE',
313
+ agent,
314
+ skillIds,
315
+ resourceIds,
316
+ recommendMemorySearch:
317
+ input.memorySearchRelevant && zeus.capabilities.includes('memory_recall'),
318
+ gateStatus,
319
+ complexity,
320
+ action: 'advisory_only',
321
+ }
322
+ }
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Allowlisted, short Pantheon catalog used by the per-turn decision router.
3
+ *
4
+ * Only IDs and one-line descriptions live here. Full skill bodies, agent
5
+ * prompts, file paths, memory contents, and transcripts are never included in
6
+ * a provider payload.
7
+ */
8
+
9
+ export interface DecisionCatalogEntry {
10
+ id: string
11
+ description: string
12
+ }
13
+
14
+ export const PANTHEON_SKILL_CATALOG: readonly DecisionCatalogEntry[] = Object.freeze([
15
+ { id: 'agent-coordination', description: 'Multi-agent orchestration, routing, and delegation.' },
16
+ { id: 'artifact-management', description: 'Structured artifacts for planned or risky work.' },
17
+ { id: 'auto-continue', description: 'Continue multi-step todos while keeping safety gates.' },
18
+ { id: 'clonedeps', description: 'Clone dependency source locally for inspection.' },
19
+ { id: 'code-review-checklist', description: 'Systematic code review and quality gates.' },
20
+ { id: 'codemap', description: 'Map repository structure before deep reading.' },
21
+ { id: 'context-compression', description: 'Explicit compaction and resumable checkpoints.' },
22
+ { id: 'git-workflow-and-versioning', description: 'Atomic commits and versioning workflow.' },
23
+ { id: 'incremental-implementation', description: 'Thin, testable, rollback-safe slices.' },
24
+ { id: 'loop-engineering', description: 'Controlled iterative refinement cycles.' },
25
+ { id: 'memory-bank', description: 'Memory-bank structure, rules, and maintenance.' },
26
+ { id: 'reflect', description: 'Turn repeated workflow friction into reusable assets.' },
27
+ { id: 'security-hardening', description: 'Security gate: OWASP, secrets, dependencies.' },
28
+ { id: 'session-goal', description: 'Pin the session objective against scope creep.' },
29
+ { id: 'simplify', description: 'Behavior-preserving code simplification.' },
30
+ {
31
+ id: 'spec-driven-development',
32
+ description: 'Spec-first requirements and acceptance criteria.',
33
+ },
34
+ {
35
+ id: 'tdd-with-agents',
36
+ description: 'RED, GREEN, REFACTOR test-driven implementation.',
37
+ },
38
+ { id: 'verification-planning', description: 'Plan the evidence path before changing code.' },
39
+ {
40
+ id: 'visual-review-pipeline',
41
+ description: 'Automated visual review with screenshots and fixes.',
42
+ },
43
+ { id: 'worktrees', description: 'Isolated git worktrees for parallel or risky work.' },
44
+ ])
45
+
46
+ export const PANTHEON_AGENT_CATALOG: readonly DecisionCatalogEntry[] = Object.freeze([
47
+ { id: 'zeus', description: 'Central orchestrator; never implements.' },
48
+ { id: 'athena', description: 'Plan-only architect and strategic planner.' },
49
+ { id: 'apollo', description: 'Read-only investigation and discovery scout.' },
50
+ { id: 'hermes', description: 'Backend specialist: FastAPI, Python, async.' },
51
+ { id: 'aphrodite', description: 'Frontend specialist: React, TypeScript, WCAG.' },
52
+ { id: 'demeter', description: 'Database specialist: SQLAlchemy, migrations, queries.' },
53
+ { id: 'themis', description: 'Quality and security review gate.' },
54
+ { id: 'prometheus', description: 'Infrastructure, Docker, CI, and model providers.' },
55
+ { id: 'hephaestus', description: 'AI pipelines: LangChain, RAG, vector stores.' },
56
+ { id: 'nyx', description: 'Observability, tracing, and cost analytics.' },
57
+ { id: 'gaia', description: 'Remote sensing and geospatial analysis.' },
58
+ { id: 'iris', description: 'GitHub branches, pull requests, issues, releases.' },
59
+ { id: 'mnemosyne', description: 'Memory bank and ADR authoring on request.' },
60
+ { id: 'talos', description: 'Small hotfixes, typos, and CSS fixes.' },
61
+ ])
62
+
63
+ const SKILL_IDS = new Set(PANTHEON_SKILL_CATALOG.map((entry) => entry.id))
64
+ const AGENT_IDS = new Set(PANTHEON_AGENT_CATALOG.map((entry) => entry.id))
65
+
66
+ export const PANTHEON_SKILL_IDS: ReadonlySet<string> = SKILL_IDS
67
+ export const PANTHEON_AGENT_IDS: ReadonlySet<string> = AGENT_IDS
68
+
69
+ export function isPantheonSkillId(value: unknown): value is string {
70
+ return typeof value === 'string' && SKILL_IDS.has(value)
71
+ }
72
+
73
+ export function isPantheonAgentId(value: unknown): value is string {
74
+ return typeof value === 'string' && AGENT_IDS.has(value)
75
+ }
76
+
77
+ export function skillCatalogEntry(id: string): DecisionCatalogEntry | undefined {
78
+ return PANTHEON_SKILL_CATALOG.find((entry) => entry.id === id)
79
+ }
80
+
81
+ export function agentCatalogEntry(id: string): DecisionCatalogEntry | undefined {
82
+ return PANTHEON_AGENT_CATALOG.find((entry) => entry.id === id)
83
+ }
84
+
85
+ /** Build the short skill catalog subset for an explicit ID list. */
86
+ export function skillCatalogSubset(ids: readonly string[]): DecisionCatalogEntry[] {
87
+ const selected = new Set(ids)
88
+ return PANTHEON_SKILL_CATALOG.filter((entry) => selected.has(entry.id)).map((entry) => ({
89
+ id: entry.id,
90
+ description: entry.description,
91
+ }))
92
+ }
93
+
94
+ /** Build the short agent catalog subset for an explicit ID list. */
95
+ export function agentCatalogSubset(ids: readonly string[]): DecisionCatalogEntry[] {
96
+ const selected = new Set(ids)
97
+ return PANTHEON_AGENT_CATALOG.filter((entry) => selected.has(entry.id)).map((entry) => ({
98
+ id: entry.id,
99
+ description: entry.description,
100
+ }))
101
+ }
@@ -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 unconditional tools
5
+ * ## Why four 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`,
@@ -14,18 +14,19 @@
14
14
  * output contract on every call, so it buys nothing. See
15
15
  * `V2_UNSUPPORTED_FEATURES` in `../plugin-v2.ts` (marker `goal-tools`).
16
16
  *
17
- * `hashline_edit` (pure filesystem), `pantheon_cost` (reads `opencode.db`) and
18
- * `pantheon_model` (reads/writes `active-preset.json`) need none of that, so
19
- * they are wired to their real V1 implementations.
17
+ * `hashline_edit` (pure filesystem), `pantheon_cost` (reads `opencode.db`),
18
+ * `pantheon_model` (reads/writes `active-preset.json`), and the local-only
19
+ * `pantheon_local_decision` selector need none of that. Its execution rejects
20
+ * any host context that does not identify Zeus.
20
21
  *
21
- * ## Three unconditional tools, up to two host-dependent ones
22
+ * ## Four unconditional tools, up to two host-dependent ones
22
23
  *
23
- * The three above are always built. Two more exist on the V2 host and are
24
+ * The four above are always built. Two more exist on the V2 host and are
24
25
  * conditional: `vision_describe` is added here when the caller supplies a
25
26
  * vision runtime (the host model catalog), and `pantheon_bounded_read` is
26
27
  * 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.
28
+ * (root Zeus sessions only). The effective count is therefore 4 unconditional
29
+ * plus up to 2 host-dependent.
29
30
  *
30
31
  * ## The output declaration is mandatory
31
32
  *
@@ -47,6 +48,7 @@
47
48
 
48
49
  import { createCostCommand } from './cost-command.ts'
49
50
  import { createHashlineEditTool, type HashlineToolResult } from './hashline/tool.ts'
51
+ import { createV2LocalDecisionDefinition } from './local-decision-tool.ts'
50
52
  import { createModelCommand } from './model-command.ts'
51
53
  import type { ToolContextLike } from './tool-context.ts'
52
54
  import { createV2VisionTool, type V2VisionRuntime } from './v2-vision.ts'
@@ -427,12 +429,10 @@ async function executeModel(
427
429
  * to fail validation. The protection against forgetting the field is the
428
430
  * required `output` on `V2ToolDef`, not the emptiness of this schema.
429
431
  *
430
- * The three tool instances (`hashlineEdit`, `costCommand`, `modelCommand`) are
431
- * module-level consts created once at import, not per call. What matters for
432
- * this function is only that it allocates a fresh descriptor array each call,
433
- * so a caller cannot mutate another's definitions. None of the three factories
434
- * performs filesystem or database work at construction, so importing this
435
- * module stays side-effect free.
432
+ * The existing tool instances (`hashlineEdit`, `costCommand`, `modelCommand`)
433
+ * are module-level consts created once at import. The local selector is a
434
+ * per-call definition with no construction-time I/O. A fresh descriptor array
435
+ * prevents callers from mutating another registration's definitions.
436
436
  */
437
437
  export function createV2ToolDefinitions(visionRuntime?: V2VisionRuntime): V2ToolDef[] {
438
438
  const definitions: V2ToolDef[] = [
@@ -475,6 +475,7 @@ export function createV2ToolDefinitions(visionRuntime?: V2VisionRuntime): V2Tool
475
475
  execute: executeModel,
476
476
  },
477
477
  ]
478
+ definitions.push(createV2LocalDecisionDefinition())
478
479
  if (visionRuntime) definitions.push(createV2VisionTool(visionRuntime))
479
480
  return definitions
480
481
  }
package/src/plugin-v2.ts CHANGED
@@ -2,12 +2,14 @@
2
2
  * Pantheon V2 Plugin — full orchestration plugin for OpenCode V2.
3
3
  *
4
4
  * Registers:
5
- * - 3 unconditional self-sufficient tools via V2 tool.transform (hashline_edit,
6
- * pantheon_cost, pantheon_model) plus up to 2 host-dependent ones: native
5
+ * - 4 unconditional self-sufficient tools via V2 tool.transform (hashline_edit,
6
+ * pantheon_cost, pantheon_model, pantheon_local_decision) plus up to 2 host-dependent ones: native
7
7
  * `vision_describe` when the host exposes the V2 model catalog (it resolves
8
8
  * OpenCode Zen auth and sends images directly to the selected multimodal
9
9
  * model), and `pantheon_bounded_read` when the host exposes its permission
10
10
  * and session APIs (root Zeus sessions only).
11
+ * `pantheon_local_decision` is advisory and rejects execution unless the
12
+ * host tool context identifies the caller as Zeus.
11
13
  * The goal tools need V1 infrastructure and are absent from this surface.
12
14
  * - 5 event subscriptions (session.created, idle, deleted, error, compacted)
13
15
  * - Session hooks (prompt, context, compaction)
@@ -108,6 +110,8 @@ import {
108
110
  } from './pantheon/delegation-enforce.ts'
109
111
  import { GOAL_LOOP_DEFAULTS, GoalStore } from './pantheon/goal-loop.ts'
110
112
  import { createGuardPathResolver } from './pantheon/guard-path.ts'
113
+ import { DECISION_EGRESS_ACTION } from './pantheon/local-decision-egress-gate.ts'
114
+ import { applyDecisionRouterToPrompt } from './pantheon/local-decision-prompt.ts'
111
115
  import { getSharedBoard } from './pantheon/shared-board.ts'
112
116
  import {
113
117
  TODO_ENFORCER_DEFAULTS,
@@ -1024,7 +1028,14 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
1024
1028
  // Config validity is independent of hook availability; warn before the early
1025
1029
  // return so a typo is visible even on a host that registers no session hook.
1026
1030
  warnContextPrunerConfigOnce(context.options)
1027
- const sessionCtx = hostDomains(context).session
1031
+ const host = hostDomains(context)
1032
+ const sessionCtx = host.session
1033
+ const permission = host.permission
1034
+ const assertPermission = permission?.assert
1035
+ const permissionAssert =
1036
+ typeof assertPermission === 'function'
1037
+ ? (input: Record<string, unknown>) => assertPermission.call(permission, input)
1038
+ : undefined
1028
1039
 
1029
1040
  if (!sessionCtx?.hook) {
1030
1041
  return false
@@ -1116,7 +1127,7 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
1116
1127
  // "prompt" hook — preserve attached image references and add model-visible
1117
1128
  // instructions so Zeus can inspect visual context and pass it to the
1118
1129
  // implementation specialist before editing.
1119
- await sessionCtx.hook('prompt', (event: unknown) => {
1130
+ await sessionCtx.hook('prompt', async (event: unknown) => {
1120
1131
  try {
1121
1132
  // 2.0.29 host payload: `{ sessionID, messageID, prompt: { text,
1122
1133
  // files, agents, skills }, metadata, delivery }`. The session id is
@@ -1124,17 +1135,25 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
1124
1135
  // data: attachment's panic-free moment also relays it to the MCP.
1125
1136
  const admission = event as {
1126
1137
  sessionID?: unknown
1127
- prompt?: { text?: unknown; files?: unknown }
1138
+ messageID?: unknown
1139
+ prompt?: { text?: unknown; files?: unknown; skills?: unknown }
1128
1140
  } | null
1129
1141
  const prompt = admission?.prompt
1130
1142
  if (!prompt || typeof prompt.text !== 'string') return
1131
- if (prompt.text.includes('<!-- pantheon-v2-visual-context -->')) return
1132
- const sessionID =
1133
- typeof admission?.sessionID === 'string' && admission.sessionID.trim() !== ''
1134
- ? admission.sessionID
1135
- : undefined
1136
- const visualContext = buildV2VisionPromptContext(prompt.files, prompt.text, sessionID)
1137
- if (visualContext) prompt.text = `${prompt.text}\n\n${visualContext}`
1143
+ const userRequest = prompt.text
1144
+ if (!prompt.text.includes('<!-- pantheon-v2-visual-context -->')) {
1145
+ const sessionID =
1146
+ typeof admission?.sessionID === 'string' && admission.sessionID.trim() !== ''
1147
+ ? admission.sessionID
1148
+ : undefined
1149
+ const visualContext = buildV2VisionPromptContext(prompt.files, prompt.text, sessionID)
1150
+ if (visualContext) prompt.text = `${prompt.text}\n\n${visualContext}`
1151
+ }
1152
+
1153
+ // Advisory per-turn selection. The helper reads only the prompt text
1154
+ // captured before Pantheon's own visual context, and the router caches
1155
+ // per session/message, so a repeated admission cannot call twice.
1156
+ await applyDecisionRouterToPrompt(admission, permissionAssert, userRequest)
1138
1157
  } catch {
1139
1158
  // Fail-open: malformed/unsupported prompt shapes must not block input.
1140
1159
  }
@@ -1855,6 +1874,17 @@ async function registerV2PermissionHook(
1855
1874
  deny('permission event is missing')
1856
1875
  return
1857
1876
  }
1877
+ // `decision.egress` is Pantheon's own custom action. It is NOT decided
1878
+ // here: the user-level config/consent is the source of truth, and the
1879
+ // host's own permission rules are the kill-switch (see
1880
+ // local-decision-egress-gate). The v2.2.0 canary observed this hook runs
1881
+ // on the allow path of `permission.assert` and is skipped for an explicit
1882
+ // deny, so egress must never depend on it. Leaving the effect untouched
1883
+ // preserves whatever the host decided.
1884
+ if (event.action === DECISION_EGRESS_ACTION) {
1885
+ writeProof()
1886
+ return
1887
+ }
1858
1888
  if (!Array.isArray(event.resources) || event.resources.length === 0) {
1859
1889
  deny('permission resources are missing or malformed')
1860
1890
  return
@@ -2110,7 +2140,13 @@ export const plugin = define({
2110
2140
  const boundedRead = await prepareV2BoundedRead(context).catch(() => undefined)
2111
2141
  if (boundedRead === undefined) markUnsupported('bounded-read')
2112
2142
 
2113
- // ─── Phase 2: V2 Event Subscription (best-effort) ────────────────
2143
+ // ─── Phase 2: V2 Permission Hook (best-effort) ───────────────────
2144
+ // Registered before the event subscription and session hooks so the
2145
+ // delegation matrix is enforced before any turn runs. Egress never depends
2146
+ // on this hook: the user-level config plus the host's own rules gate it.
2147
+ await registerV2PermissionHook(context, subagentOrigins).catch(() => false)
2148
+
2149
+ // ─── Phase 3: V2 Event Subscription (best-effort) ────────────────
2114
2150
  const eventCleanup = subscribeV2Events(context, boundedRead?.clearSession)
2115
2151
  if (eventCleanup) {
2116
2152
  activeCleanups.push(eventCleanup)
@@ -2118,13 +2154,13 @@ export const plugin = define({
2118
2154
  markUnsupported('event-stream')
2119
2155
  }
2120
2156
 
2121
- // ─── Phase 3: V2 Session Hooks (best-effort) ─────────────────────
2157
+ // ─── Phase 4: V2 Session Hooks (best-effort) ─────────────────────
2122
2158
  const sessionHooksRegistered = await registerV2SessionHooks(context).catch(() => false)
2123
2159
  if (!sessionHooksRegistered) {
2124
2160
  markUnsupported('session-hooks')
2125
2161
  }
2126
2162
 
2127
- // ─── Phase 4: V2 Tool Hooks (best-effort) ────────────────────────
2163
+ // ─── Phase 5: V2 Tool Hooks (best-effort) ────────────────────────
2128
2164
  const toolHookResult = await registerV2ToolHooks(
2129
2165
  context,
2130
2166
  subagentOrigins,
@@ -2134,7 +2170,7 @@ export const plugin = define({
2134
2170
  markUnsupported('tool-execute-hooks')
2135
2171
  }
2136
2172
 
2137
- // ─── Phase 5: V2 Tool Registration (best-effort) ─────────────────
2173
+ // ─── Phase 6: V2 Tool Registration (best-effort) ─────────────────
2138
2174
  const boundedReadDefinition = toolHookResult.beforeRegistered
2139
2175
  ? boundedRead?.definition
2140
2176
  : undefined
@@ -2144,9 +2180,6 @@ export const plugin = define({
2144
2180
  const toolsRegistered = await registerV2Tools(context, boundedReadDefinition).catch(() => false)
2145
2181
  if (!toolsRegistered) markUnsupported('tool-transform')
2146
2182
 
2147
- // ─── Phase 6: V2 Permission Hook (best-effort) ───────────────────
2148
- await registerV2PermissionHook(context, subagentOrigins).catch(() => false)
2149
-
2150
2183
  // ─── Phase 7: V2 Compaction Hook (best-effort) ───────────────────
2151
2184
  const compactionCtx = hostDomains(context).session
2152
2185
  if (compactionCtx?.hook) {
package/src/plugin.ts CHANGED
@@ -22,6 +22,7 @@ import { createGuardPathResolver } from './pantheon/guard-path.ts'
22
22
  import { createReadEnhancer } from './pantheon/hashline/read-enhancer.ts'
23
23
  import { createHashlineEditTool } from './pantheon/hashline/tool.ts'
24
24
  import { createIdleDispatcher } from './pantheon/idle-continuation.ts'
25
+ import { createLocalDecisionTool } from './pantheon/local-decision-tool.ts'
25
26
  import { createPantheonLogger } from './pantheon/logger.ts'
26
27
  import { createModelCommand } from './pantheon/model-command.ts'
27
28
  import { pantheonPluginOnce } from './pantheon/plugin-once.ts'
@@ -369,6 +370,7 @@ const plugin: Plugin = async (input: PluginInput) => {
369
370
  // opencode.db read-only via the single node:sqlite backend. Fully wired.
370
371
  const costCommand = createCostCommand()
371
372
  const modelCommand = createModelCommand()
373
+ const localDecisionTool = createLocalDecisionTool()
372
374
 
373
375
  return {
374
376
  config: async (config: PluginConfig) => {
@@ -436,6 +438,8 @@ const plugin: Plugin = async (input: PluginInput) => {
436
438
  pantheon_cost: costCommand.pantheon_cost,
437
439
  // Deterministic /pantheon-model management of top-level model fields.
438
440
  pantheon_model: modelCommand.pantheon_model,
441
+ // Local advisory routing; execute() requires the host's Zeus agent context.
442
+ pantheon_local_decision: localDecisionTool,
439
443
  },
440
444
  'chat.message': async (hookInput, output) => {
441
445
  await vision.chatMessage(hookInput, output)