feat: role-aware sub-agent prompting (built-in contract + per-tier appends)

[hallerite]

Recursive sessions currently prompt every engine identically: a depth-3 leaf gets the same system prompt as the root, and a single append_to_system_prompt applies at every depth. This PR makes prompting role-aware, in two layers.

What this adds

1. A built-in sub-agent framing, gated on depth (zero config). build_system_prompt now takes depth; any depth>0 engine gets its sub-agent identity woven into the prompt's two opening lines instead of the root's plain ones:

You are a coding agent, spawned as a sub-agent: your caller delegated a single task to you and sees none of your work. Do exactly that task; don't widen the scope. [+ tool sentences]

When the task is done, stop calling tools and state your final answer. It is the only thing your caller receives, so make it a complete, self-contained result — the answer plus the evidence needed to trust it (sources, file paths, values).

2. Per-tier append fields (config). The ACP runtime-v1 contract and RuntimeConfig gain subagent_append_to_system_prompt and leaf_append_to_system_prompt alongside the existing append_to_system_prompt. RuntimeConfig.resolved_append_to_system_prompt picks by role, with fallback leaf → subagent → root, so unset fields preserve today's single-append behavior. Children inherit config via model_copy, so every descendant resolves its own tier.

The resulting tiers:

tier	condition	sub-agent framing	rlm hint	append field
root	depth == 0	–	✓ (if max_depth > 0)	append_to_system_prompt
node	1 ≤ depth < max_depth	✓	✓	subagent_append_to_system_prompt
leaf	depth == max_depth	✓	–	leaf_append_to_system_prompt

Rationale

The design splits sub-agent prompting into three concerns, each handled where it belongs:

• Contract — built-in, shared by node and leaf. "Your caller sees only your final message; make it self-contained; stay on the delegated task" is true identically for every sub-agent, so it ships as the default rather than something every host must remember to configure. It lives in the role and final-answer lines (not a separate mid-prompt block) so there's exactly one "You are …" statement and the framing is the first thing the model reads — weaker models overweight the prompt opening.
• Capability — built-in, differs by tier. Nodes get the rlm recursion hint; leaves get no mention of rlm at all. Deliberately no "you cannot spawn sub-agents" line: advertising a missing capability is what caused depth-thrash before this PR — leaves calling rlm(), hitting [depth limit … reached], and burning turns retrying.
• Strategy — config, per tier. How aggressively a node should decompose vs. a leaf should execute-and-report is model- and taskset-dependent, so it stays out of the harness and goes in the appends. That's also the fix for the motivating bug: a delegation-oriented root append used to be injected verbatim into leaves that couldn't act on it. In a search-taskset eval, tiered appends took depth-thrash from 13–27 occurrences to 0 while keeping heavy, load-bearing delegation.

Before/after on SWE-bench Pro

32 stratified tasks (3 per repo across all 11 repos; identical task list in every arm), k=1, three models via Prime Inference, stock harness settings except max_depth=1 and a 1h rollout wall clock. before = main (7eaff71), after = #151 + #166 stacked (c886994). Zero harness errors across ~190 rollouts.

model	arm	n	mean reward	solved	turns/rollout	tokens/rollout
z-ai/glm-5.3	before	32	0.562	18/32	82.8	143k
z-ai/glm-5.3	after	32	0.656	21/32	78.2	141k
deepseek-v4-flash	before	32	0.438	14/32	74.3	123k
deepseek-v4-flash	after	32	0.438	14/32	72.5	111k
kimi-k3	before	31	0.581	18/31	59.3	165k
kimi-k3	after	32	0.594	19/32	57.5	157k

Paired on shared tasks: glm-5.3 3W/0L/29T (sign p=0.25), deepseek 2W/2L/28T, kimi-k3 2W/1L/28T. The after arm is never worse on reward and slightly cheaper on every model (fewer turns and tokens). Individual deltas are within noise at n=32/k=1; the uniform direction across three models is the signal.

One honest caveat for THIS PR: on SWE tasks no model delegates unprompted — exactly one rlm() call occurred across all ~190 rollouts — so the built-in sub-agent contract almost never rendered and this eval is primarily a no-regression check for it. The contract's behavioral evidence is the append-driven redsearcher experiment above (depth-thrash 13–27 → 0).

---

Note

Medium Risk
Changes affect every agent’s system prompt and runtime contract fields; misconfigured tier appends could alter delegation behavior, though fallbacks preserve prior single-append semantics when new fields are unset.

Overview
This PR makes system prompts depend on where an engine sits in the recursion tree, instead of treating every depth the same.

Built-in sub-agent framing (no config): build_system_prompt now takes depth and session_dir. Engines with depth > 0 get a sub-agent role and a stricter “final answer” line (caller-only, self-contained result with evidence). The conversation log path uses the real session directory when available. Kernel guidance is consolidated into KERNEL_PACKAGES_PROMPT (!uv pip install in cells); skill help text is slightly tightened.

Per-tier config appends: The ACP runtime-v1 contract and RuntimeConfig add subagent_append_to_system_prompt and leaf_append_to_system_prompt. resolved_append_to_system_prompt selects root vs node vs leaf append with fallback leaf → subagent → root, so unset tiers keep today’s single-append_to_system_prompt behavior. RLMEngine applies the resolved append when loading the system prompt.

Kernel bootstrap: IPython startup pre-imports asyncio so parallel rlm examples in the prompt work without extra setup.

README documents the new append fields and tier semantics.

^{Reviewed by Cursor Bugbot for commit abc4d2d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9059b73. Configure here.}

[mikasenghaas]

lgtm