Capability-Scoped Script Access for Codex

What variant of Codex are you using?

CLI

What feature would you like to see?

Proposal: Capability-Scoped Script Access for Codex

Concept

Codex should let an agent-spawned script talk back to the active session through a short-lived, capability-scoped channel.

This would let the script invoke approved tools, including MCP tool calls specifically, pause for agent judgment at checkpoints, then resume. The goal is to let Codex generate and run task-specific helper scripts without routing every intermediate action through the main transcript/context.

Today, external scripts and session tools are separate tracks. A script can do local work, but it cannot use the active session's MCP tools or hand control back to the agent mid-execution. That makes workflows like pagination, reconciliation, and repetitive checkpointed edits much more expensive in context than they need to be.

Why

• Reduces context bloat for loops, paging, joins, and bulk edits.
• Enables script-driven workflows with agent checkpoints.
• Lets Codex use MCP tools from inside a task-specific script instead of bouncing every call through the transcript.
• Preserves agent judgment for the points that matter while keeping bulk execution local.

MVP

1. codex session grant mints a short-lived token with explicit capabilities.
2. codex.connect(...) binds a script to the active session channel.
3. session.tool(...) lets the script call approved tools, including MCP tools exposed in the active session.
4. session.checkpoint(...) sends a structured question/result back to the agent and waits for a reply.
5. session.summarize(...) promotes selected output into transcript/context.

Examples

Small MCP pagination loop

# Codex writes this script, grants it a scoped token,
# and starts it with CODEX_CHANNEL + CODEX_TOKEN in env.
session = codex.connect(
    channel=os.environ["CODEX_CHANNEL"],
    token=os.environ["CODEX_TOKEN"],
)

for page in range(0, 3):
    rows = session.tool("mcp.Entity_List", {
        "from": page * 50,
        "pageSize": 50,
    })

    if suspicious(rows):
        reply = session.checkpoint("Investigate these rows?", rows[:5])
        if reply.approve:
            session.tool("mcp.Entity_Get", {"id": reply.id})

Small refactor with checkpointed apply

# Codex generates and runs this helper against the active session.
session = codex.connect(
    channel=os.environ["CODEX_CHANNEL"],
    token=os.environ["CODEX_TOKEN"],
)

for path in session.glob("src/**/*.ts"):
    before = session.read(path)
    patch = make_patch(before)

    if patch:
        reply = session.checkpoint(f"Apply patch to {path}?", patch.summary)
        if reply.approve:
            session.tool("apply_patch", {
                "path": path,
                "patch": patch.text,
            })

Cross-source MCP reconciliation

session = codex.connect(
    channel=os.environ["CODEX_CHANNEL"],
    token=os.environ["CODEX_TOKEN"],
)

users = session.tool("mcp.Entity_List", {"entityType": "User"})
schedules = session.tool("mcp.Entity_List", {"entityType": "Schedule"})

orphans = find_orphans(users, schedules)
session.summarize("Orphaned users", orphans[:20])

Required Guardrails

• All child activity should be auditable in-session, including MCP invocations.
• Capabilities should be explicit: MCP/tool access, file read/write, patch, memory, network, sub-agents, call limits, expiry.
• Sensitive actions should still be able to require checkpoint approval.
• Cancellation should revoke the token and stop the child cleanly.
• Re-entrancy rules should prevent recursive agent/script deadlocks.

Core Principle

Scripts should act as scoped executors for the current session, not hidden parallel agents.

Additional information

_No response_