pantheon-opencode 1.6.0 → 1.6.2-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 (115) hide show
  1. package/AGENTS.global.md +11 -11
  2. package/AGENTS.md +2 -2
  3. package/CHANGELOG.md +45 -0
  4. package/README.md +122 -6
  5. package/README.pt-BR.md +14 -9
  6. package/bin/pantheon-init.mjs +255 -39
  7. package/package.json +8 -6
  8. package/plugin.json +1 -1
  9. package/pyproject.toml +1 -1
  10. package/scripts/build-agents-md.mjs +1 -1
  11. package/scripts/doctor.mjs +231 -46
  12. package/scripts/install/agents-md.mjs +2 -1
  13. package/scripts/install/config-migration.mjs +344 -393
  14. package/scripts/install/config-paths.mjs +15 -0
  15. package/scripts/install/interactive.mjs +30 -9
  16. package/scripts/install/interrupt.mjs +78 -0
  17. package/scripts/install/mcp-permissions.mjs +164 -0
  18. package/scripts/install/opencode-state.mjs +91 -0
  19. package/scripts/install/opencode-version.mjs +31 -13
  20. package/scripts/install/opencode-wildcard.mjs +106 -0
  21. package/scripts/install/opencode.mjs +508 -108
  22. package/scripts/install/plan-artifact.mjs +12 -1
  23. package/scripts/install/plugin.mjs +17 -1
  24. package/scripts/install/run-record.mjs +115 -0
  25. package/scripts/install/strings.mjs +35 -6
  26. package/scripts/install/v2-capabilities.mjs +204 -0
  27. package/scripts/package-evidence.mjs +1 -0
  28. package/scripts/release-gates.mjs +7 -2
  29. package/scripts/sandbox-env.sh +174 -0
  30. package/scripts/setup-v2-config.mjs +1703 -0
  31. package/scripts/setup.mjs +415 -0
  32. package/scripts/sync-tui.mjs +9 -1
  33. package/scripts/test-opencode-v2-sandbox.sh +438 -151
  34. package/scripts/update-skills-lock.mjs +30 -0
  35. package/skills-lock.json +10 -10
  36. package/src/agents/aphrodite.md +5 -2
  37. package/src/agents/apollo.md +5 -0
  38. package/src/agents/athena.md +6 -1
  39. package/src/agents/demeter.md +5 -1
  40. package/src/agents/gaia.md +4 -0
  41. package/src/agents/hephaestus.md +6 -1
  42. package/src/agents/hermes.md +6 -3
  43. package/src/agents/iris.md +5 -1
  44. package/src/agents/mnemosyne.md +20 -50
  45. package/src/agents/nyx.md +5 -1
  46. package/src/agents/prometheus.md +4 -0
  47. package/src/agents/talos.md +4 -0
  48. package/src/agents/themis.md +4 -0
  49. package/src/agents/zeus.md +9 -3
  50. package/src/instructions/agent-return-format.instructions.md +1 -1
  51. package/src/instructions/memory-protocol.instructions.md +3 -3
  52. package/src/instructions/test-economy.instructions.md +6 -6
  53. package/src/mcp/pantheon_vision.py +37 -36
  54. package/src/mcp/requirements-mcp.txt +1 -1
  55. package/src/mcp/requirements-vision.txt +1 -1
  56. package/src/pantheon/cost-command.ts +127 -40
  57. package/src/pantheon/delegation-enforce.ts +160 -23
  58. package/src/pantheon/guard-path.ts +162 -0
  59. package/src/pantheon/v2-bounded-read.ts +15 -1
  60. package/src/pantheon/v2-bridge.ts +27 -0
  61. package/src/pantheon/v2-shell-hooks.ts +260 -0
  62. package/src/pantheon/v2-unsupported.mjs +32 -4
  63. package/src/pantheon/v2-vision.ts +34 -29
  64. package/src/pantheon/vision.ts +49 -11
  65. package/src/plugin-v2.ts +413 -60
  66. package/src/plugin.ts +22 -2
  67. package/src/plugins/tui/dist/quota-adapters.d.ts +89 -0
  68. package/src/plugins/tui/dist/quota-adapters.d.ts.map +1 -0
  69. package/src/plugins/tui/dist/quota-adapters.js +1142 -0
  70. package/src/plugins/tui/dist/quota-adapters.js.map +1 -0
  71. package/src/plugins/tui/dist/quota-cli.d.ts +17 -0
  72. package/src/plugins/tui/dist/quota-cli.d.ts.map +1 -0
  73. package/src/plugins/tui/dist/quota-cli.js +184 -0
  74. package/src/plugins/tui/dist/quota-cli.js.map +1 -0
  75. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js +390 -0
  76. package/src/plugins/tui/dist/quota-rpc-UL2HuFRJ.js.map +1 -0
  77. package/src/plugins/tui/dist/server-v2.d.ts +14 -0
  78. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -0
  79. package/src/plugins/tui/dist/server-v2.js +673 -0
  80. package/src/plugins/tui/dist/server-v2.js.map +1 -0
  81. package/src/plugins/tui/dist/tui-v2.d.ts +247 -52
  82. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  83. package/src/plugins/tui/dist/tui-v2.js +2492 -529
  84. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  85. package/src/plugins/tui/dist/tui.js +1 -1
  86. package/src/plugins/tui/index-v2.ts +3 -6
  87. package/src/plugins/tui/package-lock.json +11 -11
  88. package/src/plugins/tui/package.json +6 -4
  89. package/src/plugins/tui/src/context-gauge.ts +59 -0
  90. package/src/plugins/tui/src/go-key-diagnostic-ui.ts +100 -0
  91. package/src/plugins/tui/src/go-key-diagnostic.ts +125 -0
  92. package/src/plugins/tui/src/index-v2.tsx +199 -240
  93. package/src/plugins/tui/src/model-usage-limits.ts +4 -0
  94. package/src/plugins/tui/src/quota-adapters.ts +1598 -0
  95. package/src/plugins/tui/src/quota-cli.ts +237 -0
  96. package/src/plugins/tui/src/quota-rpc.ts +209 -0
  97. package/src/plugins/tui/src/quota-v2-model.ts +1032 -0
  98. package/src/plugins/tui/src/quota-v2.tsx +986 -0
  99. package/src/plugins/tui/src/server-v2.ts +841 -0
  100. package/src/plugins/tui/src/sidebar-width.ts +129 -0
  101. package/src/plugins/tui/tsconfig.typecheck.json +1 -1
  102. package/src/plugins/tui/tsdown.config.ts +8 -1
  103. package/src/routing.yml +72 -13
  104. package/src/skills/README.md +4 -0
  105. package/src/skills/agent-coordination/SKILL.md +0 -3
  106. package/src/skills/artifact-management/SKILL.md +0 -3
  107. package/src/skills/auto-continue/SKILL.md +0 -3
  108. package/src/skills/code-review-checklist/SKILL.md +0 -3
  109. package/src/skills/context-compression/SKILL.md +0 -3
  110. package/src/skills/memory-bank/SKILL.md +6 -28
  111. package/src/skills/session-goal/SKILL.md +0 -3
  112. package/src/skills/simplify/SKILL.md +5 -4
  113. package/src/skills/tdd-with-agents/SKILL.md +0 -3
  114. package/src/skills/visual-review-pipeline/SKILL.md +0 -1
  115. package/src/pantheon/memory-context.ts +0 -1017
