From c66705d6ba4ff0b7cdf1c5f13565380033389c56 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Tue, 26 May 2026 12:08:53 -0400
Subject: [PATCH] fix(#279): document Agent mapping and deferred tool discovery
 (#285)

---
 .changeset/tidy-orcas-romp.md              |  5 ++++
 bin/install.js                             |  4 ++++
 tests/bug-279-codex-agent-mapping.test.cjs | 27 ++++++++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 .changeset/tidy-orcas-romp.md
 create mode 100644 tests/bug-279-codex-agent-mapping.test.cjs

diff --git a/.changeset/tidy-orcas-romp.md b/.changeset/tidy-orcas-romp.md
new file mode 100644
index 000000000..77de4e9a6
--- /dev/null
+++ b/.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.
diff --git a/bin/install.js b/bin/install.js
index 89241a189..a2f6f2b4e 100755
--- a/bin/install.js
+++ b/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
diff --git a/tests/bug-279-codex-agent-mapping.test.cjs b/tests/bug-279-codex-agent-mapping.test.cjs
new file mode 100644
index 000000000..fdbd73b0a
--- /dev/null
+++ b/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',
+    );
+  });
+});