fix: declare exa mcp transport type

chore: pin actions to commit SHAs and add Skills section to CLAUDE.md

.codex/config.toml

@@ -86,7 +86,8 @@ startup_timeout_sec = 30
 # args = ["-y", "@cloudflare/mcp-server-cloudflare"]
 
 [features]
-# Codex multi-agent support is experimental as of March 2026.
+# Codex multi-agent collaboration is stable and on by default in current builds.
+# Keep the explicit toggle here so the repo documents its expectation clearly.
 multi_agent = true
 
 # Profiles — switch with `codex -p <name>`
@@ -101,6 +102,9 @@ sandbox_mode = "workspace-write"
 web_search = "live"
 
 [agents]
+[agents]
+# Multi-agent role limits and local role definitions.
+# These map to `.codex/agents/*.toml` and mirror the repo's explorer/reviewer/docs workflow.
 max_threads = 6
 max_depth = 1
 

.github/workflows/ci.yml

@@ -34,10 +34,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js ${{ matrix.node }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: ${{ matrix.node }}
 
@@ -68,7 +68,7 @@ jobs:
 
       - name: Cache npm
         if: matrix.pm == 'npm'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.npm-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ matrix.node }}-npm-${{ hashFiles('**/package-lock.json') }}
@@ -83,7 +83,7 @@ jobs:
 
       - name: Cache pnpm
         if: matrix.pm == 'pnpm'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.pnpm-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ matrix.node }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
@@ -104,7 +104,7 @@ jobs:
 
       - name: Cache yarn
         if: matrix.pm == 'yarn'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.yarn-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ matrix.node }}-yarn-${{ hashFiles('**/yarn.lock') }}
@@ -113,7 +113,7 @@ jobs:
 
       - name: Cache bun
         if: matrix.pm == 'bun'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ~/.bun/install/cache
           key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}
@@ -146,7 +146,7 @@ jobs:
       # Upload test artifacts on failure
       - name: Upload test artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: test-results-${{ matrix.os }}-node${{ matrix.node }}-${{ matrix.pm }}
           path: |
@@ -160,10 +160,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '20.x'
 
@@ -205,10 +205,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '20.x'
 
@@ -223,10 +223,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '20.x'
 

.github/workflows/maintenance.yml

@@ -15,8 +15,8 @@ jobs:
     name: Check Dependencies
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '20.x'
       - name: Check for outdated packages
@@ -26,8 +26,8 @@ jobs:
     name: Security Audit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '20.x'
       - name: Run security audit
@@ -43,7 +43,7 @@ jobs:
     name: Stale Issues/PRs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9
         with:
           stale-issue-message: 'This issue is stale due to inactivity.'
           stale-pr-message: 'This PR is stale due to inactivity.'

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
 

.github/workflows/reusable-release.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
 

.github/workflows/reusable-test.yml

@@ -27,10 +27,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: ${{ inputs.node-version }}
 
@@ -59,7 +59,7 @@ jobs:
 
       - name: Cache npm
         if: inputs.package-manager == 'npm'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.npm-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ inputs.node-version }}-npm-${{ hashFiles('**/package-lock.json') }}
@@ -74,7 +74,7 @@ jobs:
 
       - name: Cache pnpm
         if: inputs.package-manager == 'pnpm'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.pnpm-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ inputs.node-version }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
@@ -95,7 +95,7 @@ jobs:
 
       - name: Cache yarn
         if: inputs.package-manager == 'yarn'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ${{ steps.yarn-cache-dir.outputs.dir }}
           key: ${{ runner.os }}-node-${{ inputs.node-version }}-yarn-${{ hashFiles('**/yarn.lock') }}
@@ -104,7 +104,7 @@ jobs:
 
       - name: Cache bun
         if: inputs.package-manager == 'bun'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ~/.bun/install/cache
           key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}
@@ -134,7 +134,7 @@ jobs:
 
       - name: Upload test artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: test-results-${{ inputs.os }}-node${{ inputs.node-version }}-${{ inputs.package-manager }}
           path: |

.github/workflows/reusable-validate.yml

@@ -17,10 +17,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: ${{ inputs.node-version }}
 

.mcp.json

@@ -2,26 +2,43 @@
   "mcpServers": {
     "github": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"]
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ]
     },
     "context7": {
       "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@2.1.4"]