@@ -12,15 +12,17 @@
12
12
  * scripts/install/opencode-version.mjs). Known V2 beta gaps handled here:
13
13
  * top-level `subagent_depth` is migrated to `experimental.subagent_depth`, and
14
14
  * the instruction content is consolidated into AGENTS.md, which both versions
15
- * load. Pass --version v2 to pantheon-init for an informational label; state
16
- * isolation is handled at runtime via OPENCODE_DB.
15
+ * load. Pass --version v2 to pantheon-init for an informational label.
16
+ *
17
+ * Nothing here isolates host STATE: both generations read one OpenCode store,
18
+ * and the resolver in scripts/install/opencode-state.mjs (not a literal in this
19
+ * file) is what the V2 notice reports.
17
20
  */
18
21
 
19
22
  import { createHash } from 'node:crypto'
20
- import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
23
+ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
21
24
  import { homedir } from 'node:os'
22
25
  import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
23
- import { listV2UnsupportedFeatures } from '../../src/pantheon/v2-unsupported.mjs'
24
26
  import { copyAgentPrompts, writeAgentsMdManaged } from '../build-agents-md.mjs'
25
27
  import { backupWarning, createBackupSet, previewBackupSet } from './backup.mjs'
26
28
  import {
@@ -45,10 +47,21 @@ import {
45
47
  mergeContextSandboxBlocks,
46
48
  migrateMcpEntrypointPaths,
47
49
  migrateV1toV2,
50
+ validateMcpV1toV2Source,
48
51
  } from './config-migration.mjs'
52
+ import { resolveGlobalConfigDirectory } from './config-paths.mjs'
49
53
  import { componentForInstalledPath, updateFileInventory } from './file-inventory.mjs'
50
54
  import { healthCheck } from './health-check.mjs'
55
+ import {
56
+ assertMcpGeneratedPermissionsDoNotWeakenExplicitRules,
57
+ assertMcpPermissionNamesUnambiguous,
58
+ assertMcpPermissionScopesDoNotAliasConfiguredServers,
59
+ assertMcpPermissionServerGrantsUnambiguous,
60
+ mcpPermissionAliases,
61
+ normalizeMcpPermissionSegment,
62
+ } from './mcp-permissions.mjs'
51
63
  import { detectVersion, runMigrations } from './migrate.mjs'
64
+ import { describeSharedState } from './opencode-state.mjs'
52
65
  import { DRY_RUN_PROBE_TIMEOUT_MS, resolveOpenCodeVersion } from './opencode-version.mjs'
53
66
  import {
54
67
  ACTIONS,
@@ -81,7 +94,11 @@ import {
81
94
  } from './shared.mjs'
82
95
  import { createInitialState, hasState, readState, setComponentState, writeState } from './state.mjs'
83
96
  import { strings } from './strings.mjs'
84
-
97
+ import {
98
+ describePluginOptionsReachability,
99
+ formatV2CapabilityNotice,
100
+ v2Capabilities,
101
+ } from './v2-capabilities.mjs'
85
102
  import { setupVenv, venvPythonPath } from './venv.mjs'
86
103
  import { assertNoSymlinkAncestors, assertPathWithin, assertSafeRemoval } from './verify.mjs'
87
104
 
@@ -386,9 +403,7 @@ const PANTHEON_MCP_SERVER_ENTRIES = Object.freeze([
386
403
  /** The managed server names, in write order. */
387
404
  const PANTHEON_MCP_SERVERS = Object.freeze(PANTHEON_MCP_SERVER_ENTRIES.map((entry) => entry.name))
388
405
 
389
- function normalizeMcpPermissionSegment(value) {
390
- return value.replace(/[^a-zA-Z0-9_]/g, '_')
391
- }
406
+ export { normalizeMcpPermissionSegment, PANTHEON_MCP_SERVERS }
392
407
 
393
408
  /**
394
409
  * Translate an agent's `mcp_tools` frontmatter into per-tool native
@@ -400,7 +415,7 @@ function normalizeMcpPermissionSegment(value) {
400
415
  * @param {Record<string, 'all' | string[]>} mcpTools
401
416
  * @returns {Record<string, 'allow' | 'deny'>}
402
417
  */
403
- export function deriveNativeMcpPermissions(mcpTools) {
418
+ export function deriveNativeMcpPermissions(mcpTools, configuredServers = []) {
404
419
  if (mcpTools === null || typeof mcpTools !== 'object' || Array.isArray(mcpTools)) {
405
420
  throw new TypeError('mcp_tools must be an object keyed by MCP server name')
406
421
  }
@@ -420,21 +435,36 @@ export function deriveNativeMcpPermissions(mcpTools) {
420
435
  ) {
421
436
  throw new TypeError(`mcp_tools.${server} must be "all" or an array of tool names`)
422
437
  }
438
+ }
423
439
 
424
- const serverAliases = new Set([server, normalizeMcpPermissionSegment(server)])
440
+ assertMcpPermissionNamesUnambiguous(servers)
441
+ assertMcpPermissionScopesDoNotAliasConfiguredServers(servers, configuredServers)
442
+ for (const server of servers) {
443
+ const tools = Object.hasOwn(mcpTools, server) ? mcpTools[server] : []
444
+ if (Array.isArray(tools)) assertMcpPermissionNamesUnambiguous(tools)
445
+ }
446
+ assertMcpPermissionServerGrantsUnambiguous(
447
+ [...servers].map((server) => ({
448
+ server,
449
+ tools: Object.hasOwn(mcpTools, server) ? mcpTools[server] : [],
450
+ })),
451
+ )
452
+
453
+ for (const server of servers) {
454
+ const serverAliases = mcpPermissionAliases(server)
425
455
  for (const alias of serverAliases) permissions[`${alias}_*`] = 'deny'
426
456
  }
427
457
 
428
458
  for (const server of servers) {
429
459
  const tools = Object.hasOwn(mcpTools, server) ? mcpTools[server] : []
430
- const serverAliases = new Set([server, normalizeMcpPermissionSegment(server)])
460
+ const serverAliases = mcpPermissionAliases(server)
431
461
  if (tools === 'all') {
432
462
  for (const alias of serverAliases) permissions[`${alias}_*`] = 'allow'
433
463
  continue
434
464
  }
435
465
 
436
466
  for (const tool of tools) {
437
- const toolAliases = new Set([tool, normalizeMcpPermissionSegment(tool)])
467
+ const toolAliases = mcpPermissionAliases(tool)
438
468
  for (const serverAlias of serverAliases) {
439
469
  for (const toolAlias of toolAliases) {
440
470
  permissions[`${serverAlias}_${toolAlias}`] = 'allow'
@@ -446,10 +476,58 @@ export function deriveNativeMcpPermissions(mcpTools) {
446
476
  return permissions
447
477
  }
448
478
 
479
+ /** Merge generated MCP grants only when they do not weaken explicit agent policy. */
480
+ export function mergeAgentMcpPermissions(explicit, mcpTools, configuredServers = []) {
481
+ const generated = deriveNativeMcpPermissions(mcpTools, configuredServers)
482
+ assertMcpGeneratedPermissionsDoNotWeakenExplicitRules(explicit, generated)
483
+ return { ...(explicit ?? {}), ...generated }
484
+ }
485
+
486
+ /** Build a fail-closed skill allowlist from an agent's canonical `skills` list. */
487
+ export function deriveNativeSkillPermissions(skills) {
488
+ if (!Array.isArray(skills)) {
489
+ throw new TypeError('agent skills must be an array of skill IDs')
490
+ }
491
+
492
+ const permissions = { '*': 'deny' }
493
+ const seen = new Set()
494
+ for (const skill of skills) {
495
+ if (typeof skill !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill)) {
496
+ throw new TypeError(`agent skill ID is invalid: ${String(skill)}`)
497
+ }
498
+ if (seen.has(skill)) throw new TypeError(`agent skill list contains duplicate skill: ${skill}`)
499
+ seen.add(skill)
500
+ permissions[skill] = 'allow'
501
+ }
502
+ return permissions
503
+ }
504
+
505
+ /**
506
+ * Add the canonical skill allowlist to one agent's permission map. An explicit
507
+ * skill policy in canonical frontmatter would make last-match precedence
508
+ * ambiguous, so require that policy to be expressed through `skills:` instead.
509
+ */
510
+ export function mergeAgentSkillPermissions(explicit, skills) {
511
+ if (explicit?.skill !== undefined) {
512
+ throw new TypeError('agent skill access must be declared only through the skills list')
513
+ }
514
+ return { ...(explicit ?? {}), skill: deriveNativeSkillPermissions(skills) }
515
+ }
516
+
449
517
  function deepClone(value) {
450
518
  return JSON.parse(JSON.stringify(value))
451
519
  }
452
520
 
521
+ function configuredMcpServerNames(mcpConfig) {
522
+ if (mcpConfig === null || typeof mcpConfig !== 'object' || Array.isArray(mcpConfig)) return []
523
+ const { hasV2ServersMap, legacyServersToggle } = validateMcpV1toV2Source(mcpConfig)
524
+ return Object.entries(mcpConfig).flatMap(([name, value]) => {
525
+ if (hasV2ServersMap && name === 'servers') return Object.keys(value)
526
+ if (legacyServersToggle && name === 'servers') return []
527
+ return [name]
528
+ })
529
+ }
530
+
453
531
  /**
454
532
  * (Re)generate the code-mode manifest with SHA-256 digests for every bundled
455
533
  * script, and write it to the destination. This is the explicit installation
@@ -573,6 +651,78 @@ function normalizePluginRef(ref) {
573
651
  return typeof ref === 'string' ? ref.replaceAll('\\', '/').replace(/\/$/, '') : ref
574
652
  }
575
653
 
654
+ /**
655
+ * Whether a path-ish plugin ref is a filesystem path rather than a package spec.
656
+ *
657
+ * The V2 loader treats anything that is not an obvious path as an npm/GitHub
658
+ * spec and runs `npm install` on it — including `a/b`, which it reads as a
659
+ * GitHub repository and fails on (`NpmInstallFailedError`). A relative path is
660
+ * always spelled with `./` or `../`, so that spelling is the discriminator.
661
+ *
662
+ * @param {string} value
663
+ * @returns {boolean}
664
+ */
665
+ function looksLikePluginPath(value) {
666
+ if (value.startsWith('.') || value.startsWith('/') || value.startsWith('~')) return true
667
+ return /^[A-Za-z]:[\\/]/.test(value)
668
+ }
669
+
670
+ /**
671
+ * Whether the OpenCode V2 loader can load a `plugins` entry EXACTLY as written.
672
+ *
673
+ * This is the gate for the V1→V2 migration: the V1 singular `plugin` list is
674
+ * ignored by the V2 host, but moving an entry there into `plugins` only helps
675
+ * when the loader accepts it. The loader's contract (documented on
676
+ * PANTHEON_V2_PLUGIN and proven by sandbox probes) is:
677
+ * - a DIRECTORY containing a real index.ts/index.js loads;
678
+ * - a file path is rejected ("must be a directory");
679
+ * - a package shorthand is resolved through `npm install` and dies with
680
+ * NpmInstallFailedError.
681
+ * Migrating a file path or a shorthand would therefore convert "silently
682
+ * ignored" into "config fails to load", which is worse than leaving it alone.
683
+ *
684
+ * @param {unknown} entry the `plugins`/`plugin` entry
685
+ * @param {string} configDir the config directory the loader resolves against
686
+ * @returns {{ loadable: boolean, reason: 'directory'|'file'|'missing'|'npm-spec'|'unverifiable', resolved: string|null }}
687
+ */
688
+ export function v2PluginEntryLoadability(entry, configDir) {
689
+ if (typeof entry !== 'string' || entry.trim() === '') {
690
+ return { loadable: false, reason: 'unverifiable', resolved: null }
691
+ }
692
+ const value = entry.trim()
693
+ if (!looksLikePluginPath(value)) {
694
+ return { loadable: false, reason: 'npm-spec', resolved: null }
695
+ }
696
+ const resolved = isAbsolute(value) ? value : resolve(configDir, value)
697
+ if (!existsSync(resolved)) {
698
+ return { loadable: false, reason: 'missing', resolved }
699
+ }
700
+ try {
701
+ if (!statSync(resolved).isDirectory()) {
702
+ return { loadable: false, reason: 'file', resolved }
703
+ }
704
+ } catch {
705
+ return { loadable: false, reason: 'missing', resolved }
706
+ }
707
+ return { loadable: true, reason: 'directory', resolved }
708
+ }
709
+
710
+ /** Human explanation of a non-loadable entry, naming the exact failure mode. */
711
+ const V2_LOAD_FAILURES = {
712
+ 'npm-spec':
713
+ 'is a package/GitHub shorthand, which the V2 loader resolves through `npm install` and fails on (NpmInstallFailedError)',
714
+ file: 'is a file, and the V2 loader only accepts a directory containing index.ts ("must be a directory")',
715
+ missing:
716
+ 'does not exist, and the V2 loader only accepts an existing directory containing index.ts',
717
+ unverifiable:
718
+ 'is not a path this installer can verify, so it was left untouched rather than guessed at',
719
+ }
720
+
721
+ /** Render a plugin entry for a warning without ever printing a bare object. */
722
+ function describePluginEntry(entry) {
723
+ return typeof entry === 'string' ? entry : JSON.stringify(entry)
724
+ }
725
+
576
726
  const PANTHEON_V1_PLUGIN = 'src/plugin.ts'
577
727
  const PANTHEON_V1_HOOKS = 'src/plugins/pantheon-hooks.ts'
578
728
  // Canonical V2 entry is the plugin DIRECTORY (beta loader contract: entries
@@ -703,6 +853,35 @@ export function deduplicatePluginReferences(refs) {
703
853
  })
704
854
  }
705
855
 
856
+ /**
857
+ * Register the copied Pantheon TUI plugin in the V2 `plugins` list.
858
+ *
859
+ * The OpenCode 2.x host does not load server-side RPC from a local plugin
860
+ * folder by free discovery — only entries listed in `config.plugins` are
861
+ * loaded (sandbox probe evidence: no entry → `rpc.unavailable`; with the
862
+ * entry the host logs `loading plugin id=…/pantheon-tui` and the V2-only
863
+ * RPC (`pantheon.quota`) answers HTTP 200). Without this registration a
864
+ * postinstall/sync that re-copies the payload after `init` can never restore
865
+ * it, so the quota status stays "unavailable".
866
+ *
867
+ * Idempotent: the existing entry for the copy (same identity) is retained
868
+ * and kept after the core plugin, while every other entry stays in place.
869
+ * Gated on the copy existing so an install without the plugins component does
870
+ * not register a dangling path.
871
+ *
872
+ * @param {{ plugins?: unknown }} config - the config object about to be written (mutated)
873
+ * @param {{ tuiCopyDir: string }} opts - absolute path of the copied plugin directory
874
+ */
875
+ export function ensureTuiCopyRegistered(config, { tuiCopyDir }) {
876
+ if (!Array.isArray(config.plugins)) config.plugins = []
877
+ if (!existsSync(tuiCopyDir)) return
878
+
879
+ const identity = pluginReferenceIdentity(tuiCopyDir)
880
+ const existing = config.plugins.find((entry) => pluginReferenceIdentity(entry) === identity)
881
+ config.plugins = config.plugins.filter((entry) => pluginReferenceIdentity(entry) !== identity)
882
+ config.plugins.push(existing ?? tuiCopyDir)
883
+ }
884
+
706
885
  /**
707
886
  * Duplicate the V1 top-level `context_sandbox` block into the exact Pantheon V2
708
887
  * plugin entry's `options`, converting a plain-string entry into the
@@ -798,8 +977,9 @@ export function isGlobalConfigDir(target) {
798
977
  *
799
978
  * <configDir>/plugins/pantheon-tui (tui.ts + dist/ + package manifests)
800
979
  *
801
- * V1 registers that copy through tui.json. V2 discovers the local plugin's
802
- * index.ts + tui.ts pair; the V2 shim re-exports dist/tui-v2.js.
980
+ * V1 registers that copy through tui.json. V2 loads the copy only through the
981
+ * `plugins` entry (see ensureTuiCopyRegistered); the V2 shim re-exports
982
+ * dist/tui-v2.js.
803
983
  *
804
984
  * @param {string} configDir - OpenCode config directory (target for global
805
985
  * installs, <target>/.opencode for project installs)
@@ -1070,8 +1250,9 @@ export function applyContextSidebarNegation(
1070
1250
  }
1071
1251
 
1072
1252
  /**
1073
- * Sync the Pantheon TUI plugin payload and V1 registration. V2 discovers the
1074
- * copied local-plugin entrypoints and does not use a project tui.json.
1253
+ * Sync the Pantheon TUI plugin payload and V1 registration. V2 does not use a
1254
+ * project tui.json; it loads the copy's server ONLY through the config
1255
+ * `plugins` entry written by ensureTuiCopyRegistered().
1075
1256
  *
1076
1257
  * Contract (single source of truth):
1077
1258
  * 1. ALWAYS copy src/plugins/tui → <configDir>/plugins/pantheon-tui with the
@@ -1082,8 +1263,9 @@ export function applyContextSidebarNegation(
1082
1263
  * paths, in-package src/plugins/tui dirs, bare plugins/pantheon-tui
1083
1264
  * copies, and npx paths. A stale ref left in the non-target location
1084
1265
  * would still be loaded and break the TUI.
1085
- * 3. V1 registers the copied directory in the selected target. V2 relies on
1086
- * local-plugin discovery and does not write a project tui.json entry.
1266
+ * 3. V1 registers the copied directory in the selected target. V2 does not
1267
+ * write a project tui.json entry; its `plugins` registration is written
1268
+ * by the config merge (ensureTuiCopyRegistered).
1087
1269
  *
1088
1270
  * @param {string} target - install target directory
1089
1271
  * @param {object} [opts]
@@ -1146,9 +1328,10 @@ export function syncTuiRegistration(
1146
1328
  })
1147
1329
  }
1148
1330
 
1149
- // OpenCode V2 discovers local plugins from the config plugins directories;
1150
- // its TUI plugin API is exposed by the sibling tui.ts entrypoint. V1 still
1151
- // requires the explicit tui.json registration.
1331
+ // The V2 host loads the copy's server-side RPC only from the config
1332
+ // `plugins` list — ensureTuiCopyRegistered writes that entry during the
1333
+ // config merge, so no tui.json is written here. V1 still requires the
1334
+ // explicit tui.json registration.
1152
1335
  if (version === 'v2') return 'skipped'
1153
1336
 
1154
1337
  // 3. Register the copied directory in the selected target only.
@@ -1259,63 +1442,80 @@ export function setupRuntimePhase(
1259
1442
  * order) — the dry-run preview reports exactly these
1260
1443
  */
1261
1444
  export function applyMcpServerEntries(config, { runtimeTarget, venvPython, version = 'v2' }) {
1262
- config.mcp = config.mcp || {}
1263
- // MCP stays a flat named-server map for BOTH V1 and V2: OpenCode 1.18.x has
1264
- // no `mcp.servers` wrapper and rejects one with "Missing key
1265
- // mcp.servers.enabled". config-migration.mjs normalizes any legacy
1266
- // wrapper-shaped entries back to the flat map.
1267
- const healed = migrateMcpEntrypointPaths(config.mcp)
1445
+ if (version === 'v2') {
1446
+ if (Object.hasOwn(config, 'mcp')) validateMcpV1toV2Source(config.mcp)
1447
+ else config.mcp = {}
1448
+ } else {
1449
+ config.mcp = config.mcp || {}
1450
+ }
1451
+ let serverMap = config.mcp
1452
+ if (version === 'v2') {
1453
+ const { hasV2ServersMap, legacyServersToggle } = validateMcpV1toV2Source(config.mcp)
1454
+ const existingServers = config.mcp.servers
1455
+ if (hasV2ServersMap) {
1456
+ serverMap = existingServers
1457
+ } else {
1458
+ serverMap = { ...config.mcp }
1459
+ if (legacyServersToggle) delete serverMap.servers
1460
+ config.mcp = { servers: serverMap }
1461
+ }
1462
+ }
1463
+ const healed = migrateMcpEntrypointPaths(serverMap)
1268
1464
 
1269
1465
  // Only add if not already configured by user.
1270
1466
  const servers = []
1271
1467
  for (const entry of PANTHEON_MCP_SERVER_ENTRIES) {
1272
- if (config.mcp[entry.name]) continue
1273
- config.mcp[entry.name] = {
1468
+ if (serverMap[entry.name]) continue
1469
+ serverMap[entry.name] = {
1274
1470
  type: 'local',
1275
1471
  cwd: runtimeTarget,
1276
1472
  command: [venvPython, entry.script],
1277
- enabled: true,
1473
+ ...(version === 'v1' ? { enabled: true } : {}),
1278
1474
  }
1279
1475
  servers.push(entry.name)
1280
1476
  }
1281
1477
 
1282
- // Default MCP permissions.
1478
+ // V1 compatibility defaults. V2 setup converts user `ask` entries only after
1479
+ // explicit review; the inert legacy defaults are not seeded into V2 configs.
1283
1480
  //
1284
- // WARNING: on OpenCode 2.x, `permission.mcp.<server>` is NOT enforced. The
1285
- // host evaluates an MCP call as the action `<server>_<tool>` with resources
1286
- // ["*"]; `permission.mcp.<server>` and `action:"mcp"` are inert (measured on
1287
- // 2.0.29–2.1.3). These defaults are kept for V1 compatibility, but `ask` does
1288
- // not prompt and `allow` grants nothing it did not already have — every `ask`
1289
- // server below is reported to the user as unenforced. The enforceable form is
1290
- // `{ action: "<server>_*", resource: "*", effect: "deny" }`; `ask` there
1291
- // HIDES the tool instead of asking, so it is never emitted as a default.
1292
- config.permission = config.permission || {}
1293
- config.permission.mcp = config.permission.mcp || {}
1294
- if (!config.permission.mcp['pantheon-resources']) {
1295
- config.permission.mcp['pantheon-resources'] = 'allow'
1296
- }
1297
- if (!config.permission.mcp['pantheon-code-mode']) {
1298
- config.permission.mcp['pantheon-code-mode'] = 'ask'
1299
- }
1300
- if (!config.permission.mcp['pantheon-memory']) {
1301
- config.permission.mcp['pantheon-memory'] = 'allow'
1302
- }
1303
- if (!config.permission.mcp['pantheon-persistence']) {
1304
- config.permission.mcp['pantheon-persistence'] = 'allow'
1305
- }
1306
- if (!config.permission.mcp['pantheon-vision']) {
1307
- config.permission.mcp['pantheon-vision'] = 'ask'
1481
+ // Legacy defaults remain V1-only. V2 requires explicit native permissions;
1482
+ // absent a rule, MCP servers remain accessible without a prompt.
1483
+ if (version === 'v1') {
1484
+ config.permission = config.permission || {}
1485
+ config.permission.mcp = config.permission.mcp || {}
1486
+ if (!config.permission.mcp['pantheon-resources']) {
1487
+ config.permission.mcp['pantheon-resources'] = 'allow'
1488
+ }
1489
+ if (!config.permission.mcp['pantheon-code-mode']) {
1490
+ config.permission.mcp['pantheon-code-mode'] = 'ask'
1491
+ }
1492
+ if (!config.permission.mcp['pantheon-memory']) {
1493
+ config.permission.mcp['pantheon-memory'] = 'allow'
1494
+ }
1495
+ if (!config.permission.mcp['pantheon-persistence']) {
1496
+ config.permission.mcp['pantheon-persistence'] = 'allow'
1497
+ }
1498
+ if (!config.permission.mcp['pantheon-vision']) {
1499
+ config.permission.mcp['pantheon-vision'] = 'ask'
1500
+ }
1308
1501
  }
1309
1502
 
1310
1503
  // Report every `ask` entry, whether just seeded or left by a previous
1311
1504
  // install: the config claims a gate the host does not apply. V1's MCP
1312
1505
  // permission semantics were not measured, so the warning is V2-only.
1313
- const S = strings()
1506
+ const askCount = Object.values(config.permission?.mcp ?? {}).filter(
1507
+ (effect) => effect === 'ask',
1508
+ ).length
1314
1509
  const warnings =
1315
1510
  version === 'v2'
1316
- ? Object.entries(config.permission.mcp)
1317
- .filter(([, effect]) => effect === 'ask')
1318
- .map(([server]) => S.mcpAskNotEnforceable(server))
1511
+ ? [
1512
+ ...(askCount > 0
1513
+ ? [
1514
+ `${askCount} legacy MCP ask rule(s) cannot be enforced; run setup for an explicit policy choice.`,
1515
+ ]
1516
+ : []),
1517
+ 'V2 Pantheon MCP servers without an explicit permission rule remain accessible without a prompt.',
1518
+ ]
1319
1519
  : []
1320
1520
 
1321
1521
  return { healed, warnings, servers }
@@ -1411,9 +1611,13 @@ async function installPass(
1411
1611
  components = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime'],
1412
1612
  opts = {},
1413
1613
  ) {
1614
+ if (opts.configPreview !== undefined && opts.configPreview !== null && !dryRun) {
1615
+ throw new Error('A setup config preview is accepted only during a dry run.')
1616
+ }
1617
+
1414
1618
  // Default target if not provided (global ~/.config/opencode)
1415
1619
  if (!target) {
1416
- target = join(homedir(), '.config', 'opencode')
1620
+ target = resolveGlobalConfigDirectory(process.env)
1417
1621
  }
1418
1622
 
1419
1623
  const componentSet = new Set(
@@ -1471,9 +1675,10 @@ async function installPass(
1471
1675
 
1472
1676
  // V1/V2 dual-version awareness (Phase 3): the installer builds a unified
1473
1677
  // config, then applies V2-native migration (migrateV1toV2) when
1474
- // --opencode-version=v2. V2 normalizes V1 fields in memory (no rewrite) and
1475
- // isolates its state DB via OPENCODE_DB (~/.local/share/opencode/opencode-v2.db)
1476
- // with a distinct service port (49375 vs V1's 49374).
1678
+ // --opencode-version=v2. V2 normalizes V1 fields in memory (no rewrite).
1679
+ // Neither generation isolates state: both read the same OpenCode store, so
1680
+ // the V2 notice reports the path an actual resolver returns instead of a
1681
+ // literal, and claims no service port because nothing binds one.
1477
1682
  // Default to 'auto' so a flagless run resolves against the actual host. A
1478
1683
  // hardcoded 'v1' here (or in bin/pantheon-init.mjs) is what shipped the bug:
1479
1684
  // the V1 branch writes .ts file paths that a 2.x host drops from the config.
@@ -1503,25 +1708,30 @@ async function installPass(
1503
1708
  )
1504
1709
  }
1505
1710
  const versionAssumed = dryRun && versionFallback !== null
1506
- if (version === 'v2') {
1507
- notice(
1508
- 'OpenCode V2 target — shared config; state isolated via OPENCODE_DB ' +
1509
- '(~/.local/share/opencode/opencode-v2.db), service port 49375',
1510
- )
1511
- // Say what the V2 contract does NOT give you, at the moment the user picks
1512
- // it. The V2 surface is 3 tools (hashline_edit, pantheon_cost,
1513
- // pantheon_model); V1's is 6 plus the BackgroundJobBoard, the three goal
1514
- // tools and the caller/target delegation matrix. This list was previously
1515
- // reachable only through `getUnsupportedFeatures()`, which no production
1516
- // code called — a user migrating hit the reduction with no warning at all.
1517
- //
1518
- // The markers are read from the same seed `getUnsupportedFeatures()` is
1519
- // built from (src/pantheon/v2-unsupported.mjs), so this notice cannot drift
1520
- // from what the plugin reports. Advisory: a V2 install is a supported
1521
- // configuration, not a failure.
1522
- notice(
1523
- `V2 plugin generation — reduced surface. Unsupported features: ${listV2UnsupportedFeatures().join(', ')}`,
1524
- )
1711
+ // Both V2 notices belong to the run the USER started, not to the internal
1712
+ // plan pass the gate spawns. That pass runs with the same output channel, so
1713
+ // an ungated notice printed twice on the unauthorized-preview path (`init`
1714
+ // without --yes: plan pass, then the outer apply pass, both loud). The
1715
+ // sibling `warning()` for a sibling opencode.jsonc is gated the same way;
1716
+ // a real --dry-run is not a plan pass, so it still prints them once.
1717
+ if (version === 'v2' && !opts.planOnly) {
1718
+ // The notice states only what this installer actually does and what the
1719
+ // host actually reads. It previously claimed an isolated state database and
1720
+ // a dedicated service port: nothing in this package sets OPENCODE_DB, no
1721
+ // install creates a per-generation file, nothing binds that port, and the
1722
+ // repo's own database consumer documents the opposite
1723
+ // (src/pantheon/cost-command.ts). The path below comes from the shared
1724
+ // resolver, so the sentence cannot drift from the code.
1725
+ notice(`OpenCode V2 target — ${describeSharedState()}`)
1726
+ // Say what the V2 contract gives you AND what it does not, at the moment
1727
+ // the user picks it. "Reduced surface" alone is misleading in both
1728
+ // directions: V2 registers real hooks, transforms and events, and it also
1729
+ // drops the goal tools. The not-registered half is the same SEED
1730
+ // `getUnsupportedFeatures()` is built from (imported, never restated), so
1731
+ // this notice cannot drift from what the plugin reports; the notice says
1732
+ // so, because the live list is a superset that grows at runtime. Advisory:
1733
+ // a V2 install is a supported configuration, not a failure.
1734
+ notice(formatV2CapabilityNotice())
1525
1735
  }
1526
1736
 
1527
1737
  // Interactive mode handling
@@ -1548,14 +1758,40 @@ async function installPass(
1548
1758
  isTTY: opts.deps?.isTTY,
1549
1759
  })
1550
1760
 
1761
+ // Resolve the location from the SELECTION before any cancel return: a
1762
+ // cancel after the user picked "Current project" must record that
1763
+ // directory, not the global default the caller would fall back to. The
1764
+ // recorded target is where the user was installing, not where a file was
1765
+ // written (nothing was written either way).
1766
+ const selectedTarget = result.target === 'project' ? process.cwd() : target
1767
+
1551
1768
  if (result.canceled) {
1552
- notice('Installation canceled.')
1553
- return { ...stats, applied: false, reason: 'canceled' }
1769
+ // The named point is what makes the message explainable. The interactive
1770
+ // module already printed the single cancel line through the prompt
1771
+ // library's own cancel channel, so printing another one here was the
1772
+ // duplicate the issue reports: the user saw the same sentence twice and
1773
+ // learned nothing about WHERE it stopped.
1774
+ return {
1775
+ ...stats,
1776
+ applied: false,
1777
+ reason: 'canceled',
1778
+ cancelPoint: result.cancelPoint ?? 'components',
1779
+ target: selectedTarget,
1780
+ }
1554
1781
  }
1555
1782
 
1556
1783
  if (!result.confirmed) {
1557
- notice('Installation canceled.')
1558
- return { ...stats, applied: false, reason: 'canceled' }
1784
+ // Answering "No" at the pre-install confirmation is not the prompt
1785
+ // library's cancel channel, so nothing was printed yet: this is the one
1786
+ // message, and it names the point.
1787
+ notice(S.canceledAt(S.cancelPoints.confirmation))
1788
+ return {
1789
+ ...stats,
1790
+ applied: false,
1791
+ reason: 'canceled',
1792
+ cancelPoint: 'confirmation',
1793
+ target: selectedTarget,
1794
+ }
1559
1795
  }
1560
1796
 
1561
1797
  // Map target selection to actual path
@@ -1565,9 +1801,7 @@ async function installPass(
1565
1801
  componentSet.clear()
1566
1802
  for (const c of newComponents) componentSet.add(c)
1567
1803
 
1568
- if (result.target === 'project') {
1569
- target = process.cwd()
1570
- }
1804
+ target = selectedTarget
1571
1805
  }
1572
1806
 
1573
1807
  // Product defaults live in code (PRODUCT_CONFIG_DEFAULTS). A repository-root
@@ -1583,7 +1817,43 @@ async function installPass(
1583
1817
  const pantheonConfigPath =
1584
1818
  typeof mergeDevConfigOpt === 'string' ? resolve(mergeDevConfigOpt) : null
1585
1819
  const targetConfigPath = join(target, 'opencode.json')
1586
- const { config, raw: configRaw } = readJsonConfigWithRaw(targetConfigPath)
1820
+ // The installer reads and writes ONLY `opencode.json`, but the V2 host also
1821
+ // loads a sibling `opencode.jsonc` and unions arrays from both. A Pantheon
1822
+ // entry there is invisible to this installer, so a "second config" is a real
1823
+ // ambiguity the user has to resolve — name it instead of leaving the two
1824
+ // files to disagree silently.
1825
+ const siblingJsonc = join(target, 'opencode.jsonc')
1826
+ const configAdvisories = []
1827
+ if (version === 'v2' && existsSync(siblingJsonc)) {
1828
+ configAdvisories.push(
1829
+ `Both ${targetConfigPath} and ${siblingJsonc} exist and an OpenCode V2 host merges ` +
1830
+ 'them (scalars from the .jsonc win, arrays are unioned). The installer reads and ' +
1831
+ 'writes only opencode.json, so anything plugin-related in the .jsonc — including a ' +
1832
+ 'Pantheon entry — is neither seen nor changed by this install. Move those entries ' +
1833
+ 'into opencode.json and delete the .jsonc, or edit both by hand.',
1834
+ )
1835
+ // The internal plan pass is not a user-facing report; the apply pass (and a
1836
+ // real --dry-run) prints it once.
1837
+ if (!opts.planOnly) warning(configAdvisories[0])
1838
+ }
1839
+ const { config: diskConfig, raw: configRaw } = readJsonConfigWithRaw(targetConfigPath)
1840
+ let config = diskConfig
1841
+ if (opts.configPreview !== undefined && opts.configPreview !== null) {
1842
+ try {
1843
+ config = JSON.parse(opts.configPreview)
1844
+ if (config === null || typeof config !== 'object' || Array.isArray(config)) {
1845
+ throw new Error('not an object')
1846
+ }
1847
+ } catch {
1848
+ throw new Error('The setup config preview input is invalid.')
1849
+ }
1850
+ }
1851
+ // Validate the original MCP shape before runtime entries can be seeded or a
1852
+ // flat map can be wrapped. Seeding first can turn malformed nested input into
1853
+ // an apparently valid wrapper and let migration silently discard user data.
1854
+ if (version === 'v2' && Object.hasOwn(config, 'mcp')) {
1855
+ validateMcpV1toV2Source(config.mcp)
1856
+ }
1587
1857
  const pantheonConfig =
1588
1858
  pantheonConfigPath !== null && existsSync(pantheonConfigPath)
1589
1859
  ? readJsonConfig(pantheonConfigPath)
@@ -1652,6 +1922,16 @@ async function installPass(
1652
1922
  target,
1653
1923
  packageRoot: ROOT,
1654
1924
  packageVersion,
1925
+ options: {
1926
+ clean,
1927
+ components: [...components],
1928
+ version,
1929
+ isProject: opts.isProject === true,
1930
+ model: opts.model ?? null,
1931
+ smallModel: opts.smallModel ?? null,
1932
+ preset: opts.preset ?? null,
1933
+ mergeDevConfig: mergeDevConfigOpt,
1934
+ },
1655
1935
  files: planned?.files ?? [],
1656
1936
  snapshots: planned?.snapshots ?? [],
1657
1937
  })
@@ -1674,12 +1954,19 @@ async function installPass(
1674
1954
  isTTY: opts.deps?.isTTY,
1675
1955
  })
1676
1956
  if (accepted === PROMPT_CANCELED) {
1677
- notice(S.nothingApplied)
1678
- return { ...stats, applied: false, reason: 'canceled' }
1957
+ // The real prompt already printed the one cancel line through clack's
1958
+ // own cancel channel. An INJECTED reviewer (tests, other callers)
1959
+ // prints nothing, so this is the single place that guarantees the
1960
+ // message exists exactly once, and it names the point.
1961
+ if (typeof injected === 'function') notice(S.canceledAt(S.cancelPoints.review))
1962
+ return { ...stats, applied: false, reason: 'canceled', cancelPoint: 'review' }
1679
1963
  }
1680
1964
  if (!accepted) {
1681
- notice(S.nothingApplied)
1682
- return { ...stats, applied: false, reason: 'declined' }
1965
+ // Answering "No" is not a cancel: it used to reach the caller as a
1966
+ // silent `reason: 'declined'` and exit 0 with "Nothing applied." and
1967
+ // no explanation at all.
1968
+ notice(S.declinedAt(S.cancelPoints.review))
1969
+ return { ...stats, applied: false, reason: 'declined', cancelPoint: 'review' }
1683
1970
  }
1684
1971
  } else {
1685
1972
  notice(S.planOnlyNoYes)
@@ -2272,11 +2559,15 @@ async function installPass(
2272
2559
  if (fm.permission) {
2273
2560
  agent.permission = JSON.parse(JSON.stringify(fm.permission))
2274
2561
  }
2562
+ if (fm.skills !== undefined) {
2563
+ agent.permission = mergeAgentSkillPermissions(agent.permission, fm.skills)
2564
+ }
2275
2565
  if (fm.mcp_tools !== undefined) {
2276
- agent.permission = {
2277
- ...(agent.permission ?? {}),
2278
- ...deriveNativeMcpPermissions(fm.mcp_tools),
2279
- }
2566
+ agent.permission = mergeAgentMcpPermissions(
2567
+ agent.permission,
2568
+ fm.mcp_tools,
2569
+ configuredMcpServersForPolicies,
2570
+ )
2280
2571
  }
2281
2572
 
2282
2573
  config[name] = agent
@@ -2284,6 +2575,8 @@ async function installPass(
2284
2575
  return config
2285
2576
  }
2286
2577
 
2578
+ const configuredMcpServersForPolicies =
2579
+ version === 'v2' ? configuredMcpServerNames(config.mcp) : []
2287
2580
  const canonicalAgentConfig = readAgentConfigFromCanonical()
2288
2581
  const agentSources = getAgentSources(agentPrefix)
2289
2582
 
@@ -2433,11 +2726,55 @@ async function installPass(
2433
2726
  }
2434
2727
 
2435
2728
  if (version === 'v2') {
2436
- // V2 loads the plural `plugins` list. Keep third-party V1 entries in the
2437
- // legacy list for users who still use them, but never leave a Pantheon V1
2438
- // entry configured alongside the V2 package export.
2729
+ // V2 loads the plural `plugins` list, and the singular `plugin` key is dead
2730
+ // on this host. Migrating a V1 config therefore means deciding, entry by
2731
+ // entry, whether the V2 loader can load it AT ALL: a directory can, a file
2732
+ // path is rejected ("must be a directory") and a package shorthand dies in
2733
+ // `npm install`. Copying every entry across would turn "silently ignored"
2734
+ // into "config fails to load", so only loadable entries move; the rest stay
2735
+ // where they are and the warning names the exact failure mode.
2439
2736
  if (Array.isArray(config.plugin)) {
2737
+ // Strip Pantheon refs FIRST, exactly as the V1 branch does: a stale V1
2738
+ // .ts path is not a registrable entry on this host and must not be moved.
2440
2739
  config.plugin = removePantheonPluginReferences(config.plugin)
2740
+ if (!Array.isArray(config.plugins)) config.plugins = []
2741
+ const migrated = []
2742
+ const blocked = []
2743
+ for (const plugin of config.plugin) {
2744
+ const verdict = v2PluginEntryLoadability(plugin, target)
2745
+ if (!verdict.loadable) {
2746
+ blocked.push({ plugin, reason: verdict.reason })
2747
+ continue
2748
+ }
2749
+ if (!hasPluginReference(config.plugins, plugin)) {
2750
+ config.plugins.push(deepClone(plugin))
2751
+ migrated.push(plugin)
2752
+ }
2753
+ }
2754
+ if (migrated.length > 0) {
2755
+ warning(
2756
+ `V2 host ignores the singular "plugin" key; also registered ${migrated.length} ` +
2757
+ `third-party entr${migrated.length === 1 ? 'y' : 'ies'} under "plugins" so ` +
2758
+ `they keep loading: ${migrated.map(describePluginEntry).join(', ')}. ` +
2759
+ 'Remove any that only support the V1 plugin API.',
2760
+ )
2761
+ }
2762
+ if (blocked.length > 0) {
2763
+ warning(
2764
+ 'V2 host ignores the singular "plugin" key; these entries were left in it ' +
2765
+ `because the V2 loader cannot load them, so they will NOT be active: ${blocked
2766
+ .map(
2767
+ ({ plugin, reason }) =>
2768
+ `${describePluginEntry(plugin)} ${V2_LOAD_FAILURES[reason]}`,
2769
+ )
2770
+ .join('; ')}.`,
2771
+ )
2772
+ }
2773
+ // Pantheon refs are already gone. An emptied array is not configuration:
2774
+ // drop the dead key entirely so the written config points at the list the
2775
+ // V2 host actually reads. A surviving V1 list is the user's own data and
2776
+ // is left in place (a downgrade still finds it).
2777
+ if (config.plugin.length === 0) delete config.plugin
2441
2778
  }
2442
2779
  if (!Array.isArray(config.plugins)) config.plugins = []
2443
2780
  // Preserve any options already set on the Pantheon V2 entry across the
@@ -2476,11 +2813,54 @@ async function installPass(
2476
2813
  config.plugins = config.plugins.filter(
2477
2814
  (plugin) => pluginReferenceIdentity(plugin) !== pluginReferenceIdentity(resolvedV2),
2478
2815
  )
2479
- config.plugins.push(
2480
- existingV2Options === null
2481
- ? resolvedV2
2482
- : { package: resolvedV2, options: deepClone(existingV2Options) },
2816
+ // Always use object form, even on a fresh install. The host passes plugin
2817
+ // options only from `{ package, options }`, and `context_pruner` reads
2818
+ // `ctx.options`. A bare string left the option unreachable; an empty object
2819
+ // keeps the contract visible and preserves user-added keys on re-run.
2820
+ config.plugins.push({
2821
+ package: resolvedV2,
2822
+ options: existingV2Options === null ? {} : deepClone(existingV2Options),
2823
+ })
2824
+
2825
+ // See ensureTuiCopyRegistered: OpenCode 2.x loads server-side RPC of the
2826
+ // copied TUI plugin ONLY through an explicit `plugins` entry.
2827
+ ensureTuiCopyRegistered(config, {
2828
+ tuiCopyDir: isGlobal
2829
+ ? join(target, 'plugins', 'pantheon-tui')
2830
+ : join(target, '.opencode', 'plugins', 'pantheon-tui'),
2831
+ })
2832
+
2833
+ // A path that LOOKS like a Pantheon V2 entry but is not one this package
2834
+ // can prove it owns (managedPluginIdentity only recognizes installed copies
2835
+ // and this package's own paths) would now be registered twice: the host
2836
+ // would run both copies' hooks. Retiring it on a guess could delete a
2837
+ // third-party plugin, so say what is happening instead of guessing.
2838
+ const lookalikes = config.plugins.filter(
2839
+ (ref) =>
2840
+ !isPantheonPluginReference(ref) &&
2841
+ pluginMetadataReferences(ref).some((reference) =>
2842
+ /(^|\/)plugin-v2(?:\.ts)?$/.test(normalizePluginRef(reference)),
2843
+ ),
2483
2844
  )
2845
+ if (lookalikes.length > 0) {
2846
+ warning(
2847
+ 'This config also points at another copy of the Pantheon V2 plugin, which this ' +
2848
+ 'installer cannot prove it owns: ' +
2849
+ `${lookalikes.map(describePluginEntry).join(', ')}. With the entry registered in ` +
2850
+ 'this install, BOTH copies would load and their hooks would run twice. Remove that ' +
2851
+ 'entry by hand if it is an older Pantheon installation; it is left alone because a ' +
2852
+ 'third-party plugin could share the path.',
2853
+ )
2854
+ }
2855
+ }
2856
+
2857
+ // Report whether the entry the host will read can actually carry options.
2858
+ // Computed here, from the config this pass is about to write, so it answers
2859
+ // the installed state rather than an assumption.
2860
+ const v2PluginOptions =
2861
+ version === 'v2' ? describePluginOptionsReachability(config.plugins) : null
2862
+ if (v2PluginOptions !== null && !v2PluginOptions.reachable && !opts.planOnly) {
2863
+ warning(`Pantheon V2 plugin options are not reachable: ${v2PluginOptions.detail}`)
2484
2864
  }
2485
2865
 
2486
2866
  if (pantheonConfig !== null) {
@@ -2500,6 +2880,10 @@ async function installPass(
2500
2880
  // --------------------------------------------------------------------
2501
2881
  // C. Merge permissions
2502
2882
  // --------------------------------------------------------------------
2883
+ // A native V2 array is an explicit policy, including an empty one. Do not
2884
+ // append legacy defaults to it: reruns would duplicate rules, and custom V2
2885
+ // configs would gain grants the user did not choose.
2886
+ const hasNativeV2Permissions = version === 'v2' && Array.isArray(config.permissions)
2503
2887
  if (config.permission === undefined) config.permission = {}
2504
2888
  if (
2505
2889
  typeof config.permission === 'object' &&
@@ -2519,7 +2903,11 @@ async function installPass(
2519
2903
  // must not seed the key. It used to anyway, via the unconditional
2520
2904
  // PRODUCT_CONFIG_DEFAULTS.permission merge that sat above this block —
2521
2905
  // which also made this gate dead code.
2522
- if (componentSet.has('skills') && config.permission.skill === undefined) {
2906
+ if (
2907
+ componentSet.has('skills') &&
2908
+ config.permission.skill === undefined &&
2909
+ !hasNativeV2Permissions
2910
+ ) {
2523
2911
  config.permission.skill = { '*': 'allow' }
2524
2912
  }
2525
2913
  // These five are the commands Pantheon's OWN agents must be able to run
@@ -2545,7 +2933,7 @@ async function installPass(
2545
2933
  // NOTE: this grant is NOT gated on the skills component — unlike
2546
2934
  // permission.skill above, agents are installed by the agents component and
2547
2935
  // the test/lint commands are needed whichever components were selected.
2548
- if (config.permission.bash === undefined) {
2936
+ if (config.permission.bash === undefined && !hasNativeV2Permissions) {
2549
2937
  config.permission.bash = {
2550
2938
  'git *': 'allow',
2551
2939
  'npm *': 'allow',
@@ -2989,6 +3377,18 @@ async function installPass(
2989
3377
  target,
2990
3378
  openCodeVersion: version,
2991
3379
  versionAssumed,
3380
+ configAdvisories,
3381
+ v2Capabilities: version === 'v2' ? v2Capabilities() : null,
3382
+ pluginOptions: v2PluginOptions,
3383
+ }
3384
+ : {
3385
+ ...stats,
3386
+ applied: true,
3387
+ reason: 'applied',
3388
+ target,
3389
+ openCodeVersion: version,
3390
+ configAdvisories,
3391
+ v2Capabilities: version === 'v2' ? v2Capabilities() : null,
3392
+ pluginOptions: v2PluginOptions,
2992
3393
  }
2993
- : { ...stats, applied: true, reason: 'applied' }
2994
3394
  }