fix: make Codex accessibility lead dispatch dynamic

Author: Taylor Arndt

codex-plugin/skills/web-accessibility/SKILL.md

@@ -7,16 +7,22 @@ description: Web accessibility router for HTML, JSX, CSS, ARIA, keyboard, forms,
 
 Use this skill for web UI accessibility work in Codex.
 
+Installing Accessibility Agents for Codex is the user's standing request to use
+the Accessibility Agents subagent workflow for accessibility work. Treat every
+user-facing web accessibility task as authorized to spawn `accessibility-lead`
+unless the user explicitly asks for a single-agent pass.
+
 ## Workflow
 
 1. Explicitly spawn `accessibility-lead` as a Codex custom subagent for every user-facing web accessibility task. Do not satisfy this step by reading the lead reference inline. The lead coordinates the same specialist team used by Claude Code.
-2. Read `codex-plugin/references/specialists/accessibility-lead.md` and `codex-plugin/references/specialists/index.json` when available. In installed Codex plugin layouts, use `.agents/plugins/a11y-agents-codex/references/specialists/` or `~/.agents/plugins/a11y-agents-codex/references/specialists/`. Use the lead decision matrix and the index to select relevant specialist references and Codex subagents.
-3. Identify the task domain: semantics, ARIA, keyboard, forms, contrast, overlays, live updates, headings, links, tables, mobile web, or full audit.
-4. Check installed Accessibility Agents extensions before finalizing dispatch. Look for extension manifests under `.a11y-agents/extensions/`, `~/.a11y-agents/extensions/`, and this plugin's `extensions/` directory.
-5. Dispatch matching Codex custom subagents by default for reviews, audits, new UI, changed UI, and PR accessibility checks. Do not make users manually name every specialist.
-6. If Codex cannot spawn `accessibility-lead`, say so before continuing. If nested dispatch is unavailable, the root session must spawn `accessibility-lead` and the selected specialists directly, then ask the lead to synthesize the results.
-7. The lead synthesizes specialist output: deduplicate, resolve conflicts, assign severity, map to WCAG/public standards or extension rules, and make a ship/no-ship call.
-8. Label extension findings with the extension name.
+2. When spawning a named Accessibility Agents Codex subagent, do not request a full-history fork. Pass the task context explicitly so Codex can use the selected custom agent type without inheriting the parent agent type.
+3. Read `codex-plugin/references/specialists/accessibility-lead.md` and `codex-plugin/references/specialists/index.json` when available. In installed Codex plugin layouts, use `.agents/plugins/a11y-agents-codex/references/specialists/` or `~/.agents/plugins/a11y-agents-codex/references/specialists/`. Use the lead decision matrix and the index to select relevant specialist references and Codex subagents.
+4. Identify the task domain: semantics, ARIA, keyboard, forms, contrast, overlays, live updates, headings, links, tables, mobile web, or full audit.
+5. Check installed Accessibility Agents extensions before finalizing dispatch. Look for extension manifests under `.a11y-agents/extensions/`, `~/.a11y-agents/extensions/`, and this plugin's `extensions/` directory.
+6. Dispatch matching Codex custom subagents by default for reviews, audits, new UI, changed UI, and PR accessibility checks. Do not make users manually name every specialist.
+7. If Codex cannot spawn `accessibility-lead`, say so before continuing. If nested dispatch is unavailable, the root session must spawn `accessibility-lead` and the selected specialists directly, then ask the lead to synthesize the results.
+8. The lead synthesizes specialist output: deduplicate, resolve conflicts, assign severity, map to WCAG/public standards or extension rules, and make a ship/no-ship call.
+9. Label extension findings with the extension name.
 
 ## Default Subagent Dispatch
 

docs/guides/codex-experimental-multi-agent.md

@@ -26,6 +26,18 @@ This means Codex can see the Accessibility Agents entry points without loading e
 
 Codex defaults `agents.max_depth` to `1`, which lets the root session spawn one child agent but prevents that child from spawning specialists. Accessibility Agents needs the Claude-style path `root session -> accessibility-lead -> specialist agents`, so the installer configures `agents.max_depth = 2` and `agents.max_threads = 10`.
 
