delegation(V1): inject the exact spawn_agent call and model dispatch names so agents stop rediscovering them every session

[lidge-jun]

Problem

On the V1 collab family, every dispatch starts with a discovery detour. The agent is told to call spawn_agent, but it has to work out two things from scratch each session:

1. The exact callable. In native Code Mode the tool is not spawn_agent; it is the deferred nested helper tools.multi_agent_v1__spawn_agent (likewise multi_agent_v1__wait_agent, multi_agent_v1__close_agent, multi_agent_v1__send_input, multi_agent_v1__resume_agent). It is absent from the top-level catalog and from the exec description, so the agent filters ALL_TOOLS, reads the description, then reads the declaration block for the argument shape before it can make the call.
2. The exact dispatch name. When the user says "send a DeepSeek subagent", the agent has to map a family name to a routed model id. Today that means scraping the "Available model overrides" prose in the spawn_agent description (and sometimes ~/.opencodex/config.json) to find command-code/deepseek-deepseek-v4.1-flash.

Observed 2026-09-24 in an OpenCodex Desktop session (Codex 0.155.0-alpha.16.3, codexclaw 0.2.36): answering "can a DeepSeek subagent be dispatched?" took three exploratory exec cells (ALL_TOOLS filter, description read, declaration read) before the one real call:

await tools.multi_agent_v1__spawn_agent({
  model: "command-code/deepseek-deepseek-v4.1-flash",
  reasoning_effort: "low",
  message: "..."
});
// -> { agent_id: "01a0d220-...", nickname: "Laplace" }, completed "OK — deepseek/deepseek-v4.1-flash" in ~4s

The user reports this repeats across sessions.

Related drift

mcp__codexclaw__subagents_get (project scope) returns explorer/reviewer/executor.model = "gpt-5.6-sol", while the same session's spawn_agent description advertises gpt-6-sol / gpt-6-luna. Per DELEGATE-MODEL-LIST-01 the advertised list is not an allowlist, but nothing tells the agent whether the configured role model is still current, so it cannot use the role config as the dispatch name with confidence either.

Where the guidance stops short

• skills/pabcd/references/delegation.md (V1 table) writes spawn_agent({ message | items, model?, reasoning_effort?, fork_context? }) with bare names. It identifies the family but never says how the name reaches you in Code Mode.
• skills/dev/references/native-execution.md says to filter ALL_TOOLS and read the schema, which is correct in general but is exactly the per-session cost for a tool codexclaw already knows it will use.
• The session-start-announcing-subagent-fallback hook already runs at SessionStart and knows the role config, but it does not emit a resolved call template or model aliases.

Proposed fix

1. SessionStart dispatch card. Extend fallback-dispatch-cli.js hook session-start (or add a sibling hook) to inject a short, resolved card for the detected family, for example:

   [codexclaw] Subagent dispatch (V1, multi_agent_v1):
     Code Mode: await tools.multi_agent_v1__spawn_agent({ message, model?, reasoning_effort?, fork_context? })
     Direct:    multi_agent_v1.spawn_agent(...)
     wait:  tools.multi_agent_v1__wait_agent({ targets: [agent_id], timeout_ms })
     close: tools.multi_agent_v1__close_agent({ target: agent_id })
     Model aliases: deepseek -> command-code/deepseek-deepseek-v4.1-flash
                    swe2     -> devin/swe-2
                    kimi     -> kimi/kimi-for-coding-highspeed
                    sol      -> gpt-6-sol   luna -> gpt-6-luna
   

   V2 gets the equivalent card with task_name required and the collaboration namespace spelling.

2. Alias table owned by codexclaw. Resolve aliases from the opencodex catalog when the provider bridge is active (ocx management API or the injected Codex catalog), falling back to a checked-in default map. Record the source and date so a stale alias is visible. Keep DELEGATE-MODEL-LIST-01 intact: the alias is the default for a family name, and a user-supplied full id is still passed through verbatim.

3. Make subagents_get return spawn-ready args. Add a spawnArgs field per role ({ model, reasoning_effort }) plus a staleModel: true flag when the configured model is absent from the live catalog, so role dispatch and the card agree.

4. Doc update. In delegation.md, add one line under the V1 table: "In native Code Mode the callable is tools.multi_agent_v1__<name>; use the SessionStart dispatch card instead of rediscovering it." Point native-execution.md at the card for collab tools.

Acceptance

• A fresh session asked to "dispatch a DeepSeek subagent" makes the spawn call in its first exec cell, with no ALL_TOOLS scan.
• The card names the exact nested helper for Code Mode and the direct name otherwise, for both V1 and V2.
• subagents_get flags gpt-5.6-sol as stale when the live catalog only carries gpt-6-*.
• A test for the hook output covers V1 and V2 cards and the alias fallback when opencodex is not running.

[lidge-jun]

Resolved in v0.2.39 (#246, released from main 8e6aa80).

• Dispatch card at SessionStart. It is injected even when no role has a fallback. SessionStart carries no tool catalog, so the card claims a family only when told to: CODEXCLAW_SPAWN_V1=1 prints the exact tools.multi_agent_v1__spawn_agent/wait_agent/close_agent calls, labeled an override. Otherwise the card gives one Code Mode cell that finds the unique spawn_agent helper, identifies V1 or V2 from companion tools, and spawns: V2 with task_name and fork_turns: "none", so model overrides are accepted. It stops before any call if the helper or the family is ambiguous.
• Model aliases. A dated map (deepseek, swe2, kimi, sol, luna) is marked verified or unverified against the local Codex catalog, so the hook stays local (about 40 ms). A full model id passes through unchanged.
• subagents_get. It returns spawnArgs per role and staleModel (true or false from a fresh catalog; null with a staleReason on timeout, a last-success cache or an unavailable catalog). The catalog read is bounded to 5 s. The MCP server also now answers in request order.
• Docs. delegation.md and native-execution.md point to the card.

Evidence: the card's cell, pasted verbatim into a V1 Code Mode session, spawned command-code/deepseek-deepseek-v4.1-flash in one cell, and the agent answered "deepseek/deepseek-v4.1-flash". The release run measured 3,609 tests with 0 failures.

Two acceptance lines are met differently than written. The spawn happens in the first cell, but that cell still reads ALL_TOOLS unless the override is set. V2 is proven only against a tool harness. Both are tracked in #247.