arkgate 3.8.2 → 3.9.0

package/bin/lib/skill-install.mjs

@@ -8,18 +8,28 @@ import { arkCommand } from '../ark-shared.mjs';
 import { codexPromptsDir, codexSkillsDir } from './codex-home.mjs';
 import { __packageRoot, isCompactRouterAgentsContent, readJson } from './gate-files.mjs';
 
+/** Alias map so --tools agy installs the antigravity profile. */
+const TOOL_ALIASES = Object.freeze({
+  agy: 'antigravity',
+});
+
+function normalizeToolId(value) {
+  const id = String(value).trim().toLowerCase();
+  return TOOL_ALIASES[id] ?? id;
+}
+
 export function normalizeToolsList(tools) {
   if (tools == null) return [];
   if (Array.isArray(tools)) {
     return tools
       .flatMap((t) => String(t).split(','))
-      .map((t) => t.trim().toLowerCase())
+      .map(normalizeToolId)
       .filter(Boolean);
   }
   if (typeof tools === 'string') {
     return tools
       .split(',')
-      .map((t) => t.trim().toLowerCase())
+      .map(normalizeToolId)
       .filter(Boolean);
   }
   return [];
@@ -77,6 +87,25 @@ export function detectActiveAgentHost(env = process.env) {
   ) {
     return 'codex';
   }
+  // Google Antigravity / agy CLI
+  if (
+    envTruthy(env.ANTIGRAVITY) ||
+    envTruthy(env.AGY) ||
+    env.ANTIGRAVITY_WORKSPACE ||
+    env.AGY_WORKSPACE ||
+    /antigravity/i.test(String(env.TERM_PROGRAM ?? ''))
+  ) {
+    return 'antigravity';
+  }
+  // OpenCode
+  if (
+    envTruthy(env.OPENCODE) ||
+    env.OPENCODE_SESSION_ID ||
+    env.OPENCODE_CONFIG ||
+    envTruthy(env.OPENCODE_CLI)
+  ) {
+    return 'opencode';
+  }
   return null;
 }
 
