# `@<agent>` mention in a host agent session doesn't actually delegate

[acer2k-ux]

Codeg version: 0.27.0 (Windows x64)
Reproduction rate: always

Summary

When I write [@Codex CLI](codeg://agent/codex) (or any other registered agent type) at the start of a user message inside a host agent session (the claude_code agent running in codeg), the chip renders correctly, but the work is not handed off to Codex. The host model just keeps answering with its own tools. To the user it looks like @ is silently broken.

Expected

@codex should mean "send this turn to the Codex agent" — i.e. codeg should rewrite the user turn into an internal delegate_to_agent call before the host model sees it, so the host model can't accidentally answer itself.

Actual

• The chip is purely a rendering decoration (refType:"agent", meta:{agentType:"codex"}). No tool call is injected.
• The host model's behavior depends on whether the host chooses to interpret the chip and then call mcp__codeg-mcp__delegate_to_agent itself. In practice, most host models (and Claude in particular) don't recognize the chip as a hard delegation request and just proceed.
• The codeg web UI shows no banner, no error, and no automatic child session is opened.

Why this matters

@codex is advertised as the one-keystroke way to dispatch to another agent. If the host model decides not to call delegate_to_agent, the user sees the chip rendered, watches Claude keep answering, and assumes the dispatcher is broken — when in reality nothing was ever dispatched.

Workaround that I confirmed works (but is not a fix)

When I ask the host Claude explicitly to invoke the MCP tool:

[@Codex CLI](codeg://agent/codex)
Use mcp__codeg-mcp__delegate_to_agent(agent_type="codex", task="<the original request>")

…it works. Two successful test runs from this machine today:

task_id	agent	duration	child conversation	result
88dc974b-91fc-4cd7-8738-a3e7a1611b3b	codex	13.1 s	session 25 (is_delegation_child:true, parent_id:24)	pong
8f074176-3e02-43df-8a59-c7d9239c7d76	codex	8.8 s	session 27 (same parent_id:24)	ok-from-codex-2026\n当前时间：2026-08-22

So the back-end path is healthy. The bug is purely in the front-end "send" pipeline and in how codeg presents the host agent's tool catalogue.

Where I think the fix should live (with evidence from the 0.27.0 build)

1. codeg://agent/<type> chip never triggers dispatch

AppData/Local/codeg/web/_next/static/chunks/*.js defines the mention parser. The relevant excerpt:

// 1d3ab5c0dba16603.js, ~line 102
function a(e) {
  return {
    reference: {
      refType: "agent",
      id: e.agent_type,
      label: e.name || (0, l.getAgentLabel)(e.agent_type),
      uri: `codeg://agent/${e.agent_type}`,
      meta: { agentType: e.agent_type, available: e.available }
    },
    detail: e.description || null,
    keywords: e.agent_type
  };
}

The reference is only metadata. There is no code path in the web bundle that intercepts a submission and converts an agent-type mention into a delegate_to_agent invocation. The same is true in 47adb5e78617c4bc.js, 595d81c8291a19b3.js, 59efecc780f835a3.js, 73f057a387002675.js, 75b92753250a4596.js, 8bb9a50f89269f6f.js, a807d8c0d70d73b1.js, d2915b7267ce3a94.js, e35488615852dbbb.js.

2. delegate_to_agent is conditionally withheld from the host agent's MCP catalogue

Codeg ships its own server-side filter for the MCP tool list advertised to the host agent. The relevant string literals live in codeg-server.exe:

CODEG_ACP_HOST_TOOLS    (occurs at file offsets 44350928, 44506760, 45718128, 45928256)
CODEG_ACP_FS_POLICY     (occurs adjacent)

…and the English-language log messages embedded in the binary read (excerpted from the same offsets):

[ACP] refusing <tool>: env CODEG_ACP_HOST_TOOLS=agent, so this channel was never advertised — the agent must use its own (sandboxable) tools.

[ACP] <FS policy / host tools>: ... confines the fs channel but codeg still advertises "terminal", so an agent reaches the same paths through a shell — this is not a containment boundary. Set CODEG_ACP_HOST_TOOLS=agent to hand file access and commands back to the agent, where its own sandbox applies.

The matching UI strings (from the i18n bundle in the web chunks) make the user-facing contract explicit. Translated from the Spanish/Portuguese source bundles (the English copy is in the same chunks but garbled in this 0.27.0 build):

• hostTools.label — "Let the agent handle files and commands" / 「让 Agent 自己处理文件和命令」 / "Dejar que el agente gestione archivos y comandos"
• hostTools.description — "codeg stops mediating file access and terminal commands, so the agent runs them in its own process where its sandbox and permission rules apply. Delegation to other agents is also disabled, because that would bounce the same work back to codeg. codeg adds no sandbox of its own, so only turn this on if the agent already has one configured."
• multiAgent.enableHint — "When disabled, the delegate_to_agent tool is hidden from the agent's MCP tool catalogue."
• withheldByHostTools — "Agents will not receive the delegation tools because the per-agent 'Let the agent handle files and commands' switch is on."

The environment variable literal used by the UI is also hardcoded in the bundle:

// 5ea88203d02ac8bd.js / 51a5276b8d1ca1f0.js / 9e648820911a721a.js
let ih = "CODEG_ACP_HOST_TOOLS";
let iv = "agent";

…and the Switch that writes it is gated on ib(t2.envText)[ih] === iv, so any agent whose env_json contains CODEG_ACP_HOST_TOOLS=agent loses delegate_to_agent (and get_delegation_status, cancel_delegation) entirely. The persistence target is agent_setting.env_json (table defined in ~/.codeg/codeg.db).

3. Two failure modes I hit during reproduction

• (a) With default settings (agent_setting is empty on a fresh install, hostTools switch is off), delegate_to_agent is present in the host MCP tool catalogue — but the host model still doesn't call it just because of the chip. So default-state codeg is functionally broken even though the tool is technically visible.
• (b) If a user turns the hostTools switch on (e.g. because they read the description and concluded "let the agent handle its own files sounds safer"), delegate_to_agent is silently removed from the catalogue. Now the chip can't be honored even by a model that tries to be helpful — there is no warning that @codex will silently no-op.

Suggested fixes

1. Make @<agent> a real dispatcher, not a decoration.
   When the user submits a turn whose leading mention has refType:"agent" and that agent is enabled && available, intercept the turn before it reaches the host agent: open a child conversation on that agent type, stream delegate_to_agent's progress into the current UI, and only let the host model see the chip if the user explicitly cancels. At minimum, surface a visible banner ("Dispatching to Codex…") so the user knows something happened.

2. Tighten the CODEG_ACP_HOST_TOOLS=agent contract.
   When that env is set, also (a) grey out the @<other-agent> chip in the input box with a tooltip explaining the switch has disabled delegation, and (b) refuse to start a child conversation from inside such an agent with a clear error rather than silently dropping the tool. Today the user gets neither.

3. Default multiAgent.enable to true.
   The Spanish/Portuguese description of enableHint already states the consequence ("delegate_to_agent fica oculta"). Many users — me included — assumed Enable delegation was just a fan-out feature and never thought to toggle it. A first-run toggle with a one-line explanation, or simply defaulting to on, would prevent most of the silent-failure reports.

4. Stop hiding delegate_to_agent from the host catalogue unconditionally.
   Today the filter on the server side is a one-way ratchet: it's hard to know whether a model has it without opening dev tools. Even with CODEG_ACP_HOST_TOOLS=agent, keep delegate_to_agent advertised but make the server return a structured error if the model tries to use it, so the model can at least tell the user what's wrong instead of silently no-op'ing.

Environment

• codeg 0.27.0 (Windows x64, installer codeg_0.27.0_x64-setup.exe)
• host agent: claude_code, model claude-opus-5[1M]
• target agent for reproduction: codex
• agent_setting is empty (no overrides), hostTools switch is off, multiAgent.enable defaults are in effect
• Both delegate_to_agent calls I issued via explicit instruction succeeded; only the chip-driven flow is broken

---

Happy to send a minimal repro recording or to dig further into a specific file offset if it helps — just let me know.

---

Update (2026-08-22, same author) — Root cause of "Codex cannot delegate"

I dug further into the binary after filing this and confirmed the architectural reason session 29's Codex agent has no delegate_to_agent. This is the same class of issue as the original report; codeg's design needs a small extension to fix it.

What's actually happening on the server side

codeg-server.exe contains (at file offset 45937345) the following log string, which I extracted with strings:

[delegation][WARN] codeg-mcp companion binary not found (checked CODEG_MCP_BIN,
exe sibling, and PATH); skipping delegate_to_agent / check_user_feedback /
ask_user_question / get_session_info tool injection for connection <id>.
Reinstall codeg or set CODEG_MCP_BIN to fix.

Reading this together with the codeg-mcp --help output, the design is:

• For every ACP connection (i.e. every agent session codeg itself spawns and connects to over ACP), codeg-server tries to launch the codeg-mcp companion binary as a child process and injects four tools into that session's MCP catalogue — delegate_to_agent, check_user_feedback, ask_user_question, get_session_info.
• The companion binary requires three runtime parameters that only codeg-server knows: --parent-connection-id <uuid>, --socket-path <path>, and --token <secret>.
• If the companion is missing it logs the warning above and skips the injection — silently, from the user's point of view.

So Claude Code works because codeg starts Claude Code over ACP and codeg-server injects codeg-mcp into that ACP connection.

Why Codex is the broken case

The Codex CLI on Windows does not speak ACP. It runs as a standalone OpenAI Codex CLI process (%LOCALAPPDATA%\OpenAI\Codex\bin\<ver>\codex.exe) using OpenAI's own runtime, and reads MCP server configuration from ~/.codex/config.toml ([mcp_servers.<name>]). codeg is, today, just a launching surface for that CLI — it does not run Codex over ACP, so codeg-server never has an ACP connection id to attach codeg-mcp to.

I confirmed this on the machine I'm typing on: ~/.codex/config.toml has [mcp_servers.codegraph] and [mcp_servers.node_repl] registered by other tooling, but no [mcp_servers.codeg] entry. session 29's Codex (GPT-5.6 Sol) correctly reports it has only functions.collaboration.spawn_agent / followup_task / send_message — those are OpenAI Codex's own internal sub-agent tools, not codeg's.

Workarounds I tried (all dead ends)

1. Register codeg-mcp directly in ~/.codex/config.toml:

   [mcp_servers.codeg]
   command = 'C:\Users\Admin\AppData\Local\codeg\codeg-mcp.exe'

   Running the binary by hand immediately exits with codeg-mcp: missing --parent-connection-id / --socket-path / --token. Those three values are runtime-bound to a specific codeg-server session and aren't obtainable from outside the process.

2. Bridge via codeg-server's HTTP/REST surface: codeg-server.exe does not expose HTTP. Tauri commands like list_conversations / create_conversation only exist inside the in-process command dispatcher. There's no published RPC I can call.

3. Reverse-connect to codeg's named pipe: codeg-server.exe references the pipe prefix \\.\pipe\codeg-delegation-<id> (offset 45736541), but only as the server-side binding for its own ACP listener; it doesn't accept inbound client connections from arbitrary external processes, and even if it did, the <id> part is session-bound and not enumerable.

So unless codeg itself is extended to start Codex over ACP (or otherwise inject the codeg-mcp companion into the Codex CLI process), there's nothing a user can do externally. The clean fix lives in this repo.

What I'd like to see

Two viable directions, both of which are additive and shouldn't break existing flows:

Option 1 — Start Codex over ACP too. When codeg launches codex.exe, instead of letting it talk to OpenAI directly, route it through codeg-server via ACP (the same way Claude Code is started today). The existing codeg-mcp injection logic then applies unchanged. This is the smallest, most consistent fix.

Option 2 — Write a codeg-managed entry into ~/.codex/config.toml before launching Codex CLI. Something like:

[mcp_servers.codeg]
command = 'C:\Users\Admin\AppData\Local\codeg\codeg-mcp.exe'
args = [
  '--parent-connection-id', '__PLACEHOLDER__',
  '--socket-path',       '__PLACEHOLDER__',
  '--token',             '__PLACEHOLDER__',
]

…and have codeg-server substitute the three placeholders with the real values before handing the file to Codex CLI (or hand Codex a temporary config that already has them filled in). Codex CLI launches codeg-mcp as a normal stdio MCP server, codeg-mcp connects back to codeg-server, and delegate_to_agent shows up in Codex's tool list just like it does for Claude Code.

Option 1 is cleaner; Option 2 is cheaper and unblocks every ACP-less CLI agent (Codex, Gemini, Hermes, Grok, OpenClaw — codeg's binary already has config writers for all of them, judging by the string table).

Happy to test a build of either approach on this machine.

---

Happy to send a minimal repro recording or to dig further into a specific file offset if it helps — just let me know.