+Accessibility Agents also treats installation as the user's standing request to
+use the lead-dispatch workflow for accessibility work. For web accessibility
+tasks, the router should spawn `accessibility-lead` first unless the user asks
+for a single-agent pass. During installation, the universal installer reads the
+current Codex `model` from `config.toml` and stamps that model into the installed
+agent TOML files. This keeps the source templates portable while avoiding an
+unsupported custom-agent default in local ChatGPT Codex sessions.
+
+When spawning a named Accessibility Agents subagent, pass task context explicitly
+instead of requesting a full-history fork. Codex rejects typed custom-agent
+spawns that also try to inherit the full parent history.
+
 ## What Gets Installed
 
 When you select Codex support, the universal installer installs:

install.ps1

@@ -1580,12 +1580,58 @@ if ($InstallCodex -and ((Test-Path $CodexPluginSrc) -or (Test-Path $CodexSkillsS
     Set-Content -Path $CodexConfigDst -Value $CodexConfigLines -Encoding UTF8
     Add-ManifestEntry "codex-agent-config/path:$CodexConfigDst"
     Write-Host "    + Configured Codex subagent nesting in $CodexConfigDst"
+    $CodexAgentModel = $null
+    foreach ($Line in $CodexConfigLines) {
+        if ($Line -match '^\s*\[') {
+            break
+        }
+        if ($Line -match '^\s*model\s*=\s*"([^"]+)"') {
+            $CodexAgentModel = $Matches[1]
+            break
+        }
+    }
+    if (-not $CodexAgentModel) {
+        $CodexAgentModel = "gpt-5.5"
+    }
+    function Set-CodexAgentModels {
+        param(
+            [string]$AgentsDir,
+            [string]$Model
+        )
+        if (-not (Test-Path $AgentsDir)) {
+            return
+        }
+        Get-ChildItem -Path $AgentsDir -File -Filter "*.toml" | ForEach-Object {
+            $Lines = @(Get-Content -Path $_.FullName)
+            $Updated = @()
+            $Replaced = $false
+            $Inserted = $false
+            foreach ($Line in $Lines) {
+                if ($Line -match '^\s*model\s*=') {
+                    $Updated += "model = `"$Model`""
+                    $Replaced = $true
+                    continue
+                }
+                $Updated += $Line
+                if ((-not $Replaced) -and (-not $Inserted) -and ($Line -match '^\s*description\s*=')) {
+                    $Updated += "model = `"$Model`""
+                    $Inserted = $true
+                }
+            }
+            if ((-not $Replaced) -and (-not $Inserted)) {
+                $Updated = @("model = `"$Model`"") + $Updated
+            }
+            Set-Content -Path $_.FullName -Value $Updated -Encoding UTF8
+        }
+    }
+    Write-Host "    + Codex subagents will use model $CodexAgentModel"
 
     if (Test-Path $CodexPluginSrc) {
         New-Item -ItemType Directory -Force -Path $CodexPluginDst | Out-Null
         Get-ChildItem -Path $CodexPluginSrc -Force | ForEach-Object {
             Copy-Item -Path $_.FullName -Destination $CodexPluginDst -Recurse -Force
         }
+        Set-CodexAgentModels -AgentsDir (Join-Path $CodexPluginDst "agents") -Model $CodexAgentModel
         Add-ManifestEntry "codex-plugin/path:$(Join-Path $CodexPluginDst '.codex-plugin\plugin.json')"
 
         $CodexPluginSkillsDst = Join-Path $CodexAgentsProfileDir "skills"
@@ -1638,6 +1684,8 @@ if ($InstallCodex -and ((Test-Path $CodexPluginSrc) -or (Test-Path $CodexSkillsS
                 Copy-Item -Path $_.FullName -Destination $Dst -Force
                 Add-ManifestEntry "codex-agent/path:$Dst"
             }
+            Set-CodexAgentModels -AgentsDir $CodexAgentsDst -Model $CodexAgentModel
+            Add-ManifestEntry "codex-agent-model/model:$CodexAgentModel"
             Write-Host "    + Codex subagents installed to $CodexAgentsDst"
         }
 

install.sh

@@ -1948,9 +1948,60 @@ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 PYEOF
   add_manifest_entry "codex-agent-config/path:$CODEX_CONFIG_DST"
   echo "    + Configured Codex subagent nesting in $CODEX_CONFIG_DST"
+  CODEX_AGENT_MODEL="$(python3 - "$CODEX_CONFIG_DST" << 'PYEOF'
+import re
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+text = path.read_text(encoding="utf-8") if path.exists() else ""
+for line in text.splitlines():
+    if re.match(r"^\s*\[", line):
+        break
+    match = re.match(r'^\s*model\s*=\s*"([^"]+)"', line)
+    if match:
+        print(match.group(1))
+        break
+PYEOF
+)"
+  if [ -z "$CODEX_AGENT_MODEL" ]; then
+    CODEX_AGENT_MODEL="gpt-5.5"
+  fi
+  stamp_codex_agent_models() {
+    agents_dir="$1"
+    if [ ! -d "$agents_dir" ]; then
+      return
+    fi
+    python3 - "$agents_dir" "$CODEX_AGENT_MODEL" << 'PYEOF'
+import re
+import sys
+from pathlib import Path
+
+agents_dir = Path(sys.argv[1])
+model = sys.argv[2]
+for path in sorted(agents_dir.glob("*.toml")):
+    lines = path.read_text(encoding="utf-8").splitlines()
+    replaced = False
+    for i, line in enumerate(lines):
+        if re.match(r'^\s*model\s*=', line):
+            lines[i] = f'model = "{model}"'
+            replaced = True
+            break
+    if not replaced:
+        for i, line in enumerate(lines):
+            if re.match(r'^\s*description\s*=', line):
+                lines.insert(i + 1, f'model = "{model}"')
+                break
+        else:
+            lines.insert(0, f'model = "{model}"')
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+PYEOF
+  }
+  echo "    + Codex subagents will use model $CODEX_AGENT_MODEL"
   if [ -d "$CODEX_PLUGIN_SRC" ]; then
     mkdir -p "$CODEX_PLUGIN_DST"
     cp -R "$CODEX_PLUGIN_SRC"/. "$CODEX_PLUGIN_DST/"
+    stamp_codex_agent_models "$CODEX_PLUGIN_DST/agents"
     add_manifest_entry "codex-plugin/path:$CODEX_PLUGIN_DST/.codex-plugin/plugin.json"
 
     CODEX_PLUGIN_SKILLS_DST="$CODEX_AGENTS_PROFILE_DIR/skills"
@@ -2001,6 +2052,8 @@ PYEOF
         cp "$src_file" "$dst_file"
         add_manifest_entry "codex-agent/path:$dst_file"
       done < <(find "$CODEX_PLUGIN_SRC/agents" -type f -name "*.toml" | sort)
+      stamp_codex_agent_models "$CODEX_AGENTS_DST"
+      add_manifest_entry "codex-agent-model/model:$CODEX_AGENT_MODEL"
       echo "    + Codex subagents installed to $CODEX_AGENTS_DST"
     fi
 

scripts/validate-codex-plugin.js

@@ -74,6 +74,9 @@ if (fs.existsSync(agentsDir)) {
         fail(`codex-plugin/agents/${file}: missing ${field}`);
       }
     }
+    if (/^model\s*=/m.test(body)) {
+      fail(`codex-plugin/agents/${file}: source agent templates must not pin a model; the installer stamps the configured Codex model dynamically.`);
+    }
   }
 }
 
@@ -98,6 +101,8 @@ if (fs.existsSync(webRouterSkill)) {
   const body = fs.readFileSync(webRouterSkill, 'utf8');
   for (const phrase of [
     'Explicitly spawn `accessibility-lead` as a Codex custom subagent',
+    "Installing Accessibility Agents for Codex is the user's standing request",
+    'do not request a full-history fork',
     '~/.agents/plugins/a11y-agents-codex/references/specialists/',
     'Dispatch matching Codex custom subagents by default',
     'Do not make users manually name every specialist',
@@ -122,13 +127,17 @@ for (const installerRel of ['install.sh', 'install.ps1']) {
       'max_depth',
       'max_threads',
       'codex-agent-config',
+      'codex-agent-model',
       './a11y-agents-codex',
       'codex-marketplace-repaired',
     ]) {
       if (!body.includes(phrase)) {
         fail(`${installerRel}: missing Codex legacy skill cleanup phrase "${phrase}".`);
       }
     }
+    if (!body.includes('CODEX_AGENT_MODEL') && !body.includes('CodexAgentModel')) {
+      fail(`${installerRel}: missing dynamic Codex agent model variable.`);
+    }
   }
 }