Skip to content

fix(codex): rewrite unsupported tool references#1133

Open
SIGMAREAL wants to merge 1 commit into
Fission-AI:mainfrom
SIGMAREAL:fix/codex-tool-reference-instructions
Open

fix(codex): rewrite unsupported tool references#1133
SIGMAREAL wants to merge 1 commit into
Fission-AI:mainfrom
SIGMAREAL:fix/codex-tool-reference-instructions

Conversation

@SIGMAREAL
Copy link
Copy Markdown

@SIGMAREAL SIGMAREAL commented May 27, 2026

Summary

  • rewrite Claude-style AskUserQuestion/TodoWrite/Task references when generating Codex prompts
  • apply the same Codex-safe wording to Codex skill generation paths
  • add coverage for the transformer and Codex adapter output

Tests

  • pnpm run lint
  • pnpm test test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts
  • pnpm run build
  • manual Codex init generation grep for AskUserQuestion|TodoWrite|Task tool|subagent_type

Notes

  • pnpm test has one environment-dependent existing failure locally: test/commands/artifact-workflow.test.ts > creates skills for Cursor tool expects .cursor/commands/opsx-explore.md, but my global OpenSpec config is delivery: skills, so that command file is not generated.

Fixes #1103

Summary by CodeRabbit

  • New Features

    • Codex command and skill generation now includes automatic runtime tool reference transformation for improved compatibility across command generation, skill initialization, and skill updates.
  • Tests

    • Added comprehensive test coverage validating tool reference transformation and Codex adapter output formatting.

Review Change Stack

@SIGMAREAL SIGMAREAL requested a review from TabishB as a code owner May 27, 2026 15:00
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 27, 2026

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 86130737-c439-42de-8d35-e7dea848299a

📥 Commits

Reviewing files that changed from the base of the PR and between b1124ea and a51272d.

📒 Files selected for processing (7)
  • src/core/command-generation/adapters/codex.ts
  • src/core/init.ts
  • src/core/update.ts
  • src/core/workspace/skills.ts
  • src/utils/command-references.ts
  • test/core/command-generation/adapters.test.ts
  • test/utils/command-references.test.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • test/core/command-generation/adapters.test.ts
  • test/utils/command-references.test.ts
  • src/core/update.ts
  • src/core/workspace/skills.ts
  • src/utils/command-references.ts

📝 Walkthrough

Walkthrough

This PR adds a transformer that converts Claude-style tool references into Codex-compatible instruction wording, applies it in the Codex command adapter, and wires tool-specific transformer selection into init, update, and workspace skill-generation flows.

Changes

Codex tool reference transformation

Layer / File(s) Summary
Core Codex tool reference transformer
src/utils/command-references.ts, test/utils/command-references.test.ts
transformCodexRuntimeToolReferences performs regex-based rewrites mapping AskUserQuestion/TodoWrite/Task tool phrases and case-insensitive "Use … tool" references into Codex-safe instruction wording. Tests verify transformed output excludes original Claude tool tokens.
Codex adapter applies transformer
src/core/command-generation/adapters/codex.ts, test/core/command-generation/adapters.test.ts
Codex adapter imports and applies the transformer to content.body before interpolating into the markdown template. Adapter test verifies unsupported runtime tool references are removed from formatted output.
Skill generation wires transformer selection
src/core/init.ts, src/core/update.ts, src/core/workspace/skills.ts
Init, update (normal and legacy flows), and workspace skill generation adopt a three-way conditional: codex selects transformCodexRuntimeToolReferences, opencode/pi select transformToHyphenCommands, others use no transformer.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • Fission-AI/OpenSpec#632: Touches Task-tool delegation/sync instruction paths that this PR rewrites for Codex.
  • Fission-AI/OpenSpec#626: Related to the generateSkillContent(..., transformer?) pattern extended here for Codex.
  • Fission-AI/OpenSpec#556: Previously modified the Codex adapter formatting pipeline that this PR now applies the transformer within.

Suggested reviewers

  • TabishB
  • alfred-openspec

Poem

🐰 I nibble through phrases with nimble paws,
Hiding Claude's tool names behind gentle laws.
Ask in chat, make a plan, tick a tiny list,
Codex-safe instructions—no steps are missed.
hops away singing with a carrot twist

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix(codex): rewrite unsupported tool references' accurately summarizes the main change: introducing a transformer to rewrite Claude-style tool names (AskUserQuestion, TodoWrite, Task) in generated Codex prompts and skills.
Linked Issues check ✅ Passed The pull request fully addresses issue #1103 by implementing transformCodexRuntimeToolReferences to replace AskUserQuestion/TodoWrite/Task tool references with Codex-safe wording in generated assets across all skill generation and command adaptation paths.
Out of Scope Changes check ✅ Passed All changes are scoped to implementing the transformer and integrating it into the skill and command generation paths. No unrelated refactoring, dependency updates, or out-of-scope modifications are present.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
test/core/command-generation/adapters.test.ts (1)

324-334: ⚡ Quick win

Add one positive assertion for transformed semantics.

This test only checks removed tokens; it can still pass if the whole line is accidentally dropped. Add one expected replacement assertion (for example, Ask the user in chat...) to lock behavior.

✅ Minimal test hardening
     expect(output).not.toContain('Task tool');
     expect(output).not.toContain('subagent_type');
+    expect(output).toContain('Ask the user in chat');
   });
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/core/command-generation/adapters.test.ts` around lines 324 - 334, The
test "should replace unsupported runtime tool references" currently only asserts
that unsupported tokens are removed; update the test that calls
codexAdapter.formatFile with sampleContent to also assert a positive transformed
phrase is present (e.g., add expect(output).toContain('Ask the user in chat') or
similar) so the test verifies replacement semantics rather than just deletion;
keep existing negative checks for 'AskUserQuestion', 'TodoWrite', 'Task tool'
and 'subagent_type' and add one clear positive assertion referencing the
expected transformed text produced by codexAdapter.formatFile.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/core/command-generation/adapters.test.ts`:
- Around line 324-334: The test "should replace unsupported runtime tool
references" currently only asserts that unsupported tokens are removed; update
the test that calls codexAdapter.formatFile with sampleContent to also assert a
positive transformed phrase is present (e.g., add expect(output).toContain('Ask
the user in chat') or similar) so the test verifies replacement semantics rather
than just deletion; keep existing negative checks for 'AskUserQuestion',
'TodoWrite', 'Task tool' and 'subagent_type' and add one clear positive
assertion referencing the expected transformed text produced by
codexAdapter.formatFile.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 84f7cfe3-11be-4be4-bf3b-aa1d913ea3a1

📥 Commits

Reviewing files that changed from the base of the PR and between fd92ccc and b1124ea.

📒 Files selected for processing (7)
  • src/core/command-generation/adapters/codex.ts
  • src/core/init.ts
  • src/core/update.ts
  • src/core/workspace/skills.ts
  • src/utils/command-references.ts
  • test/core/command-generation/adapters.test.ts
  • test/utils/command-references.test.ts

@SIGMAREAL SIGMAREAL force-pushed the fix/codex-tool-reference-instructions branch from b1124ea to a51272d Compare May 27, 2026 15:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools

1 participant