Feature: Hierarchical Agent Delegation & Per-Agent Tool Access Control in TOML Configuration

What variant of Codex are you using?

CLI

What feature would you like to see?

Context & Acknowledgment

First, kudos to the Codex team for the recent UX improvements in the TUI. The transition from raw internal identifiers to human-readable agent output has dramatically reduced interface noise — a significant quality-of-life improvement:

Before (≤ 0.104):

• Agent spawned
  └ call: call_L8EBbcS9pdc8StNP7dxUPpAk
    agent: 019c6da1-1521-7f31-9a1f-6c04e2c4fb64
    status: pending init
    prompt: Independent review of changeset ...

• Agent closed
  └ call: call_3638stez6LgpgLvvSHhIDMI2
    receiver: 019c6da1-1521-7f31-9a1f-6c04e2c4fb64
    status: completed

After (0.105+):

• Spawned Maple [fast_builder]
  └ [P07] Ownership: plugin P07 only ...

• Waiting for 21 agents
  └ Oleander [fast_builder]
    Juniper [fast_builder]
    ...

• Closed Peony [fast_builder]

This is a meaningful improvement. While 0.105 is still being finalized, I'd like to propose two features that would further enhance the multi-agent orchestration capabilities.

---

Feature 1: Hierarchical Agent Delegation (Agent-to-Agent Ownership)

Problem

Currently, all spawned agents report directly to the top-level orchestrator. As the number of agents grows (20+), the orchestrator's context becomes saturated — it must track every agent's scope, status, and output simultaneously. This creates a cognitive bottleneck that degrades orchestration quality.

Proposed Solution

Allow agents to be assigned as subordinates to other agents, enabling a tree-structured delegation hierarchy. A "team lead" agent would own and manage a subset of worker agents, keeping the top-level orchestrator's context clean and focused.

How It Would Work

The root config.toml remains unchanged — team leads are defined as regular agents:

[agents.team_lead_tui]
description = "Delegate non-trivial TUI development tasks to this agent"
config_file = "/home/user/.codex/agents/team_lead_tui.toml"

The team lead's own config file (team_lead_tui.toml) then defines its own sub-agents:

model = "gpt-5.3-codex"
model_reasoning_effort = "high"

[agents.tui_core]
description = "Core TUI rendering and layout agent"
config_file = "/home/user/.codex/agents/tui/tui_core.toml"

[agents.tui_input]
description = "Input handling and keybinding agent"
config_file = "/home/user/.codex/agents/tui/tui_input.toml"

Benefits

• Reduced cognitive load per agent — each agent operates strictly within its own scope
• - Clean context windows — agents only see what is relevant to their task
• - - Composable engineering teams — enables end-to-end delivery through structured delegation
• - - - Scalability — orchestrating 50+ agents becomes feasible via hierarchical decomposition

---

Feature 2: Per-Agent Tool Access Control in TOML Configuration

Problem

All agents currently have access to the full tool suite (shell, apply_patch, etc.) regardless of their role. An agent that only needs to review code or generate documentation still has write access to the filesystem — this is both unnecessary and a potential source of unintended side effects.

Proposed Solution

Extend the agent TOML configuration to support explicit tool whitelisting/blacklisting, allowing users to restrict or grant tool access on a per-agent basis.

Example Configuration

# reviewer_agent.toml
model = "gpt-5.3-codex"

[tools]
shell = false
apply_patch = false
read_file = true
list_directory = true

# Or alternatively, a whitelist approach:
# allowed = ["read_file", "list_directory", "search"]

Benefits

• Principle of least privilege — agents only have access to tools they actually need
• - Zero chance of deviant behavior — a read-only reviewer literally cannot modify files
• - - Flexible specialization — users can craft purpose-built agents (reviewer, planner, writer, builder) with distinct capability profiles
• - - - Safer multi-agent orchestration — reduces blast radius of any single agent's actions

Additional information

_No response_