Skip to main content
Glama

Ask Codex (new session)

codex_ask

Run hard reasoning or real coding tasks with OpenAI Codex in a sandboxed session, then continue the thread. Read-only by default; set sandbox="workspace-write" to allow file edits.

Instructions

Best for the hardest reasoning and real code work, behind a REAL OS sandbox (OpenAI Codex, codex exec), in a NEW session. Pass workspace=; without it the sub-agent sees no repo. Follow up with codex_continue. Uses your Codex login (ChatGPT or API key). Read-only by default; sandbox="workspace-write" lets it edit. On Windows the bridge flags refused commands and a silent read-only downgrade with an [agent-intern] WARNING in the answer: treat such an answer as unsourced. Autonomous agent: trusted prompts only.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>"
    },
    "name": "codex_ask"
  }
}

Input Schema

NameRequiredDescriptionDefault
modelNoOptional model override (`-m`); omit to use codex's configured default.
watchNoIf true, open a live "watch" view in your browser that streams codex's steps (reasoning, the commands it runs, file changes) from its `--json` event stream. codex still runs headless; the same final text is returned. Best-effort — if the browser can't open, the run completes normally. Default false.
promptYesQuestion or instruction for Codex.
sandboxNoFilesystem policy, enforced by an OS sandbox: "read-only" (default: reads and answers, writes nothing), "workspace-write" (may edit files in the workspace), or "danger-full-access" (no sandbox, avoid). There is no approval gate, so this is the safety boundary. On Windows, workspace-write runs read-only unless `[windows] sandbox = "unelevated"` is set in ~/.codex/config.toml (see codex_status), and refused commands leave codex answering unsourced; the bridge appends an [agent-intern] WARNING in both cases.read-only
timeout_sNoMax seconds to wait for codex to complete. Default 180.
workspaceNoWorking root for the session (`-C`). Defaults to the server cwd.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.37.1
    • changedInput schema / properties / sandbox / description
      Previous value: -"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1-0.162.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."New value: +"Filesystem policy, enforced by an OS sandbox: \"read-only\" (default:\n     reads and answers, writes nothing), \"workspace-write\" (may edit\n     files in the workspace), or \"danger-full-access\" (no sandbox, avoid).\n     There is no approval gate, so this is the safety boundary. On Windows,\n     workspace-write runs read-only unless `[windows] sandbox =\n     \"unelevated\"` is set in ~/.codex/config.toml (see codex_status), and\n     refused commands leave codex answering unsourced; the bridge appends\n     an [agent-intern] WARNING in both cases."
  2. Changed1 schema field changedv0.33.0
    • changedInput schema / properties / sandbox / description
      Previous value: -"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."New value: +"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1-0.162.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."
  3. Changed1 schema field changedv0.28.0
    • changedInput schema / properties / sandbox / description
      Previous value: -"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately."New value: +"Filesystem policy — \"read-only\" (default: reads and answers but\n     writes nothing), \"workspace-write\" (may edit files under the\n     workspace), or \"danger-full-access\" (no sandbox — avoid). `codex\n     exec` has no interactive approval gate, so this is the real safety\n     boundary; opt into write access deliberately.\n\n     WINDOWS CAVEAT (codex 0.149.1): sandboxed runs there currently\n     refuse EVERY command, both policies, down to `pwd` — codex's\n     policy engine cannot classify the `pwsh -Command <...>` wrapper it\n     builds. Shell commands are how codex reads files, so it sees none\n     of the workspace and ANSWERS ANYWAY, from its own knowledge or a\n     web search, with no hint that it read nothing. The bridge appends\n     a visible \"[agent-intern] WARNING\" to any answer whose run had\n     commands refused: if you see it, treat the answer as unsourced."
  4. Addedv0.12.2

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing the OS sandbox model, that read-only is the default while `workspace-write` permits edits, that there is no approval gate and sandbox is the safety boundary, that it uses the caller's Codex login, and the Windows silent-downgrade pitfall flagged with an [agent-intern] WARNING. These are exactly the operational traits an agent needs before invoking an autonomous coding sub-agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The differentiator (hardest reasoning, real code work, new session, real sandbox) is front-loaded, and the follow-up/workspace guidance comes next. It is dense but nearly every clause carries information; only the Windows WARNING sentence is slightly convoluted and could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter autonomous sub-agent tool with an output schema already describing returns, the description covers the remaining unknowns: session lifecycle, auth, sandbox safety, timeout, and failure modes. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it explains the consequence of omitting `workspace` (no repo visible) and frames `sandbox` as the actual safety boundary with a Windows-specific failure mode. `model`, `watch`, and `timeout_s` are left to the schema's own descriptions, which is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action and backend: delegate a prompt to OpenAI Codex via `codex exec` in a NEW session, positioned as "best for the hardest reasoning and real code work." It explicitly contrasts itself with the sibling `codex_continue` for follow-ups, so an agent can distinguish new-session vs. continuation without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage conditions: use it for hard reasoning/code tasks, always pass `workspace=<project dir>` or the sub-agent sees no repo, and follow up with `codex_continue`. It also warns "Autonomous agent: trusted prompts only." It stops short of saying when to prefer a different vendor's `*_ask` sibling (e.g. claude_ask vs codex_ask), but the when-to-use and the named alternative are both explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.