fix: use scalar Claude agent tools (#2583)

Normalize scalar Claude agent tool metadata across validators, adapters, dashboards, and generated surfaces with regression coverage.

tests/ci/validate-agents-tools.test.js

@@ -0,0 +1,175 @@
+/**
+ * Focused tests for validate-agents.js tools frontmatter rules.
+ *
+ * Run with: node tests/ci/validate-agents-tools.test.js
+ */
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const validatorsDir = path.join(__dirname, '..', '..', 'scripts', 'ci');
+const repoRoot = path.join(__dirname, '..', '..');
+const canonicalAgentsDir = path.join(repoRoot, 'agents');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  \u2713 ${name}`);
+    return true;
+  } catch (err) {
+    console.log(`  \u2717 ${name}`);
+    console.log(`    Error: ${err.message}`);
+    return false;
+  }
+}
+
+function createTestDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'validate-agents-tools-test-'));
+}
+
+function cleanupTestDir(testDir) {
+  fs.rmSync(testDir, { recursive: true, force: true });
+}
+
+function stripShebang(source) {
+  let s = source;
+  if (s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  if (s.startsWith('#!')) {
+    const nl = s.indexOf('\n');
+    s = nl === -1 ? '' : s.slice(nl + 1);
+  }
+  return s;
+}
+
+function runSourceViaTempFile(source) {
+  const tmpFile = path.join(repoRoot, `.tmp-validator-${Date.now()}-${Math.random().toString(36).slice(2)}.js`);
+  try {
+    fs.writeFileSync(tmpFile, source, 'utf8');
+    const stdout = execFileSync('node', [tmpFile], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 10000,
+      cwd: repoRoot,
+    });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return {
+      code: err.status || 1,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+    };
+  } finally {
+    fs.rmSync(tmpFile, { force: true });
+  }
+}
+
+function runValidatorWithDir(validatorName, dirConstant, overridePath) {
+  const validatorPath = path.join(validatorsDir, `${validatorName}.js`);
+  let source = fs.readFileSync(validatorPath, 'utf8');
+  source = stripShebang(source);
+  const dirRegex = new RegExp(`const ${dirConstant} = .*?;`);
+  source = source.replace(dirRegex, `const ${dirConstant} = ${JSON.stringify(overridePath)};`);
+  return runSourceViaTempFile(source);
+}
+
+function readCanonicalAgent(file) {
+  const resolvedPath = path.resolve(canonicalAgentsDir, file);
+  const agentsRoot = path.resolve(canonicalAgentsDir);
+  assert.ok(
+    resolvedPath.startsWith(`${agentsRoot}${path.sep}`),
+    `${file} should resolve inside the canonical agents directory`
+  );
+  return fs.readFileSync(resolvedPath, 'utf8');
+}
+
+function runTests() {
+  console.log('\n=== Testing validate-agents tools frontmatter ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  if (test('canonical agents declare tools as comma-separated scalars', () => {
+    const agentFiles = fs.readdirSync(canonicalAgentsDir).filter(file => file.endsWith('.md'));
+
+    for (const file of agentFiles) {
+      const content = readCanonicalAgent(file);
+      const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      assert.ok(frontmatter, `${file} should have frontmatter`);
+
+      const toolsLine = frontmatter[1].match(/^tools:\s*(.+)$/m);
+      assert.ok(toolsLine, `${file} should declare a non-empty tools scalar`);
+      assert.ok(
+        !toolsLine[1].trim().startsWith('['),
+        `${file} should use comma-separated scalar tools, not a YAML sequence`
+      );
+    }
+  })) passed++; else failed++;
+
+  if (test('accepts comma-separated scalar agent tools', () => {
+    const testDir = createTestDir();
+    try {
+      fs.writeFileSync(path.join(testDir, 'scalar-tools.md'), '---\nmodel: sonnet\ntools: Read, Glob, Grep\n---\n# Agent');
+
+      const result = runValidatorWithDir('validate-agents', 'AGENTS_DIR', testDir);
+      assert.strictEqual(result.code, 0, `Should accept scalar tools, got stderr: ${result.stderr}`);
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  if (test('rejects YAML sequence-form agent tools', () => {
+    const testDir = createTestDir();
+    try {
+      fs.writeFileSync(path.join(testDir, 'sequence-tools.md'), '---\nmodel: sonnet\ntools: [Read, Glob, Grep]\n---\n# Agent');
+
+      const result = runValidatorWithDir('validate-agents', 'AGENTS_DIR', testDir);
+      assert.strictEqual(result.code, 1, 'Should reject sequence-form tools');
+      assert.ok(
+        result.stderr.includes('comma-separated scalar'),
+        `Should explain the supported tools format, got stderr: ${result.stderr}`
+      );
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  if (test('rejects block sequence-form agent tools', () => {
+    const testDir = createTestDir();
+    try {
+      fs.writeFileSync(path.join(testDir, 'block-sequence-tools.md'), '---\nmodel: sonnet\ntools:\n  - Read\n  - Glob\n  - Grep\n---\n# Agent');
+
+      const result = runValidatorWithDir('validate-agents', 'AGENTS_DIR', testDir);
+      assert.strictEqual(result.code, 1, 'Should reject block sequence-form tools');
+      assert.ok(
+        result.stderr.includes('comma-separated scalar'),
+        `Should explain the supported tools format, got stderr: ${result.stderr}`
+      );
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  if (test('rejects explicitly tagged YAML sequence-form agent tools', () => {
+    const testDir = createTestDir();
+    try {
+      fs.writeFileSync(path.join(testDir, 'tagged-sequence-tools.md'), '---\nmodel: sonnet\ntools: !!seq [Read, Glob, Grep]\n---\n# Agent');
+
+      const result = runValidatorWithDir('validate-agents', 'AGENTS_DIR', testDir);
+      assert.strictEqual(result.code, 1, 'Should reject tagged sequence-form tools');
+      assert.ok(
+        result.stderr.includes('comma-separated scalar'),
+        `Should explain the supported tools format, got stderr: ${result.stderr}`
+      );
+    } finally {
+      cleanupTestDir(testDir);
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();

tests/lib/agent-compress.test.js

@@ -45,6 +45,29 @@ function runTests() {
     passed++;
   else failed++;
 
+  if (
+    test('parseFrontmatter normalizes comma-separated scalar tools to an array', () => {
+      const content = '---\nname: scalar-tools\ndescription: Scalar tools\ntools: Read, Glob, Grep\nmodel: sonnet\n---\n\nBody.';
+      const { frontmatter } = parseFrontmatter(content);
+      assert.deepStrictEqual(frontmatter.tools, ['Read', 'Glob', 'Grep']);
+    })
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('parseFrontmatter preserves commas inside scoped tool arguments', () => {
+      const content = '---\nname: scoped-tools\ndescription: Scoped tools\ntools: Agent(worker, researcher), Read, Bash\nmodel: sonnet\n---\n\nBody.';
+      const { frontmatter } = parseFrontmatter(content);
+      assert.deepStrictEqual(
+        frontmatter.tools,
+        ['Agent(worker, researcher)', 'Read', 'Bash']
+      );
+    })
+  )
+    passed++;
+  else failed++;
+
   if (
     test('parseFrontmatter handles content without frontmatter', () => {
       const content = 'Just a regular markdown file.';
@@ -155,7 +178,7 @@ function runTests() {
 
   // Create a temp directory with test agent files
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-compress-test-'));
-  const agentContent = '---\nname: test-agent\ndescription: A test agent\ntools: ["Read"]\nmodel: haiku\n---\n\nTest agent body paragraph.\n\n## Details\nMore info.';
+  const agentContent = '---\nname: test-agent\ndescription: A test agent\ntools: Read\nmodel: haiku\n---\n\nTest agent body paragraph.\n\n## Details\nMore info.';
   fs.writeFileSync(path.join(tmpDir, 'test-agent.md'), agentContent);
   fs.writeFileSync(path.join(tmpDir, 'not-an-agent.txt'), 'ignored');
 
@@ -332,6 +355,10 @@ function runTests() {
       if (!fs.existsSync(realAgentsDir)) return; // skip if not present
       const result = buildAgentCatalog(realAgentsDir, { mode: 'catalog' });
       assert.ok(result.agents.length > 0, 'Should find at least one agent');
+      assert.ok(
+        result.agents.every(agent => Array.isArray(agent.tools) && agent.tools.length > 0),
+        'Every catalog agent should retain its tools as a non-empty array'
+      );
       assert.ok(result.stats.compressedBytes < result.stats.originalBytes, 'Catalog should be smaller than original');
       // Verify significant compression ratio
       const ratio = result.stats.compressedBytes / result.stats.originalBytes;

tests/scripts/dashboard-web.test.js

@@ -36,6 +36,29 @@ function cleanup(dirPath) {
   fs.rmSync(dirPath, { recursive: true, force: true });
 }
 
+function withTempDir(prefix, fn) {
+  const dirPath = createTempDir(prefix);
+  try {
+    return fn(dirPath);
+  } finally {
+    cleanup(dirPath);
+  }
+}
+
+test('withTempDir removes temp directories when the callback throws', () => {
+  let createdDir = '';
+  assert.throws(() => {
+    withTempDir('ecc-test-', dirPath => {
+      createdDir = dirPath;
+      assert.ok(fs.existsSync(createdDir));
+      throw new Error('fixture failure');
+    });
+  }, /fixture failure/);
+
+  assert.ok(createdDir);
+  assert.ok(!fs.existsSync(createdDir));
+});
+
 function writeFile(rootDir, relativePath, content) {
   const targetPath = path.join(rootDir, relativePath);
   fs.mkdirSync(path.dirname(targetPath), { recursive: true });
@@ -125,6 +148,43 @@ test('readFrontmatter parses array tools field', () => {
   cleanup(testRoot);
 });
 
+test('readFrontmatter preserves scoped tools in legacy flow sequences', () => {
+  const { readFrontmatter } = require(SCRIPT);
+  withTempDir('ecc-test-', tempDir => {
+    writeFile(tempDir, 'agent.md', [
+      '---',
+      'name: scoped-agent',
+      'tools: [Agent(worker, researcher), Read, Bash(git commit:*, git status:*)]',
+      '---',
+      'body',
+    ].join('\n'));
+
+    const fm = readFrontmatter(path.join(tempDir, 'agent.md'));
+    assert.deepStrictEqual(fm.tools, [
+      'Agent(worker, researcher)',
+      'Read',
+      'Bash(git commit:*, git status:*)',
+    ]);
+  });
+});
+
+test('readFrontmatter normalizes comma-separated scalar tools to an array', () => {
+  const { readFrontmatter } = require(SCRIPT);
+  testRoot = createTempDir('ecc-test-');
+  writeFile(testRoot, 'agent.md', [
+    '---',
+    'name: test-agent',
+    'tools: Bash, Read, Write',
+    '---',
+    '# Body',
+  ].join('\n'));
+
+  const fm = readFrontmatter(path.join(testRoot, 'agent.md'));
+  assert.ok(Array.isArray(fm.tools));
+  assert.deepStrictEqual(fm.tools, ['Bash', 'Read', 'Write']);
+  cleanup(testRoot);
+});
+
 test('readFrontmatter handles quoted values', () => {
   const { readFrontmatter } = require(SCRIPT);
   testRoot = createTempDir('ecc-test-');
@@ -202,7 +262,7 @@ test('loadAgents loads agent markdown files', () => {
     'name: typescript-reviewer',
     'description: Reviews TypeScript code',
     'model: claude-sonnet-4-6',
-    'tools: [Bash, Read, Write, Grep]',
+    'tools: Bash, Read, Write, Grep',
     '---',
     '# TypeScript Reviewer',
     'You are a TypeScript code reviewer.',
@@ -212,7 +272,7 @@ test('loadAgents loads agent markdown files', () => {
     'name: python-reviewer',
     'description: Reviews Python code',
     'model: claude-opus-4-8',
-    'tools: [Bash, Read]',
+    'tools: Bash, Read',
     '---',
     '# Python Reviewer',
   ].join('\n'));

tests/scripts/gemini-adapt-agents.test.js

@@ -99,6 +99,36 @@ function runTests() {
     }
   })) passed++; else failed++;
 
+  if (test('adapts comma-separated scalar Claude Code tools', () => {
+    const tempDir = createTempDir();
+    const agentsDir = path.join(tempDir, '.gemini', 'agents');
+
+    try {
+      writeAgent(
+        agentsDir,
+        'docs-lookup.md',
+        [
+          '---',
+          'name: docs-lookup',
+          'description: Documentation lookup agent',
+          'tools: Read, Grep, mcp__context7__resolve-library-id, mcp__context7__query-docs',
+          'model: sonnet',
+          '---',
+          '',
+          'Body'
+        ].join('\n')
+      );
+
+      const result = run([agentsDir]);
+      assert.strictEqual(result.code, 0, result.stderr);
+
+      const updated = fs.readFileSync(path.join(agentsDir, 'docs-lookup.md'), 'utf8');
+      assert.ok(updated.includes('tools: ["read_file", "grep_search", "mcp_context7_resolve_library_id", "mcp_context7_query_docs"]'));
+    } finally {
+      cleanupTempDir(tempDir);
+    }
+  })) passed++; else failed++;
+
   if (test('defaults to the cwd .gemini/agents directory', () => {
     const tempDir = createTempDir();
     const agentsDir = path.join(tempDir, '.gemini', 'agents');