Skip to content

Commit 7a50143

Browse files
authored
Merge pull request lidge-jun#2750 from lidge-jun/codex/kiro-subagent-delegation-unblock
fix(kiro): let Kiro models discover and keep the code-mode delegation surface
2 parents 7fa587e + 23bb638 commit 7a50143

16 files changed

Lines changed: 1583 additions & 16 deletions
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
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`.
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# wp1 — restore `ALL_TOOLS` discovery for Kiro code-mode turns
2+
3+
Unit: `260827_kiro_subagent_delegation_unblock` · work-phase `wp1`
4+
5+
> **P-phase amendment, 2026-08-27.** The original draft of this document assumed
6+
> the fix had to be a truncation-strategy change inside `truncateDescription()`.
7+
> Re-reading the tree at P found the discovery sentence **already written and
8+
> already shipped** in `src/adapters/tool-catalog-nudge.ts:122`, injected as a
9+
> system nudge that bypasses the 1024 cap entirely — and found that Kiro is the
10+
> one adapter that never enables it. The root cause moved one file; the fix got
11+
> much smaller. The superseded preserve-tail design is kept below as the
12+
> rejected alternative, because the reasoning about *why* the tail matters is
13+
> what led here.
14+
15+
## The one sentence that must arrive
16+
17+
```text
18+
Some deferred nested tools may be omitted from this description. They are
19+
still available on the global `tools` object and listed in `ALL_TOOLS`.
20+
```
21+
22+
~150 chars. Everything the parent needs to discover `spawn_agent` is in it.
23+
A Kiro Claude model currently receives none of it, because the cap keeps the
24+
first 1024 chars of a 5.5 KB description and this sentence is not in that
25+
window.
26+
27+
## Why head-truncation is the wrong shape here
28+
29+
`truncateDescription()` (`src/adapters/kiro-tools.ts:150`) is a pure prefix
30+
slice with a surrogate-safe boundary. It is correct as a byte-safety routine
31+
and wrong as a *documentation* routine: it assumes the first N chars are the
32+
most valuable N chars.
33+
34+
For `exec` that assumption inverts. The head is prose framing ("Run JavaScript
35+
code to orchestrate/compose tool calls"), which the model can infer from the
36+
tool name. The tail carries the discovery contract and the type declarations,
37+
which it cannot infer at all.
38+
39+
## Candidate approaches
40+
41+
### A. Preserve-tail truncation for `exec` only — recommended
42+
43+
Keep the cap. Change *which* 1024 chars survive for the code-mode tool: keep a
44+
head budget for framing, then append the discovery sentence verbatim.
45+
46+
Sketch:
47+
48+
```ts
49+
const KIRO_DISCOVERY_HINT =
50+
"Deferred nested tools are omitted here; they are callable as "
51+
+ "`await tools.<name>(...)` and enumerable via the `ALL_TOOLS` global.";
52+
```
53+
54+
When a description exceeds the limit **and** the original text contains
55+
`ALL_TOOLS`, reserve the hint's length, head-truncate to `limit - hint.length`,
56+
and append. Output stays exactly at the cap, so the wire-size property the cap
57+
exists to protect is unchanged.
58+
59+
- Payload size: identical to today (still capped at 1024).
60+
- Blast radius: only descriptions that mention `ALL_TOOLS` — in practice the
61+
single code-mode `exec` tool.
62+
- Does not touch the prompt, so `tests/kiro-adapter.test.ts:700`
63+
(`not.toContain("### Tool documentation")`) stays green.
64+
65+
### B. Per-tool allowlist limit
66+
67+
Give `exec` a larger cap while every other unverified-model tool stays at 1024.
68+
Simple, but it is a narrower version of the change that previously broke Kiro,
69+
and it needs a live probe per model family to establish the real ceiling. Keep
70+
as fallback if A proves insufficient.
71+
72+
### C. Do nothing in the adapter; fix upstream ordering
73+
74+
Ask for the discovery sentence to move to the top of the `exec` description.
75+
Correct in principle, out of this repository's control, and leaves every
76+
shipped Codex version broken. Rejected as the primary path.
77+
78+
## Chosen path
79+
80+
**A**, with **B** held in reserve.
81+
82+
## Implementation targets
83+
84+
| file | change |
85+
|---|---|
86+
| `src/adapters/kiro-tools.ts` | add discovery-preserving branch inside the truncation path |
87+
| `tests/kiro-adapter.test.ts` | regression next to the existing cap test at :690 |
88+
89+
## Regression contract
90+
91+
The new test must assert all four, or it is not proving the fix:
92+
93+
1. A >1024-char description containing `ALL_TOOLS` still yields
94+
`spec.description.length === 1024` for an unverified model.
95+
2. That output **contains** `ALL_TOOLS`.
96+
3. A >1024-char description **without** `ALL_TOOLS` is byte-identical to
97+
today's behavior (plain head-truncate ending in `…`).
98+
4. `current.content` still does not contain `### Tool documentation`.
99+
100+
Assertion 3 is what keeps this from becoming a general cap change. Drive the
101+
test red once before wiring the fix — a preserve-tail assertion passes
102+
vacuously if the fixture description happens to be under the cap.
103+
104+
## Verification
105+
106+
```bash
107+
bun x tsc --noEmit
108+
bun test tests/kiro-adapter.test.ts
109+
```
110+
111+
Focused per `AGENTS.md`: this is a scoped adapter change, not shared runtime.
112+
113+
## Exit criterion
114+
115+
A live `kiro/claude-opus-5` task, asked what tools it has, names
116+
`multi_agent_v1__spawn_agent` **without being told where to look**. Today the
117+
same prompt returns "No spawn/subagent tool exists in my current tool catalog."

0 commit comments

Comments
 (0)