@@ -101,6 +130,15 @@ export function resolveTools(args) {
   if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
   if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
   if (fs.existsSync(path.join(root, '.grok'))) detected.add('grok');
+  // Antigravity project hooks (distinct from Codex-only `.agents/skills`).
+  if (fs.existsSync(path.join(root, '.agents', 'hooks.json'))) detected.add('antigravity');
+  if (
+    fs.existsSync(path.join(root, 'opencode.json')) ||
+    fs.existsSync(path.join(root, 'opencode.jsonc')) ||
+    fs.existsSync(path.join(root, '.opencode'))
+  ) {
+    detected.add('opencode');
+  }
   if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
   // .clinerules can also be a single FILE (older Cline convention); only a directory
   // can receive .clinerules/ark.md, so a file must not trigger detection.
@@ -136,6 +174,8 @@ export const KNOWN_TOOLS = [
   'cursor',
   'codex',
   'grok',
+  'antigravity',
+  'opencode',
   'windsurf',
   'cline',
   'copilot',
@@ -161,6 +201,10 @@ export const SKILL_TOOL_TARGETS = {
   codex: (name) => `.agents/skills/${name}/SKILL.md`,
   // Grok Build: project skills at .grok/skills/<name>/SKILL.md (slash-invocable).
   grok: (name) => `.grok/skills/${name}/SKILL.md`,
+  // Antigravity loads Agent Skills from `.agents/skills` (shared path with Codex).
+  antigravity: (name) => `.agents/skills/${name}/SKILL.md`,
+  // OpenCode project skills under `.opencode/skills`.
+  opencode: (name) => `.opencode/skills/${name}/SKILL.md`,
   windsurf: (name) => `.windsurf/workflows/${name}.md`,
   cline: (name) => `.clinerules/workflows/${name}.md`,
   copilot: (name) => `.github/prompts/${name}.prompt.md`,

package/bin/lib/start-preview.mjs

@@ -5,7 +5,14 @@ import os from 'node:os';
 import path from 'node:path';
 import { arkCommand, buildArchitectureRecommendation } from '../ark-shared.mjs';
 import { compactAgentInstructions, instructionRule, mcpJson } from './ci-and-commands.mjs';
-import { claudeSettings, codexHooks, grokHooks, grokProjectConfig } from './hook-templates.mjs';
+import {
+  antigravityHooks,
+  claudeSettings,
+  codexHooks,
+  grokHooks,
+  grokProjectConfig,
+  opencodeProjectConfig,
+} from './hook-templates.mjs';
 
 const COMPACT_HOST_TEMPLATES = {
   claude: (root) => [
@@ -16,8 +23,13 @@ const COMPACT_HOST_TEMPLATES = {
     ['.grok/config.toml', grokProjectConfig(root)],
     ['.grok/hooks/ark-write-gate.json', grokHooks(root)],
   ],
+  antigravity: (root) => [
+    ['.agents/hooks.json', antigravityHooks(root)],
+    ['.mcp.json', mcpJson(root)],
+  ],
   cursor: (root) => [['.cursor/mcp.json', mcpJson(root)]],
   codex: (root) => [['.codex/hooks.json', codexHooks(root)]],
+  opencode: (root) => [['opencode.json', opencodeProjectConfig(root)]],
   windsurf: (root) => [['.windsurf/rules/ark.md', instructionRule(root)]],
   cline: (root) => [['.clinerules/ark.md', instructionRule(root)]],
   copilot: (root) => [['.github/copilot-instructions.md', instructionRule(root)]],
@@ -70,12 +82,14 @@ function setupBudget(changes) {
     (total, item) => total + (item.afterBase64 ? Buffer.from(item.afterBase64, 'base64').length : 0),
     0
   );
+  // Compact start includes shared MCP + one host registration + CI + AGENTS + config.
+  // Budget raised from 5→8 so .mcp.json always fits (field: grok compact hit the old ceiling).
   return {
     files: generatedChanges.length,
     bytes,
-    maxFiles: 5,
-    maxBytes: 25 * 1024,
-    ok: generatedChanges.length <= 5 && bytes < 25 * 1024,
+    maxFiles: 8,
+    maxBytes: 32 * 1024,
+    ok: generatedChanges.length <= 8 && bytes < 32 * 1024,
   };
 }
 
@@ -84,7 +98,8 @@ function commands(root, args, helpers) {
     return [`ark start --root ${root} --tools ${args.removeHost} --apply`];
   }
   const result = [];
-  if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
+  // Default install=true: surface the package pin/install command unless --no-install.
+  if (args.install !== false && fs.existsSync(path.join(root, 'package.json'))) {
     const [command, commandArgs] = helpers.packageInstallArgv(root, `^${helpers.cliVersion()}`);
     result.push(`${command} ${commandArgs.join(' ')}`);
   }
@@ -216,8 +231,9 @@ export async function planStart(args, helpers) {
     if (args.yes) childArgs.push('--yes');
     if (args.force) childArgs.push('--force');
     if (!args.strict) childArgs.push('--no-strict');
-    if (args.installExplicit && args.install) childArgs.push('--install');
-    if (args.installExplicit && !args.install) childArgs.push('--no-install');
+    // Propagate install intent into the shadow plan so package.json pin is in the diff by default.
+    if (args.install === false) childArgs.push('--no-install');
+    else childArgs.push('--install');
     if (args.tools) childArgs.push('--tools', args.tools);
     if (args.requireWriteHook) childArgs.push('--require-write-hook', args.requireWriteHook);
     const planned = spawnSync(process.execPath, [helpers.cliPath, ...childArgs], {

package/bin/lib/upgrade-command.mjs

@@ -55,23 +55,50 @@ function verify(root, json, arkCheck, runArkCheck) {
 export function runUpgradeCommand(args, dependencies) {
   const root = args.root;
   if (args.apply && args.install) {
-    const [command, commandArgs] = dependencies.packageInstallArgv(root);
-    if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
-    const install = spawnSync(command, commandArgs, {
-      cwd: root,
-      stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-      encoding: 'utf8',
-    });
-    const exitCode = install.status ?? 1;
-    if (exitCode !== 0) {
-      if (args.json && install.stderr) console.error(install.stderr.trim());
+    const skip =
+      typeof dependencies.shouldSkipArkgateInstall === 'function'
+        ? dependencies.shouldSkipArkgateInstall(root, dependencies.cliVersion)
+        : { skip: false };
+    if (skip.skip) {
+      if (!args.json) {
+        console.log(
+          `Package already at arkgate@${skip.installedVersion}; skipping install and recomputing managed preview.`
+        );
+      }
+    } else {
+      const [command, commandArgs] = dependencies.packageInstallArgv(root);
+      if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
+      const install = spawnSync(command, commandArgs, {
+        cwd: root,
+        stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        encoding: 'utf8',
+      });
+      const exitCode = install.status ?? 1;
+      if (exitCode !== 0) {
+        if (args.json && install.stderr) console.error(install.stderr.trim());
+        const recovery = `${command} ${commandArgs.join(' ')}`;
+        console.error(
+          `Package update failed (exit ${exitCode}). Fix the install and re-run:\n` +
+            `  ${recovery}\n` +
+            `Then: ark upgrade --no-install --root ${JSON.stringify(root)}` +
+            (args.tools ? ` --tools ${args.tools}` : '') +
+            (!args.strict ? ' --no-strict' : '') +
+            (args.json ? ' --json' : '')
+        );
+        return exitCode;
+      }
+    }
+    // Re-enter via installed CLI so the managed plan uses the newly installed package bytes.
+    let cli;
+    try {
+      cli = installedCli(root);
+    } catch {
       console.error(
-        `Package update failed (exit ${exitCode}). Fix the install and re-run, or use ` +
-          '`ark upgrade --no-install` against the installed version.'
+        'arkgate is not installed in this project after the package step. Install it, then re-run with --no-install.'
       );
-      return exitCode;
+      return 1;
     }
-    return spawnSync(process.execPath, [installedCli(root), ...previewArgs(args)], {
+    return spawnSync(process.execPath, [cli, ...previewArgs(args)], {
       cwd: root,
       stdio: 'inherit',
       encoding: 'utf8',
@@ -111,7 +138,14 @@ export function runUpgradeCommand(args, dependencies) {
     return 0;
   }
 
-  const applied = applyManagedUpgrade(root, plan, args.planDigest);
+  let applied;
+  try {
+    applied = applyManagedUpgrade(root, plan, args.planDigest);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    return 2;
+  }
   if (applied.blocked) {
     if (args.json) console.log(JSON.stringify(applied, null, 2));
     else renderManagedUpgrade(applied, {
@@ -119,6 +153,14 @@ export function runUpgradeCommand(args, dependencies) {
     });
     return 1;
   }
+  if (applied.nothingToApply && !applied.applied) {
+    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    else {
+      renderManagedUpgrade(applied);
+      console.log('No managed content writes pending (optional stamp refresh needs --plan-digest).');
+    }
+    return 0;
+  }
   const verification = args.strict
     ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
     : { mode: 'skipped', exitCode: 0 };

package/bin/lib/write-path-capabilities.mjs

@@ -194,9 +194,11 @@ function commandArkMcpInvocation(command) {
 }
 
 function requiredWriteOperations(relativePath) {
-  return relativePath.startsWith('.grok/')
-    ? ['write', 'search_replace']
-    : ['Write', 'Edit', 'MultiEdit'];
+  if (relativePath.startsWith('.grok/')) return ['write', 'search_replace'];
+  if (relativePath === '.agents/hooks.json' || relativePath.startsWith('.agents/')) {
+    return ['write_to_file', 'replace_file_content', 'multi_replace_file_content'];
+  }
+  return ['Write', 'Edit', 'MultiEdit'];
 }
 
 function matcherOperations(relativePath, matcher) {
@@ -248,25 +250,39 @@ function tomlArkMcpIsValid(text) {
   return primary.length === 1 && tomlMcpBlockIsValid(primary[0].block);
 }
 
+function collectPreToolUseGroups(parsed) {
+  // Claude/Grok/Codex: { hooks: { PreToolUse: [...] } }
+  if (Array.isArray(parsed?.hooks?.PreToolUse)) return parsed.hooks.PreToolUse;
+  // Antigravity: { "named-hook": { PreToolUse: [...] }, ... }
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    const groups = [];
+    for (const value of Object.values(parsed)) {
+      if (value && typeof value === 'object' && Array.isArray(value.PreToolUse)) {
+        groups.push(...value.PreToolUse);
+      }
+    }
+    return groups;
+  }
+  return [];
+}
+
 function hookEvidence(root, relativePath) {
   const text = readText(path.join(root, relativePath));
   let hooks = [];
   try {
-    const groups = JSON.parse(text)?.hooks?.PreToolUse;
-    if (Array.isArray(groups)) {
-      hooks = groups.flatMap((group) =>
-        Array.isArray(group?.hooks)
-          ? group.hooks
-              .filter((hook) => !hook?.type || hook.type === 'command')
-              .map((hook) => ({
-                hook,
-                invocation: commandArkMcpInvocation(hook?.command),
-                operations: matcherOperations(relativePath, group.matcher),
-              }))
-              .filter((entry) => entry.invocation)
-          : []
-      );
-    }
+    const groups = collectPreToolUseGroups(JSON.parse(text));
+    hooks = groups.flatMap((group) =>
+      Array.isArray(group?.hooks)
+        ? group.hooks
+            .filter((hook) => !hook?.type || hook.type === 'command')
+            .map((hook) => ({
+              hook,
+              invocation: commandArkMcpInvocation(hook?.command),
+              operations: matcherOperations(relativePath, group.matcher),
+            }))
+            .filter((entry) => entry.invocation)
+        : []
+    );
   } catch {
     hooks = [];
   }
@@ -290,6 +306,29 @@ function hookEvidence(root, relativePath) {
   };
 }
 
+/** OpenCode local MCP: `{ mcp: { ark: { type: "local", command: [...] } } }`. */
+function opencodeMcpIsValid(text) {
+  try {
+    const server = JSON.parse(text)?.mcp?.ark;
+    if (!server || typeof server !== 'object') return false;
+    if (server.type != null && server.type !== 'local') return false;
+    if (!Array.isArray(server.command) || server.command.length === 0) return false;
+    if (!server.command.every((value) => typeof value === 'string')) return false;
+    const [command, ...args] = server.command;
+    return mcpServerRunsArk({ command, args });
+  } catch {
+    return false;
+  }
+}
+
+function opencodeMcpEvidence(root) {
+  for (const relativePath of ['opencode.json', 'opencode.jsonc']) {
+    const text = readText(path.join(root, relativePath));
+    if (text && opencodeMcpIsValid(text)) return [relativePath];
+  }
+  return [];
+}
+
 function mcpEvidence(root, relativePath) {
   const text = readText(path.join(root, relativePath));
   const valid = relativePath.endsWith('.toml')
@@ -338,6 +377,7 @@ export function detectWritePathInventory(root) {
   const merge = ci.failClosed ? ci.arkWorkflowFiles : [];
   const claudeHook = hookEvidence(root, '.claude/settings.json');
   const grokHook = hookEvidence(root, '.grok/hooks/ark-write-gate.json');
+  const antigravityHook = hookEvidence(root, '.agents/hooks.json');
   const hosts = {
     claude: hostRecord(
       claudeHook.hard,
@@ -351,12 +391,21 @@ export function detectWritePathInventory(root) {
       grokHook.repair,
       merge
     ),
+    antigravity: hostRecord(
+      antigravityHook.hard,
+      // Shared project MCP (.mcp.json) is the common advisory surface; hooks own hard write.
+      mcpEvidence(root, '.mcp.json'),
+      antigravityHook.repair,
+      merge
+    ),
     cursor: hostRecord([], mcpEvidence(root, '.cursor/mcp.json'), [], merge),
     // Codex 0.123+ emits PreToolUse for the native apply_patch handler, but some
     // Code Mode hosts execute deferred nested writes without dispatching that
     // project hook. Keep the installed hook as best-effort protection; do not
     // report a hard boundary that cannot be verified for every write surface.
     codex: hostRecord([], codexMcpEvidence(root), [], merge),
+    // OpenCode: MCP only (plugin hooks are incomplete / subagent-bypassable).
+    opencode: hostRecord([], opencodeMcpEvidence(root), [], merge),
   };
 
   const evidence = emptyEvidence();

package/bin/lib/write-path-detect.mjs

@@ -11,7 +11,7 @@ import { buildWritePathCapabilityModel } from './write-path-capabilities.mjs';
 
 function installToolsForHost(activeHost) {
   return activeHost === 'unknown'
-    ? 'claude,grok,cursor,codex'
+    ? 'claude,grok,antigravity,cursor,codex,opencode'
     : activeHost;
 }
 
@@ -109,22 +109,26 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
       ),
     };
   } else if (mode === 'mcp-only') {
-    const codexHonesty =
+    const honesty =
       activeHost === 'codex'
         ? 'Codex local write is advisory (MCP + best-effort hooks.json — not a hard boundary; ' +
           'not equivalent to Claude/Grok PreToolUse hard-write + repair). ' +
           'The hard merge backstop is CI --strict-merge plus a required status check.'
-        : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
-          'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
+        : activeHost === 'opencode'
+          ? 'OpenCode local write is advisory (MCP + optional experimental plugin — not a hard boundary; ' +
+            'not equivalent to Claude/Grok/Antigravity PreToolUse hard-write). ' +
+            'The hard merge backstop is CI --strict-merge plus a required status check.'
+          : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
+            'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
     gap = {
       id: 'write-path-mcp-only',
       severity: 'info',
       host: activeHost,
-      message: codexHonesty,
+      message: honesty,
       fix:
-        activeHost === 'codex'
+        activeHost === 'codex' || activeHost === 'opencode'
           ? 'Keep CI on --strict-merge and require the ark-check status on the default branch; ' +
-            `refresh Codex MCP/skills with ${arkCommand(root, 'ark-check', '--install-agent-gates --tools codex')}`
+            `refresh ${activeHost} MCP/skills with ${arkCommand(root, 'ark-check', `--install-agent-gates --tools ${activeHost}`)}`
           : arkCommand(root, 'ark-check', `--install-agent-gates --tools ${tools}`),
     };
   }