Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools

[phil-cording]

Description

When OpenSpec generates Codex integration files, the generated Codex skills and prompts still reference agent tools that are not available in Codex:

• AskUserQuestion tool
• TodoWrite tool
• Task tool (subagent_type: "general-purpose", ...)

This happens even after upgrading to OpenSpec 1.3.1 and regenerating with openspec update --force.

In Codex, these names are not callable tools. Codex can ask the user in normal chat, and some Codex sessions expose different structured tools such as plan updates or subagents, but those are not named or shaped like the generated instructions. As a result, the generated workflow instructions can cause Codex to attempt unavailable tools or stall around clarification, progress tracking, or sync delegation steps.

Environment

• OpenSpec package: @fission-ai/openspec@1.3.1
• openspec --version: 1.3.1
• Node: v22.16.0
• OS: Windows
• Tool selected: codex
• Delivery mode: both
• Profile: custom
• Workflows: propose, explore, new, continue, apply, ff, sync, archive, bulk-archive, verify, onboard

Reproduction

1. Install or upgrade OpenSpec:

   npm install -g @fission-ai/openspec@latest

2. In a project configured for Codex, regenerate assets:

   openspec update --force

3. Inspect the generated Codex files:

   rg -n "AskUserQuestion|TodoWrite|Task tool|subagent_type" .codex/skills "$CODEX_HOME/prompts"

Actual Behavior

Generated Codex skills and prompts contain non-Codex tool references. Examples from regenerated 1.3.1 assets:

• .codex/skills/openspec-new-change/SKILL.md: tells the agent to use AskUserQuestion tool for open-ended input.
• .codex/skills/openspec-propose/SKILL.md: tells the agent to use AskUserQuestion tool and TodoWrite tool.
• .codex/skills/openspec-ff-change/SKILL.md: tells the agent to use AskUserQuestion tool and TodoWrite tool.
• .codex/skills/openspec-archive-change/SKILL.md: tells the agent to use Task tool (subagent_type: "general-purpose", ...).
• $CODEX_HOME/prompts/opsx-*.md: same references appear in the generated Codex prompt files.

Expected Behavior

Codex-generated assets should avoid tool names that Codex does not expose.

Possible Codex-safe alternatives:

• Replace AskUserQuestion tool with runtime-neutral wording such as: "Ask the user in chat and wait for their reply." For selection prompts, present a concise numbered list.
• Replace TodoWrite tool with runtime-neutral wording such as: "Track progress using the agent's native planning/checklist mechanism if available; otherwise keep a concise visible checklist."
• Replace Claude-style Task tool (subagent_type: ...) wording with either a runtime-neutral instruction to invoke the sync workflow/skill, or a Codex-specific instruction only if Codex support is intentionally added.

Related Context

This seems adjacent to existing Codex/generated-asset issues, but not the same as them:

• /prompt invocation broken in Codex while $skill works #723: /prompt invocation broken in Codex while $skill works
• [Bug] Skills-only delivery emits /opsx:* command references #879 / [Fix] Add transformToSkillReferences for skills-only delivery mode #881: skills-only delivery emits /opsx:* command references

Those issues are about command/skill invocation references. This issue is about generated Codex instructions naming unsupported runtime tools inside the workflow bodies.

[ebarti]

Have you tried setting default_mode_request_user_input = true in your codex's config.toml?

[clay-good]

Cross-linking: PR #1464 removes the last Claude-only tool reference (AskUserQuestion) from the workflow templates themselves, so newly generated Codex assets no longer mention any of the three tools this issue reports (TodoWrite/Task were already removed by #1403). Leaving this issue to PR #1133, which additionally rewrites tool references at the Codex adapter layer.

[clay-good]

Confirmed resolved on current main (45cca5db6137ed209117cc70510eb3e057fb981b). The exact three unsupported Codex tool references reported here have all been removed from the source workflow templates:

• Task tool / subagent_type: #1394 made archive sync run inline and removed the Claude-style task delegation.
• TodoWrite: #1403 replaced it with runtime-neutral checklist guidance.
• AskUserQuestion: #1464 replaced it with runtime-neutral ask-the-user guidance.

I also reproduced the issue's generation path from a clean temporary project using tool=codex, delivery=both, a custom profile, and all 12 current workflows. Current main generated 12 files under .codex/skills/ and correctly skipped Codex prompt commands (Codex uses skills). This exact check returned no matches anywhere in the generated Codex assets:

rg -n "AskUserQuestion|TodoWrite|Task tool|subagent_type|general-purpose" .codex openspec

Focused verification also passes:

pnpm exec vitest run test/core/templates/skill-templates-parity.test.ts test/core/shared/skill-generation.test.ts test/core/init.test.ts

Result: 3 test files passed, 116 tests passed.

The closed #1133 proposed additional adapter-layer rewriting, but that broader defense is no longer needed to resolve this report: clean current-main generation proves the reported output itself is fixed. Closing as completed. Thanks for the precise reproduction and file-level examples — they made this straightforward to verify conclusively.