|
| 1 | +# Kiro subagent delegation — unblock parallel spawning |
| 2 | + |
| 3 | +Unit: `260827_kiro_subagent_delegation_unblock` · opened 2026-08-27 |
| 4 | + |
| 5 | +## Owner decision that scopes this unit |
| 6 | + |
| 7 | +Two things that look like defects are deliberate and stay: |
| 8 | + |
| 9 | +- The **1024-char description cap** for unverified Kiro models is intentional. |
| 10 | + Raising it broke Kiro before (see "Why the cap exists"), so this unit does not |
| 11 | + raise it as a blanket change. |
| 12 | +- The **5-model `spawn_agent` override list** is intentional |
| 13 | + (`MAX_MODEL_OVERRIDES_IN_SPAWN_AGENT = 5`). Not a bug, not in scope. |
| 14 | + |
| 15 | +What the owner *does* want: **Kiro subagents allowed to spawn in parallel, |
| 16 | +without a depth ceiling.** That is the goal of this unit. |
| 17 | + |
| 18 | +## Symptom (measured, not inferred) |
| 19 | + |
| 20 | +A top-level `kiro/claude-opus-5` task reports that no delegation tool exists: |
| 21 | + |
| 22 | +> No spawn/subagent tool exists in my current tool catalog. |
| 23 | +
|
| 24 | +It then lists a 26-name top-level surface with no `spawn_agent` in it. The tool |
| 25 | +is in fact registered — a forced `ALL_TOOLS` probe in the same session found |
| 26 | +`multi_agent_v1__spawn_agent` at 6598 chars with `model`, `reasoning_effort`, |
| 27 | +and `service_tier` all intact. |
| 28 | + |
| 29 | +So the capability is present and the model cannot see it. |
| 30 | + |
| 31 | +## Mechanism |
| 32 | + |
| 33 | +> **Superseded by the P-phase re-read. See `011_root_cause_nudge_gap.md`.** |
| 34 | +> The truncation described below is REAL and measured, but it is the second |
| 35 | +> line of defense, not the cause. The actual cause is that |
| 36 | +> `src/adapters/kiro.ts:477` omits the optional `codeModeExecName` argument, so |
| 37 | +> `codeModeExecWireName()` returns `undefined` and Kiro receives a generic |
| 38 | +> fallback sentence that never names `ALL_TOOLS` — regardless of any cap. |
| 39 | +> This section is retained because the truncation evidence is what located the |
| 40 | +> gap, and because the cap would re-break discovery if the nudge ever regressed. |
| 41 | +
|
| 42 | +Codex code mode does not advertise `spawn_agent` at the top level. It defers the |
| 43 | +nested tools and tells the model where to look, inside the `exec` tool |
| 44 | +description: |
| 45 | + |
| 46 | +> Some deferred nested tools may be omitted from this description. They are |
| 47 | +> still available on the global `tools` object and listed in `ALL_TOOLS`. |
| 48 | +
|
| 49 | +That sentence sits past the 1024-char mark. `toolDescriptionLimit()` in |
| 50 | +`src/adapters/kiro-tools.ts:143` gives 9216 chars to `gpt-5.6-sol` and 1024 to |
| 51 | +every other Kiro model, so a Claude-family Kiro model receives `exec` truncated |
| 52 | +at exactly 1024 chars ending in `…`. |
| 53 | + |
| 54 | +Confirmed from inside the Kiro session: |
| 55 | + |
| 56 | +| probe | Kiro model sees | control (native) | |
| 57 | +|---|---|---| |
| 58 | +| `exec` description length | ~1010-1020, ends `…` | full | |
| 59 | +| contains `ALL_TOOLS` | NO | YES | |
| 60 | +| contains `Some deferred nested tools…` | NO | YES | |
| 61 | +| contains `Shared MCP Types` / `declare const tools` | NO | YES | |
| 62 | + |
| 63 | +The failure chain, as corrected at P: |
| 64 | + |
| 65 | +```text |
| 66 | +kiro.ts:477 omits codeModeExecName |
| 67 | + -> codeModeExecWireName() returns undefined |
| 68 | + -> generic fallback replaces the ALL_TOOLS sentence in the system nudge |
| 69 | + -> (and independently: exec's own description is cut at 1024, removing it there too) |
| 70 | + -> model concludes no spawn tool exists |
| 71 | + -> zero delegation attempts, no model/effort/tier override ever formed |
| 72 | +``` |
| 73 | + |
| 74 | +The model is not misreading the spawn schema. It never learns the schema is |
| 75 | +reachable. |
| 76 | + |
| 77 | +## Why the cap exists (do not regress this) |
| 78 | + |
| 79 | +`devlog/_fin/143_kiro-gateway-parity/125_phase_tool_fallback_hardening.md` |
| 80 | +originally moved long descriptions **into the system prompt** and left a pointer |
| 81 | +in the tool spec. That was later replaced: `tests/kiro-adapter.test.ts:690` is |
| 82 | +now named *"tool descriptions use deterministic model-specific caps **without |
| 83 | +prompt injection**"* and asserts `current.content` does **not** contain |
| 84 | +`### Tool documentation`. |
| 85 | + |
| 86 | +So there are two rejected designs already on record: |
| 87 | + |
| 88 | +1. Send the full long description to Kiro — the reason the cap was added. |
| 89 | +2. Relocate it into the prompt — explicitly reverted; the test now guards |
| 90 | + against it. |
| 91 | + |
| 92 | +Any proposal in this unit that reintroduces either is out of bounds. |
| 93 | + |
| 94 | +## Design constraint that follows |
| 95 | + |
| 96 | +> **Superseded.** This section reasoned toward a truncation-strategy fix inside |
| 97 | +> `kiro-tools.ts`. The implemented direction is `011`: pass `codeModeExecName` |
| 98 | +> at the nudge call site, which delivers the discovery contract as system text |
| 99 | +> and never touches the cap. |
| 100 | +
|
| 101 | +The reasoning is kept because its conclusion still holds and still constrains |
| 102 | +the unit: the load-bearing content is ONE sentence (`ALL_TOOLS` discovery), not |
| 103 | +the 5.5 KB of type declarations around it. That is why a system-nudge delivery |
| 104 | +works — it carries the sentence without carrying the payload. |
| 105 | + |
| 106 | +It also names the residual risk `012` records: the nudge is truncated from the |
| 107 | +TAIL under budget pressure, and the code-mode sentence sits late in it. Today |
| 108 | +there is ~10 KB of headroom, so the risk is dormant, not absent. |
| 109 | + |
| 110 | +## Work phases |
| 111 | + |
| 112 | +| phase | file | scope | |
| 113 | +|---|---|---| |
| 114 | +| wp1 | **`011_root_cause_nudge_gap.md`** | pass `codeModeExecName` at Kiro's nudge call site so the shipped `ALL_TOOLS` sentence reaches Kiro | |
| 115 | +| wp2 | `020_unbounded_kiro_delegation.md` | remove the depth-1 ceiling for Kiro parents (host config, not code) | |
| 116 | +| wp3 | `030_verification.md` | live proof + full gates + PR against `dev` | |
| 117 | + |
| 118 | +`010_exec_discovery_preservation.md` is **superseded** by `011`. It is retained |
| 119 | +for its reasoning about why the description tail matters, which is what led to |
| 120 | +finding the real call-site gap. Do not implement from `010`. |
| 121 | + |
| 122 | +wp1 is a prerequisite for wp2. Lifting the depth ceiling changes nothing while |
| 123 | +the parent still believes the tool does not exist. |
| 124 | + |
| 125 | +## Non-goals |
| 126 | + |
| 127 | +- Raising `MAX_KIRO_TOOL_DESCRIPTION_UNVERIFIED` as a blanket change. |
| 128 | +- Changing `MAX_MODEL_OVERRIDES_IN_SPAWN_AGENT`. |
| 129 | +- Reintroducing tool documentation into the Kiro system prompt. |
| 130 | +- Touching `multi_agent_version` catalog pins — `kiro/claude-opus-5` already |
| 131 | + pins `v1` correctly in both `~/.codex/models_cache.json` and |
| 132 | + `~/.codex/opencodex-catalog.json`. |
0 commit comments