@rune-kit/rune 2.28.0 → 2.29.1

package/compiler/adapters/codex.js

@@ -21,18 +21,21 @@
  * Codex GPT-5.6 tiers (verified against codex-cli 0.144.1 + developers.openai.com/codex/models):
  *   sol  = flagship/complex → opus
  *   terra = balanced everyday → sonnet
- *   luna = fast/affordable → haiku
+ *   terra at low effort = fast/affordable → haiku
  * Codex also exposes `model_reasoning_effort = minimal|low|medium|high|xhigh`
  * (a config.toml key, not per-skill frontmatter) — Rune surfaces the tier→effort
  * suggestion in AGENTS.md rather than emitting a speculative per-skill field.
  */
 
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
 const MODEL_MAP = {
   opus: 'gpt-5.6-sol',
   sonnet: 'gpt-5.6-terra',
-  haiku: 'gpt-5.6-luna',
+  haiku: 'gpt-5.6-terra',
 };
 
 // Suggested config.toml `model_reasoning_effort` per tier (global key, documented in AGENTS.md).
@@ -78,8 +81,6 @@ export default {
   generateHeader(skill) {
     const desc = (skill.description || '').replace(/"/g, '\\"');
     const lines = ['---', `name: rune-${skill.name}`, `description: "${desc}"`];
-    const translatedModel = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
-    if (translatedModel) lines.push(`model: ${translatedModel}`);
     lines.push('---', '', '');
     return lines.join('\n');
   },
@@ -102,25 +103,27 @@ export default {
 
   // Codex (and OpenAI's AGENTS.md convention generally) reads AGENTS.md at the
   // project root for high-level context. Migrated from emitter.js v2.18.
-  generateExtraFiles({ stats }) {
-    const agentsMd = [
+  async generateExtraFiles({ stats, outputRoot }) {
+    const runeBlock = [
+      '<!-- rune:codex:start -->',
       '# Rune — Project Configuration',
       '',
       '## Overview',
       '',
       'Rune is an interconnected skill ecosystem for AI coding assistants.',
-      `${stats.skillCount} core skills | 5-layer mesh architecture | ${stats.crossRefsResolved} connections | Multi-platform.`,
+      `${stats.coreSkillCount ?? stats.skillCount} core skills${stats.tierSkillCount ? ` + ${stats.tierSkillCount} tier skills` : ''} | 5-layer mesh architecture | ${stats.crossRefsResolved} connections | Multi-platform.`,
       'Philosophy: "Less skills. Deeper connections."',
       '',
       'Platform: codex',
       '',
       '## Skills',
       '',
-      `**${stats.skillCount} core skills** + **${stats.packCount} extension packs**`,
+      `**${stats.coreSkillCount ?? stats.skillCount} core skills**${stats.tierSkillCount ? ` + **${stats.tierSkillCount} tier skills**` : ''} + **${stats.packCount} extension packs**`,
       '',
       '## Usage',
       '',
-      'Reference skills using the `Skill` tool or delegate to subagents using the `Agent` tool.',
+      'Mention a skill as `$rune-<name>` or let Codex activate it from the task description.',
+      'When an applicable Rune skill requests delegation, Codex may run bounded subagents in parallel.',
       '',
       '## Skills Directory',
       '',
@@ -134,12 +137,86 @@ export default {
       `- sonnet → \`${MODEL_MAP.sonnet}\` (\`model_reasoning_effort = "${REASONING_EFFORT_MAP.sonnet}"\`) — code / edit / review`,
       `- haiku → \`${MODEL_MAP.haiku}\` (\`model_reasoning_effort = "${REASONING_EFFORT_MAP.haiku}"\`) — scan / read-only`,
       '',
-      'Set `model` + `model_reasoning_effort` in `~/.codex/config.toml` to match the tier of the task.',
+      'Generated project-scoped roles live in `.codex/agents/` so spawned agents can apply these settings natively.',
       '',
       '---',
       '> Rune Skill Mesh — https://github.com/rune-kit/rune',
+      '<!-- rune:codex:end -->',
       '',
     ].join('\n');
-    return [{ path: 'AGENTS.md', content: agentsMd }];
+
+    const agentsMd = await mergeAgentsMd(outputRoot, runeBlock);
+    return [
+      { path: 'AGENTS.md', content: agentsMd },
+      {
+        path: '.codex/agents/rune-heavy.toml',
+        content: renderAgentRole({
+          name: 'rune_heavy',
+          description: 'Rune worker for architecture, security, planning, and other high-complexity tasks.',
+          model: MODEL_MAP.opus,
+          effort: REASONING_EFFORT_MAP.opus,
+          instructions:
+            'Follow the applicable Rune skill exactly. Prioritize correctness, explicit assumptions, impact analysis, and complete verification.',
+        }),
+      },
+      {
+        path: '.codex/agents/rune-standard.toml',
+        content: renderAgentRole({
+          name: 'rune_standard',
+          description: 'Rune worker for implementation, debugging, review, and everyday engineering tasks.',
+          model: MODEL_MAP.sonnet,
+          effort: REASONING_EFFORT_MAP.sonnet,
+          instructions:
+            'Follow the applicable Rune skill exactly. Keep changes scoped, preserve user work, and verify behavior before reporting completion.',
+        }),
+      },
+      {
+        path: '.codex/agents/rune-fast.toml',
+        content: renderAgentRole({
+          name: 'rune_fast',
+          description: 'Read-heavy Rune worker for scouting, dependency checks, and focused evidence gathering.',
+          model: MODEL_MAP.haiku,
+          effort: REASONING_EFFORT_MAP.haiku,
+          instructions:
+            'Stay read-only unless the parent explicitly requests edits. Return concise evidence with file and line references.',
+        }),
+      },
+    ];
   },
 };
+
+const RUNE_AGENTS_START = '<!-- rune:codex:start -->';
+const RUNE_AGENTS_END = '<!-- rune:codex:end -->';
+
+async function mergeAgentsMd(outputRoot, runeBlock) {
+  if (!outputRoot) return runeBlock;
+
+  const agentsPath = path.join(outputRoot, 'AGENTS.md');
+  if (!existsSync(agentsPath)) return runeBlock;
+
+  const existing = await readFile(agentsPath, 'utf-8');
+  const start = existing.indexOf(RUNE_AGENTS_START);
+  const end = existing.indexOf(RUNE_AGENTS_END);
+  if (start !== -1 && end > start) {
+    const after = end + RUNE_AGENTS_END.length;
+    return `${existing.slice(0, start)}${runeBlock}${existing.slice(after)}`;
+  }
+
+  // Migrate files produced by Rune versions before managed markers existed.
+  if (existing.trimStart().startsWith('# Rune — Project Configuration')) return runeBlock;
+
+  return `${existing.trimEnd()}\n\n${runeBlock}`;
+}
+
+function renderAgentRole({ name, description, model, effort, instructions }) {
+  return [
+    `name = "${name}"`,
+    `description = "${description}"`,
+    `model = "${model}"`,
+    `model_reasoning_effort = "${effort}"`,
+    'developer_instructions = """',
+    instructions,
+    '"""',
+    '',
+  ].join('\n');
+}

package/compiler/adapters/hooks/codex.js

@@ -0,0 +1,178 @@
+/**
+ * OpenAI Codex hooks adapter.
+ *
+ * Target: `.codex/hooks.json` — Codex-native lifecycle hooks. Codex currently
+ * skips handlers marked `async`, so Rune emits every command synchronously and
+ * relies on the preset's `--gentle` flag for warn-only behavior.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  appendHookBlock,
+  detectPreset,
+  stripHooksBySkill,
+  stripRuneHooks,
+  summarizeRuneHooks,
+} from '../../commands/hooks/merge.js';
+import { buildPreset, WIRED_SKILLS } from '../../commands/hooks/presets.js';
+
+export const id = 'codex';
+export const HOOKS_REL_PATH = '.codex/hooks.json';
+
+const RUNE_DESCRIPTION = 'Rune lifecycle hooks for OpenAI Codex.';
+
+export function detect(projectRoot) {
+  return existsSync(path.join(projectRoot, '.codex'));
+}
+
+export async function emit({ preset, projectRoot, tierManifests = [] }) {
+  if (preset === 'off' && tierManifests.length === 0) return uninstall({ projectRoot });
+  if (preset !== 'off' && preset !== 'strict' && preset !== 'gentle') {
+    throw new Error(`codex adapter: invalid preset '${preset}'`);
+  }
+
+  const hooksPath = path.join(projectRoot, HOOKS_REL_PATH);
+  const existing = await readJson(hooksPath);
+  let merged = stripRuneHooks(existing);
+  const notes = [
+    'Codex requires review/trust for new or changed project hooks. Open `/hooks` after installation.',
+    'Codex does not execute async command hooks; Rune emitted synchronous handlers with preset-controlled behavior.',
+  ];
+
+  if (!merged.description) merged.description = RUNE_DESCRIPTION;
+  if (preset !== 'off') {
+    merged = appendHookBlock(merged, normalizeBlock(buildPreset(preset)));
+  }
+
+  for (const manifest of tierManifests) {
+    const overrideKeys = Object.keys(manifest.overrides || {});
+    if (overrideKeys.length > 0) merged = stripHooksBySkill(merged, overrideKeys);
+
+    const tierBlock = buildCodexTierBlock(manifest);
+    if (Object.keys(tierBlock.hooks).length > 0) {
+      merged = appendHookBlock(merged, tierBlock);
+    }
+    if (tierBlock.skipped.length > 0) {
+      notes.push(`${manifest.tier}: skipped Codex-unsupported entries (${tierBlock.skipped.join(', ')}).`);
+    }
+  }
+
+  return {
+    files: [{ path: hooksPath, content: `${JSON.stringify(merged, null, 2)}\n` }],
+    notes,
+  };
+}
+
+export async function uninstall({ projectRoot }) {
+  const hooksPath = path.join(projectRoot, HOOKS_REL_PATH);
+  if (!existsSync(hooksPath)) {
+    return { files: [], notes: ['no .codex/hooks.json — nothing to uninstall'] };
+  }
+
+  const existing = await readJson(hooksPath);
+  const stripped = stripRuneHooks(existing);
+  const keys = Object.keys(stripped);
+  const isRuneOnlyShell = keys.length === 1 && keys[0] === 'description' && stripped.description === RUNE_DESCRIPTION;
+
+  return {
+    files: [{ path: hooksPath, content: isRuneOnlyShell ? null : `${JSON.stringify(stripped, null, 2)}\n` }],
+    notes: [],
+  };
+}
+
+export async function status(projectRoot) {
+  const hooksPath = path.join(projectRoot, HOOKS_REL_PATH);
+  if (!existsSync(hooksPath)) {
+    return {
+      installed: false,
+      preset: null,
+      wired: [],
+      missing: [...WIRED_SKILLS],
+      notes: ['no .codex/hooks.json'],
+    };
+  }
+
+  const settings = await readJson(hooksPath);
+  const summary = summarizeRuneHooks(settings);
+  const preset = detectPreset(settings);
+  const wired = Array.from(new Set(Object.values(summary.events).flat()));
+  return {
+    installed: summary.total > 0,
+    preset: preset === 'none' ? null : preset,
+    wired,
+    missing: WIRED_SKILLS.filter((skill) => !wired.includes(skill)),
+    events: summary.events,
+    notes: ['Use `/hooks` in Codex to inspect the current trust state.'],
+  };
+}
+
+function normalizeBlock(block) {
+  const hooks = {};
+  for (const [event, groups] of Object.entries(block.hooks || {})) {
+    hooks[event] = groups.map((group) => {
+      const normalized = {
+        ...group,
+        hooks: group.hooks.map(normalizeCommand),
+      };
+      if (event === 'UserPromptSubmit' || event === 'Stop') delete normalized.matcher;
+      return normalized;
+    });
+  }
+  return { hooks };
+}
+
+function normalizeCommand(entry) {
+  const { async: _unsupported, ...normalized } = entry;
+  const commandWindows = toWindowsCommand(normalized.command);
+  if (commandWindows !== normalized.command) normalized.commandWindows = commandWindows;
+  return normalized;
+}
+
+function buildCodexTierBlock(manifest) {
+  const hooks = {};
+  const skipped = [];
+
+  for (const entry of manifest.entries) {
+    if (entry.event === 'statusLine' || entry.claudeOnly || entry.platforms?.codex === 'unsupported') {
+      skipped.push(entry.id || entry.skill);
+      continue;
+    }
+
+    const event = entry.event;
+    const matcher = entry.matcher || '.*';
+    if (!hooks[event]) hooks[event] = [];
+    let group = hooks[event].find((candidate) => candidate.matcher === matcher);
+    if (!group) {
+      group = { matcher, hooks: [] };
+      hooks[event].push(group);
+    }
+    group.hooks.push(
+      normalizeCommand({
+        type: 'command',
+        command: entry.command,
+      }),
+    );
+  }
+
+  return { ...normalizeBlock({ hooks }), skipped };
+}
+
+function toWindowsCommand(command) {
+  if (typeof command !== 'string') return command;
+  return command.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, '%$1%');
+}
+
+async function readJson(hooksPath) {
+  if (!existsSync(hooksPath)) return {};
+  const raw = await readFile(hooksPath, 'utf-8');
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${hooksPath} is not valid JSON — fix it manually or delete the file and re-run \`rune hooks install --platform codex\`. (${err.message})`,
+    );
+  }
+}

package/compiler/adapters/hooks/index.js

@@ -15,11 +15,13 @@
 
 import * as antigravity from './antigravity.js';
 import * as claude from './claude.js';
+import * as codex from './codex.js';
 import * as cursor from './cursor.js';
 import * as windsurf from './windsurf.js';
 
 export const ADAPTERS = Object.freeze({
   claude,
+  codex,
   cursor,
   windsurf,
   antigravity,
@@ -55,6 +57,14 @@ export const CAPABILITIES = Object.freeze({
     stop: true,
     notes: 'Full hook parity — PreToolUse/PostToolUse/Stop all supported.',
   },
+  codex: {
+    maturity: 'stable',
+    preToolEdit: true,
+    preToolBash: true,
+    postToolEdit: true,
+    stop: true,
+    notes: 'Native hooks via `.codex/hooks.json`; operator trust is required before first execution.',
+  },
   cursor: {
     maturity: 'beta',
     preToolEdit: 'rule-injection',

package/compiler/adapters/openclaw.js

@@ -105,7 +105,7 @@ export default {
       id: 'rune',
       name: 'Rune',
       kind: 'skills',
-      description: `${skills.length}-skill mesh for AI coding assistants. Routes all code tasks through specialized skills. 203 sync connections + 40 async signals, 14 extension packs.`,
+      description: `${skills.length}-skill mesh for AI coding assistants. Routes all code tasks through specialized skills. 248 sync connections + 45 async signals, 14 extension packs.`,
       version: pluginJson.version || '0.0.0',
       skills: ['./skills'],
       artifactConvention: {
@@ -170,7 +170,7 @@ export default {
 
 > Less skills. Deeper connections.
 
-**${skills.length}-skill mesh** for AI coding assistants — 5-layer architecture, 215+ connections, 14 extension packs.
+**${skills.length}-skill mesh** for AI coding assistants — 5-layer architecture, 248 connections + 45 signals, 14 extension packs.
 
 ## Install
 

package/compiler/bin/rune.js

@@ -25,6 +25,7 @@ import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 import { formatSetupResult, runSetup } from '../commands/setup.js';
+import { formatUpdateResult, runUpdate } from '../commands/update.js';
 import { generateComprehensionHTML } from '../comprehension.js';
 import { generateDashboardHTML } from '../dashboard.js';
 import { checkMeshIntegrity, formatDoctorResults, formatMeshResults, runDoctor } from '../doctor.js';
@@ -63,9 +64,10 @@ function detectPlatform(projectRoot) {
   if (existsSync(path.join(projectRoot, '.claude-plugin'))) return 'claude';
   if (existsSync(path.join(projectRoot, '.cursor'))) return 'cursor';
   if (existsSync(path.join(projectRoot, '.windsurf'))) return 'windsurf';
-  if (existsSync(path.join(projectRoot, '.agents'))) return 'antigravity';
-  if (existsSync(path.join(projectRoot, '.openclaw'))) return 'openclaw';
   if (existsSync(path.join(projectRoot, '.codex'))) return 'codex';
+  if (existsSync(path.join(projectRoot, '.agents', 'skills'))) return 'codex';
+  if (existsSync(path.join(projectRoot, '.antigravity'))) return 'antigravity';
+  if (existsSync(path.join(projectRoot, '.openclaw'))) return 'openclaw';
   if (existsSync(path.join(projectRoot, '.opencode'))) return 'opencode';
   return null;
 }
@@ -337,6 +339,18 @@ async function cmdSetup(projectRoot, args) {
   }
 }
 
+async function cmdUpdate(projectRoot, args) {
+  try {
+    const result = await runUpdate({ projectRoot, runeRoot: RUNE_ROOT, args });
+    log(formatUpdateResult(result));
+    if (!result.ok) process.exit(1);
+  } catch (err) {
+    log('');
+    log(`  ✗ Update failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 async function readVersion() {
   try {
     const pkg = JSON.parse(await readFile(path.join(RUNE_ROOT, 'package.json'), 'utf-8'));
@@ -655,7 +669,7 @@ async function cmdHooks(projectRoot, args, subcommand) {
       '    status [--platform <name>|all] [--tier pro|business]          Show active preset, wired skills, tier coverage',
     );
     log('');
-    log('  Platforms: claude, cursor, windsurf, antigravity (auto-detected if omitted)');
+    log('  Platforms: claude, codex, cursor, windsurf, antigravity (auto-detected if omitted)');
     log('  Tiers: pro, business — requires $RUNE_PRO_ROOT / $RUNE_BUSINESS_ROOT env var or monorepo sibling.');
     log('  Options:');
     log('    --dry    Preview changes without writing');
@@ -851,6 +865,9 @@ async function main() {
     case 'setup':
       await cmdSetup(projectRoot, args);
       break;
+    case 'update':
+      await cmdUpdate(projectRoot, args);
+      break;
     case 'status':
       await cmdStatus(projectRoot, args);
       break;
@@ -886,6 +903,9 @@ async function main() {
         '    setup    Interactive wizard — auto-detect tiers, pick scope, install hooks (recommended for first-time)',
       );
       log('             [--here|--global] [--tier pro,business] [--preset gentle|strict] [--dry]');
+      log('    update   Update an existing install — git-pull detected tier repos, re-run the managed');
+      log('             setup rewrite in place (reuses installed platforms/preset/tiers), verify with doctor');
+      log('             [--no-pull] [--preset gentle|strict] [--tier pro,business] [--dry]');
       log('    init     Interactive setup for build pipeline (auto-detects platform)');
       log('    build    Compile skills for configured platform');
       log('    doctor   Validate compiled output + mesh integrity');
@@ -899,7 +919,7 @@ async function main() {
       log('               [--days <n>]  Lookback window for gate counts (default: 30)');
       log('    hooks      Install/uninstall/status for multi-platform auto-discipline');
       log(
-        '               hooks install [--preset gentle|strict|off] [--platform claude|cursor|windsurf|antigravity|all] [--global]',
+        '               hooks install [--preset gentle|strict|off] [--platform claude|codex|cursor|windsurf|antigravity|all] [--global]',
       );
       log('               hooks uninstall [--platform <name>|all]');
       log('               hooks status [--platform <name>|all]');

package/compiler/commands/hooks/install.js

@@ -1,5 +1,5 @@
 /**
- * `rune hooks install [--preset strict|gentle|off] [--platform claude|cursor|windsurf|antigravity|all]`
+ * `rune hooks install [--preset strict|gentle|off] [--platform claude|codex|cursor|windsurf|antigravity|all]`
  *
  * Writes Rune-managed hook/rule/workflow entries for one or more platforms.
  * Idempotent: re-running replaces existing Rune entries, preserves user entries.
@@ -41,7 +41,7 @@ export async function installHooks(projectRoot, args = {}) {
       results: [],
       written: false,
       notes: [
-        'No target platform detected. Create `.claude/`, `.cursor/`, `.windsurf/`, or `.antigravity/` first, or pass `--platform <name>`.',
+        'No target platform detected. Create `.claude/`, `.codex/`, `.cursor/`, `.windsurf/`, or `.antigravity/` first, or pass `--platform <name>`.',
         ...tierNotes,
       ],
     };

package/compiler/commands/hooks/status.js

@@ -34,7 +34,7 @@ export async function hookStatus(projectRoot, runeRoot, args = {}) {
       tiers,
       missingInRepo,
       notes: [
-        'No target platform detected. Create `.claude/`, `.cursor/`, `.windsurf/`, or `.antigravity/` first, or pass `--platform <name>`.',
+        'No target platform detected. Create `.claude/`, `.codex/`, `.cursor/`, `.windsurf/`, or `.antigravity/` first, or pass `--platform <name>`.',
       ],
     };
   }