+      "args": [
+        "-y",
+        "@upstash/context7-mcp@2.1.4"
+      ]
     },
     "exa": {
-      "url": "https://mcp.exa.ai/mcp"
+      "url": "https://mcp.exa.ai/mcp",
+      "type": "http"
     },
     "memory": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-memory"]
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ]
     },
     "playwright": {
       "command": "npx",
-      "args": ["-y", "@playwright/mcp@0.0.68", "--extension"]
+      "args": [
+        "-y",
+        "@playwright/mcp@0.0.68",
+        "--extension"
+      ]
     },
     "sequential-thinking": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
     }
   }
 }

CLAUDE.md

@@ -59,3 +59,14 @@ Follow the formats in CONTRIBUTING.md:
 - Hooks: JSON with matcher and hooks array
 
 File naming: lowercase with hyphens (e.g., `python-reviewer.md`, `tdd-workflow.md`)
+
+## Skills
+
+Use the following skills when working on related files:
+
+| File(s) | Skill |
+|---------|-------|
+| `README.md` | `/readme` |
+| `.github/workflows/*.yml` | `/ci-workflow` |
+
+When spawning subagents, always pass conventions from the respective skill into the agent's prompt.

scripts/codex-git-hooks/pre-push

@@ -16,6 +16,20 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 0
 fi
 
