Skip to content

Add native specialist roles and delegation limits to CodexProvider - #6138

Open
markstuart-oai wants to merge 2 commits into
feat/simple-codexfrom
feat/bounded-native-children
Open

markstuart-oai wants to merge 2 commits into
feat/simple-codexfrom
feat/bounded-native-children

Conversation

@markstuart-oai

@markstuart-oai markstuart-oai commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This pull request adds optional specialist roles and a cumulative delegation limit to CodexProvider. A limit on open threads alone lets the model close a child and reuse its slot.

from agents.models.codex import CodexChildren, CodexProvider, CodexRole

editor = CodexRole("editor", "Review drafts.", "Suggest a concise edit.")
provider = CodexProvider(children=CodexChildren(roles=(editor,), max_delegations=2))

Select an exact V1 catalog entry with provider.get_model(name). Close the provider with await provider.aclose() when finished. Roles supply instructions. Core's built-in roles remain available, and the model can skip delegation.

Each native model invocation gets a private, ephemeral tree. The root and all descendants share the required max_delegations budget. Before dispatch, the SDK charges each attempt to spawn, resume or send input, including failed calls and repeated IDs. Only the exact V1 wait and close functions are exempt. Closing a child never restores an allowance. max_depth defaults to one generation.

An overrun stops the calling thread before dispatch. The SDK raises RuntimeError after cleanup even if the parent finishes without waiting for that child. Earlier admitted calls can still run.

Neither limit caps model requests or cost. Waiting, model continuations, transport sends and retries can incur additional requests. For a hard request limit, use Agent.as_tool with separate parent and child turn limits and enforce a shared quota before each send and retry.

Children inherit the parent's model and permissions. The profile disables workspace tools and MCP servers. Core can still read local context. SDK tools, handoffs, native tool hooks, V2 and conflicting settings fail before generation. Omitting children preserves ordinary settings, including any delegation already enabled in Core.

Test plan

  • Full SDK verification, including formatting, lint, type checks and parallel and serial tests.
  • Locked Linux build, 17 Rust tests and 24 native child tests. Loopback cases cover nested contention, replacement after close, malformed calls, repeated IDs and a fresh budget on the next invocation.
  • Separate loopbacks for a bundled V1 catalog entry, cancellation cleanup and a child denial without a parent wait.

Checks

  • Added regression tests
  • Ran .agents/skills/code-change-verification/scripts/run.sh
  • Confirmed all required local verification steps passed
  • Completed independent reviews of delegation limits, permissions and cleanup

@markstuart-oai
markstuart-oai requested review from a team, rm-openai and seratch as code owners November 21, 2026 14:22
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-21T15:10:37.243212Z 89c3a08 New commits
🔒 Security Review ✅ Completed 2026-11-21T15:11:18.712650Z 89c3a08 New commits

Security findings

Advisory findings (1)

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🛡️ Codex Security Review · Automatically triggered

Here are some automated security review suggestions for this pull request.

Reviewed commit: 1df5a86ade

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

Comment thread native/codex/src/children.rs Resolved

@jbeckwith-oai jbeckwith-oai left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved after comprehensive static review and two independent reviews. Reviewed Python declarations, native configuration checks, pinned Core role overlays, exact V1 model selection, concurrency/depth enforcement, per-request manager and in-memory store isolation, cross-request resume rejection, and role-file lifetime through tree shutdown. Built-in roles preserve the effective parent restrictions; custom roles add instructions only. No actionable correctness or isolation findings.

Rechecked the cumulative budget advisory. Its mechanics are real: concurrency and depth do not bound cumulative requests, cost, or native internal turns. The API explicitly documents this limitation, and existing Core internal tool loops already span multiple requests within a Runner turn. This approval does not claim a cost budget or restrict selection to declared roles. A cumulative budget is separate hardening rather than a demonstrated violation of this API contract.

Hosted CI is complete: 33 passed and 4 skipped; no failures. Static review only; no candidate code or local tests executed.

@jbeckwith-oai jbeckwith-oai left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved after static re-review and an independent second review. The new tree-wide delegation-attempt budget addresses repeated spawn/close replacement: atomic admission is shared by siblings and descendants, failed calls consume budget, and closing a child does not refund it. Verified the pinned Core interceptor ordering and inherited registry place admission before tool dispatch. Unsupported call forms fail closed, and child-limit errors propagate after joined cleanup even when the parent finishes normally. Reviewed concurrent sibling, failed-call, repeated-ID, no-refund, fresh-tree, and depth regressions. No actionable findings in this increment.

This is a delegation-attempt limit, not a hard model-request or cost limit: waits, model continuations, and transport retries can still issue requests, as the documentation explicitly states.

Hosted CI is complete: 33 checks passed and 4 skipped; no failures. Static review only; no candidate code, local tests, or native builds executed.

This branch has not been deployed

No deployments
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.

2 participants