---
name: lhr-use-codex-capabilities
description: Discover and delegate tasks to locally installed Codex skills, plugins, and MCP-backed capabilities. Use when the user explicitly asks to use Codex or a Codex plugin, mentions imagegen/image_gen, or asks Claude Code to choose an appropriate Codex capability automatically.
---

# Use Codex Capabilities

Use the `codex-capability-bridge` MCP tools to route work into Codex. Do not guess that a discovered capability is executable: inspect its runtime status first.

## Routing workflow

1. Call `search_codex_capabilities` with the user's wording and required output type.
2. If the top result is ambiguous or reports a runtime limitation, call `describe_codex_capability`.
3. Call `run_codex_capability` with:
   - the selected capability ID;
   - the complete user task;
   - the current working directory when files should be created there.
4. If Codex requests clarification or additional work, call `continue_codex_task` with the returned thread ID.
5. Report actual artifact paths returned by the bridge. Never claim that an image or file exists unless the bridge returned it or it is present on disk.

## Selection rules

- Prefer exact capability-name matches such as `imagegen`, `browser`, `documents`, or `spreadsheets`.
- Prefer capabilities marked `executable` over metadata-only discoveries.
- Treat host-only capabilities as unavailable from Claude Code unless the bridge reports a tested backend.
- Do not install extra Codex plugins, authenticate accounts, elevate permissions, or change Codex configuration without explicit user approval.
- For file-producing work, use `workspace-write`; otherwise default to the least privilege that can complete the task.

## Example requests

- “使用 codex 的 imagegen 插件生成一张猫咪的图片”
- “使用 codex 的插件生成一张猫咪的图片”
- “让 codex 自动选择合适的能力完成这个 Word 文档”

For the second example, search with both the task text and `outputKind: image`. Select `imagegen` only when the doctor/runtime status says it can be executed in the current environment.

## Failure handling — self-repair loop

Bridge errors include recovery steps in their text. Read the error, execute the suggested verification, then retry. Follow this decision table before asking the user for help:

| Error pattern | Recovery action |
| --- | --- |
| `Unknown capability` with `Did you mean: <ids>` | Retry with one of the suggested ids, preferring an executable match. |
| `Unknown capability` without suggestions | Call `search_codex_capabilities` with the task wording to obtain real ids, then `describe_codex_capability` to confirm before running. |
| Capability name `is ambiguous` | Use one of the full ids listed in the error. |
| `discoverable but not executable` | Call `describe_codex_capability` and check `enabled`/`backend`; if it comes from a disabled plugin cache, tell the user which plugin to enable in Codex, or pick an executable alternative from search results. |
| `No runnable Codex CLI` / `missing required tool` | Call `codex_bridge_doctor`, report the probe result, and relay the suggested environment fix (`CODEX_CLI_PATH`, update Codex) to the user. |
| `Working directory is outside the allowed project roots` | Retry with a `cwd` inside the current project; only suggest `CODEX_BRIDGE_ALLOWED_ROOTS` to the user for paths that must stay outside. |
| `timed out` | Retry once with a smaller or more specific task; if it still times out, tell the user the task needs `CODEX_BRIDGE_TIMEOUT_MS` raised. |
| `continue_codex_task` fails on an old `threadId` | Start a fresh `run_codex_capability` with the full task context instead. |

Attempt at most two self-repair rounds per user request; after that, report what was tried and what is still missing. Never silently substitute an unrelated provider, and never present a catalog entry as a successful invocation.