fix(#279): document Agent mapping and deferred tool discovery (#285)

.changeset/tidy-orcas-romp.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 279
+---
+Fixed Codex adapter guidance to include Agent() mapping and deferred spawn_agent discovery via tool_search.

bin/install.js

@@ -2612,6 +2612,7 @@ GSD workflows use \`Task(...)\` (Claude Code syntax). Translate to Codex collabo
 
 Direct mapping:
 - \`Task(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
+- \`Agent(subagent_type="X", prompt="Y")\` → \`spawn_agent(agent_type="X", message="Y")\`
 - \`Task(model="...")\` → omit. \`spawn_agent\` has no inline \`model\` parameter;
   GSD embeds the resolved per-agent model directly into each agent's \`.toml\`
   at install time so \`model_overrides\` from \`.planning/config.json\` and
@@ -2630,6 +2631,9 @@ Spawn restriction:
 - Codex restricts \`spawn_agent\` to cases where the user has explicitly
   requested sub-agents. When automatic spawning is not permitted, do the
   work inline in the current agent rather than attempting to force a spawn.
+- In some Codex sessions, multi-agent tooling can be deferred. If \`spawn_agent\`
+  is not currently visible, discover tools first via \`tool_search\` before
+  defaulting to inline execution.
 
 Parallel fan-out:
 - Spawn multiple agents → collect agent IDs → \`wait(ids)\` for all to complete

tests/bug-279-codex-agent-mapping.test.cjs

@@ -0,0 +1,27 @@
+'use strict';
+// allow-test-rule: source-text-is-the-product [adapter header contract in bin/install.js]
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const INSTALL_JS = path.join(__dirname, '..', 'bin', 'install.js');
+const src = fs.readFileSync(INSTALL_JS, 'utf8');
+
+describe('bug #279: Codex adapter documents Agent() and deferred tool discovery', () => {
+  test('adapter mapping section includes explicit Agent(...) -> spawn_agent mapping', () => {
+    assert.ok(
+      /Task\(subagent_type="X", prompt="Y"\).*spawn_agent\(agent_type="X", message="Y"\)/.test(src) &&
+      /Agent\(subagent_type="X", prompt="Y"\).*spawn_agent\(agent_type="X", message="Y"\)/.test(src),
+      'Codex adapter must explicitly map both Task(...) and Agent(...) to spawn_agent',
+    );
+  });
+
+  test('adapter includes deferred tool_search discovery guidance before inline fallback', () => {
+    assert.ok(
+      src.includes('deferred') && src.includes('tool_search') && src.includes('spawn_agent'),
+      'Codex adapter must instruct deferred tool discovery via tool_search before deciding to run inline',
+    );
+  });
+});