Proposal: Support custom collaboration modes with configurable request_user_input access

[AmirTlinov]

Summary

Currently, Codex supports two built-in collaboration modes — plan and code — with the request_user_input tool being restricted to plan mode only. This proposal suggests enabling users to define custom collaboration modes via config.toml (or AGENTS.md), each with explicit control over which tools are available — specifically including or excluding request_user_input.

Motivation

The current binary plan/code mode design doesn't fit many real-world workflows. Users have already expressed strong demand for request_user_input availability outside of plan mode (see Related Issues below), and beyond that, there are entire categories of workflows that don't map cleanly to either existing mode:

• Brainstorming / Ideation mode — the agent generates ideas, asks clarifying questions via request_user_input, but doesn't write any code or run commands
• Code Review mode — the agent reads files and asks targeted questions, categorizes issues, but shouldn't modify anything
• Interactive Refactoring mode — the agent proposes changes one-by-one, asks the user to approve each via request_user_input, then applies them
• Architecture / Design mode — the agent plans system design, asks questions about constraints, outputs diagrams or specs (no code execution)
• Triage mode — the agent walks through a list of items (issues, TODOs, files), asks the user to classify each one via request_user_input, then records the result

All of these share a common pattern: they need selective tool access and most critically need request_user_input to function as interactive, conversational workflows.

Proposed Design

1. Custom modes in config.toml

[modes.brainstorm]
display_name = "Brainstorm"
description = "Ideation and planning with interactive questions"
tools = ["request_user_input", "read_file", "list_dir"]
sandbox = "read_only"
system_prompt_append = "You are in brainstorming mode. Focus on generating ideas and asking clarifying questions. Do not write or modify any files."

[modes.review]
display_name = "Code Review"
description = "Review code and ask questions about it"
tools = ["request_user_input", "read_file", "list_dir", "grep"]
sandbox = "read_only"
system_prompt_append = "You are reviewing code. Read files, identify issues, and ask the user targeted questions about design decisions. Do not modify files."

[modes.interactive_refactor]
display_name = "Interactive Refactor"
description = "Propose and apply changes one by one with user approval"
tools = ["request_user_input", "read_file", "write_file", "apply_diff", "shell"]
sandbox = "workspace_write"
system_prompt_append = "For each proposed change: (1) Show the change, (2) Use request_user_input for approval, (3) Only apply after explicit approval."

2. Mode definition schema

Each custom mode should support:

Field	Type	Description
display_name	string	Shown in the mode switcher UI
description	string	Tooltip/help text
tools	string[]	Allowlist of tools available in this mode
sandbox	enum	read_only / workspace_write / full_write
system_prompt_append	string	Additional instructions injected into the system prompt
inherit_from	string?	Optionally inherit from plan or code as a base

3. Interaction with existing modes

• Built-in plan and code modes remain as defaults and cannot be overridden
• Custom modes appear in the mode switcher alongside plan/code
• The collaboration_modes = true config flag could be extended or a new custom_modes = true flag added
• Mode switching mid-session should cleanly replace instructions (see Mixed plan and code mode instructions in resumed threads #10570 for the current bug with mixed instructions)

Use Cases in Detail

Interactive Triage (the killer use case)

As mentioned in the comments on #10384, a common need is interactive item-by-item workflows — the agent asks a question, the user answers, the agent acts, then asks the next question. This is impossible in code mode today because request_user_input is blocked.

With custom modes, this becomes trivial:

[modes.triage]
display_name = "Triage"
tools = ["request_user_input", "read_file", "write_file", "shell"]
sandbox = "workspace_write"
system_prompt_append = "Process items one at a time. For each item: present it, ask for classification using request_user_input, record the result, move to the next item."

Obra Superpowers Integration

Community member @Gamarsoft noted on #10384 that Obra Superpowers heavily relies on custom planning/brainstorming instructions and would benefit from request_user_input in custom skill modes. Custom modes would formalize this pattern.

Technical Considerations

Mode instruction isolation (#10570)

The existing bug where mode switch leaves stale instructions in conversation history becomes even more important to fix before custom modes land. Each mode switch should:

1. Clear previous mode's system_prompt_append from the context
2. Update the tool allowlist atomically
3. Ensure the session JSONL correctly reflects the new mode state

Tool validation

When a custom mode specifies tools = [...], the runtime should:

• Validate that all listed tool names are real, registered tools
• Provide a clear error at startup if a tool name is invalid
• Support MCP tools in the allowlist (e.g., mcp:my_server:my_tool)

Backward compatibility

• Existing plan and code configs remain unchanged
• Users without [modes.*] sections in config see no difference
• The feature could be gated behind custom_collaboration_modes = true initially

Related Issues

• Make request_user_input tool available in code mode #10384 — Make request_user_input tool available in code mode (6 upvotes, open feature request, multiple duplicates marked)
• Make plan-mode-style question mode available to the agent in regular mode #11528 — Make plan-mode-style question mode available in regular mode (closed as dup of Make request_user_input tool available in code mode #10384)
• Continue on Ask Question Tool (request_user_input in Default mode) #11536 — Continue on Ask Question Tool (request_user_input in Default mode) (closed as dup of Make request_user_input tool available in code mode #10384)
• Shouldn't strict the ask user tool to be used only under Plan mode. #11565 — Shouldn't restrict the ask user tool to be used only under Plan mode (closed as dup of Make request_user_input tool available in code mode #10384)
• Mixed plan and code mode instructions in resumed threads #10570 — Mixed plan and code mode instructions in resumed threads (mode switching bug)
• Enable clarifying questions in normal mode (not only Plan Mode) #11266 — Enable clarifying questions in normal mode (not only Plan Mode)

Questions for Discussion

1. Config location — should custom modes live in config.toml, in a separate modes.toml, or in AGENTS.md?
2. Tool allowlist vs blocklist — should modes specify which tools are available (allowlist) or which are blocked (blocklist)?
3. Inheritance — should custom modes be able to extend built-in modes (inherit_from = "code") or always start from scratch?
4. MCP integration — should custom modes support MCP tool references in the tool list?
5. Per-project modes — should modes be definable per-project (in .codex/modes.toml or similar) vs globally?

Would love to hear thoughts from the community and maintainers on this. The core request — making request_user_input available outside plan mode — has clear demand, and a custom modes system would address it in a general, extensible way.

[AmirTlinov]

If this idea aligns with the Codex roadmap and the team finds value in it, I'd be happy to take a stab at implementing it and submitting a PR. Of course, I'd appreciate any guidance on the preferred approach or architectural constraints before diving in — want to make sure it fits well with the existing codebase and the team's vision for collaboration modes.

[Gamarsoft]

Hey @AmirTlinov , thanks for proposing this. As you said I am using Superpowers and it is basically like have all modes at the same time without needing to switch manually between them, the agent switch "modes" using skills, so in my case I would create a "Superpowers" mode with instructions to read superpowers skills. Or I could use a mode where I explicitly instruct to NOT use superpowers skills.

What if we could allocate a subset of skills to specific modes ? In Codex we can already enable or disable skills but I think It is global for all modes.