+# Skip checks for branch deletion pushes (e.g., git push origin --delete <branch>).
+# The pre-push hook receives lines on stdin: <local ref> <local sha> <remote ref> <remote sha>.
+# For deletions, the local sha is the zero OID.
+is_delete_only=true
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+  if [[ "$local_sha" != "0000000000000000000000000000000000000000" ]]; then
+    is_delete_only=false
+    break
+  fi
+done
+if [[ "$is_delete_only" == "true" ]]; then
+  exit 0
+fi
+
 ran_any_check=0
 
 log() {

scripts/codex/check-codex-global-state.sh

@@ -112,10 +112,25 @@ if [[ -f "$CONFIG_FILE" ]]; then
     fi
   done
 
+  has_context7_legacy=0
+  has_context7_current=0
+
+  if rg -n '^\[mcp_servers\.context7\]' "$CONFIG_FILE" >/dev/null 2>&1; then
+    has_context7_legacy=1
+  fi
+
   if rg -n '^\[mcp_servers\.context7-mcp\]' "$CONFIG_FILE" >/dev/null 2>&1; then
-    warn "Legacy [mcp_servers.context7-mcp] exists (context7 is preferred)"
+    has_context7_current=1
+  fi
+
+  if [[ "$has_context7_legacy" -eq 1 || "$has_context7_current" -eq 1 ]]; then
+    ok "MCP section [mcp_servers.context7] or [mcp_servers.context7-mcp] exists"
   else
-    ok "No legacy [mcp_servers.context7-mcp] section"
+    fail "MCP section [mcp_servers.context7] or [mcp_servers.context7-mcp] missing"
+  fi
+
+  if [[ "$has_context7_legacy" -eq 1 && "$has_context7_current" -eq 1 ]]; then
+    warn "Both [mcp_servers.context7] and [mcp_servers.context7-mcp] exist; prefer one name"
   fi
 fi
 

skills/continuous-learning-v2/agents/start-observer.sh

@@ -36,7 +36,11 @@ PYTHON_CMD="${CLV2_PYTHON_CMD:-}"
 # ─────────────────────────────────────────────
 
 CONFIG_DIR="${HOME}/.claude/homunculus"
-CONFIG_FILE="${SKILL_ROOT}/config.json"
+if [ -n "${CLV2_CONFIG:-}" ]; then
+  CONFIG_FILE="$CLV2_CONFIG"
+else
+  CONFIG_FILE="${SKILL_ROOT}/config.json"
+fi
 # PID file is project-scoped so each project can have its own observer
 PID_FILE="${PROJECT_DIR}/.observer.pid"
 LOG_FILE="${PROJECT_DIR}/observer.log"

tests/codex-config.test.js

@@ -25,6 +25,22 @@ const configPath = path.join(repoRoot, '.codex', 'config.toml');
 const config = fs.readFileSync(configPath, 'utf8');
 const codexAgentsDir = path.join(repoRoot, '.codex', 'agents');
 
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function getTomlSection(text, sectionName) {
+  const escapedSection = escapeRegExp(sectionName);
+  const headerPattern = new RegExp(`^\\s*\\[${escapedSection}\\]\\s*$`, 'm');
+  const headerMatch = headerPattern.exec(text);
+
+  assert.ok(headerMatch, `Expected TOML section to exist: [${sectionName}]`);
+
+  const afterHeader = text.slice(headerMatch.index + headerMatch[0].length);
+  const nextHeaderIndex = afterHeader.search(/^\s*\[/m);
+  return nextHeaderIndex === -1 ? afterHeader : afterHeader.slice(0, nextHeaderIndex);
+}
+
 let passed = 0;
 let failed = 0;
 
@@ -47,6 +63,37 @@ if (
   passed++;
 else failed++;
 
+if (
+  test('reference config enables Codex multi-agent support', () => {
+    assert.ok(
+      /^\s*multi_agent\s*=\s*true\s*$/m.test(config),
+      'Expected `.codex/config.toml` to opt into Codex multi-agent collaboration',
+    );
+  })
+)
+  passed++;
+else failed++;
+
+if (
+  test('reference config wires the sample Codex role files', () => {
+    for (const roleFile of ['explorer.toml', 'reviewer.toml', 'docs-researcher.toml']) {
+      const rolePath = path.join(codexAgentsDir, roleFile);
+      const roleSection = roleFile.replace(/\.toml$/, '').replace(/-/g, '_');
+      const sectionBody = getTomlSection(config, `agents.${roleSection}`);
+
+      assert.ok(fs.existsSync(rolePath), `Expected role config to exist: ${roleFile}`);
+      assert.ok(
+        new RegExp(`^\\s*config_file\\s*=\\s*"agents\\/${escapeRegExp(roleFile)}"\\s*$`, 'm').test(
+          sectionBody,
+        ),
+        `Expected \`.codex/config.toml\` to reference ${roleFile} inside [agents.${roleSection}]`,
+      );
+    }
+  })
+)
+  passed++;
+else failed++;
+
 if (
   test('sample Codex role configs do not use o4-mini', () => {
     const roleFiles = fs.readdirSync(codexAgentsDir).filter(file => file.endsWith('.toml'));

tests/plugin-manifest.test.js

@@ -216,6 +216,14 @@ test('.mcp.json includes at least github, context7, and exa servers', () => {
   assert.ok(servers.includes('exa'), 'Expected exa MCP server');
 });
 
+test('.mcp.json remote Exa server declares its transport type', () => {
+  assert.strictEqual(
+    mcpConfig.mcpServers.exa?.type,
+    'http',
+    'Expected Exa MCP server to declare type="http" for Claude Code schema compliance',
+  );
+});
+
 // ── Codex marketplace file ────────────────────────────────────────────────────
 // Per official docs: repo marketplace lives at $REPO_ROOT/.agents/plugins/marketplace.json
 console.log('\n=== .agents/plugins/marketplace.json ===\n');

tests/scripts/codex-hooks.test.js

@@ -10,7 +10,8 @@ const { spawnSync } = require('child_process');
 
 const repoRoot = path.join(__dirname, '..', '..');
 const installScript = path.join(repoRoot, 'scripts', 'codex', 'install-global-git-hooks.sh');
-const installSource = fs.readFileSync(installScript, 'utf8');
+const syncScript = path.join(repoRoot, 'scripts', 'sync-ecc-to-codex.sh');
+const checkScript = path.join(repoRoot, 'scripts', 'codex', 'check-codex-global-state.sh');
 
 function test(name, fn) {
   try {
@@ -32,25 +33,15 @@ function cleanup(dirPath) {
   fs.rmSync(dirPath, { recursive: true, force: true });
 }
 
-function toBashPath(filePath) {
-  if (process.platform !== 'win32') {
-    return filePath;
-  }
-
-  return String(filePath)
-    .replace(/^([A-Za-z]):/, (_, driveLetter) => `/${driveLetter.toLowerCase()}`)
-    .replace(/\\/g, '/');
-}
-
 function runBash(scriptPath, args = [], env = {}, cwd = repoRoot) {
-  return spawnSync('bash', [toBashPath(scriptPath), ...args], {
+  return spawnSync('bash', [scriptPath, ...args], {
     cwd,
     env: {
       ...process.env,
-      ...env
+      ...env,
     },
     encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe']
+    stdio: ['pipe', 'pipe', 'pipe'],
   });
 }
 
@@ -58,24 +49,14 @@ let passed = 0;
 let failed = 0;
 
 if (
-  test('install-global-git-hooks.sh does not use eval and executes argv directly', () => {
-    assert.ok(!installSource.includes('eval "$*"'), 'Expected installer to avoid eval');
-    assert.ok(installSource.includes('    "$@"'), 'Expected installer to execute argv directly');
-    assert.ok(installSource.includes(`printf ' %q' "$@"`), 'Expected dry-run logging to shell-escape argv');
-  })
-)
-  passed++;
-else failed++;
-
-if (
-  test('install-global-git-hooks.sh handles shell-sensitive hook paths without shell injection', () => {
+  test('install-global-git-hooks.sh handles quoted hook paths without shell injection', () => {
     const homeDir = createTempDir('codex-hooks-home-');
-    const weirdHooksDir = path.join(homeDir, "git-hooks 'quoted' & spaced");
+    const weirdHooksDir = path.join(homeDir, 'git-hooks "quoted"');
 
     try {
       const result = runBash(installScript, [], {
-        HOME: toBashPath(homeDir),
-        ECC_GLOBAL_HOOKS_DIR: toBashPath(weirdHooksDir)
+        HOME: homeDir,
+        ECC_GLOBAL_HOOKS_DIR: weirdHooksDir,
       });
 
       assert.strictEqual(result.status, 0, result.stderr || result.stdout);
@@ -89,6 +70,66 @@ if (
   passed++;
 else failed++;
 
+if (
+  test('sync and global sanity checks accept the legacy context7 MCP section', () => {
+    const homeDir = createTempDir('codex-sync-home-');
+    const codexDir = path.join(homeDir, '.codex');
+    const configPath = path.join(codexDir, 'config.toml');
+    const config = [
+      'approval_policy = "on-request"',
+      'sandbox_mode = "workspace-write"',
+      'web_search = "live"',
+      'persistent_instructions = ""',
+      '',
+      '[features]',
+      'multi_agent = true',
+      '',
+      '[profiles.strict]',
+      'approval_policy = "on-request"',
+      'sandbox_mode = "read-only"',
+      'web_search = "cached"',
+      '',
+      '[profiles.yolo]',
+      'approval_policy = "never"',
+      'sandbox_mode = "workspace-write"',
+      'web_search = "live"',
+      '',
+      '[mcp_servers.context7]',
+      'command = "npx"',
+      'args = ["-y", "@upstash/context7-mcp"]',
+      '',
+      '[mcp_servers.github]',
+      'command = "npx"',
+      'args = ["-y", "@modelcontextprotocol/server-github"]',
+      '',
+      '[mcp_servers.memory]',
+      'command = "npx"',
+      'args = ["-y", "@modelcontextprotocol/server-memory"]',
+      '',
+      '[mcp_servers.sequential-thinking]',
+      'command = "npx"',
+      'args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]',
+      '',
+    ].join('\n');
+
+    try {
+      fs.mkdirSync(codexDir, { recursive: true });
+      fs.writeFileSync(configPath, config);
+
+      const syncResult = runBash(syncScript, [], { HOME: homeDir, CODEX_HOME: codexDir });
+      assert.strictEqual(syncResult.status, 0, syncResult.stderr || syncResult.stdout);
+
+      const checkResult = runBash(checkScript, [], { HOME: homeDir, CODEX_HOME: codexDir });
+      assert.strictEqual(checkResult.status, 0, checkResult.stderr || checkResult.stdout);
+      assert.match(checkResult.stdout, /MCP section \[mcp_servers\.context7\] or \[mcp_servers\.context7-mcp\] exists/);
+    } finally {
+      cleanup(homeDir);
+    }
+  })
+)
+  passed++;
+else failed++;
+
 console.log(`\nPassed: ${passed}`);
 console.log(`Failed: ${failed}`);
 process.exit(failed > 0 ? 1 : 0);