A sub-agent resolved by name was handed the PARENT's bundle root as its
workdir, so the child booted with the parent's skills and local tools
loaded — a privilege leak across the agent boundary. It reached every
harness: the parent's skills landed on claude-native's `--plugin-dir` and
codex-native's `CODEX_HOME`, and `HARNESS_*_BUNDLE_DIR` pointed the wrapped
harnesses (claude-sdk, codex, pi, cursor, copilot) at the parent's assets.
Provenance. `AgentSpec.source_rel_dir` records the directory each sub-agent
was parsed from, stamped by the parser from the DIRECTORY name and never the
YAML `name` — the two may legitimately differ. The field is `compare=False`
and is never serialized, so spec equality and the on-disk bundle format are
unchanged, and no migration is needed.
Resolution. `_resolve_sub_agent_spec_entry` walks the identity chain from
parent to child, composing one `agents/<dir>` hop per level, and returns the
child's spec and bundle dir together. `ResolvedSpec.workdir` widens to
`Path | None`: anything the resolver cannot prove — a spec unreachable in
the tree (the synthetic `__web_researcher`), an unsafe path segment, a
directory absent on disk — yields `None`, so the child registers nothing
rather than inheriting the parent's bundle. The segment guard is a
component check rather than a substring reject, so a directory legitimately
named `review..worker` still resolves while `..`, `a/b` and absolute paths
do not.
Call sites. Every place that swaps a parent spec for a named sub-agent now
routes through that one resolver: session init, turn dispatch,
`_resolve_session_spec_entry` (the trunk both native terminal ensures ride),
`_resolve_harness_config`, the `/mcp/execute` spec-local tool path, and the
claude/codex terminal-ensure paths. In turn dispatch the entry is re-read
from the spec cache first, and the workdir is swapped BEFORE local-tool
paths are resolved so relative paths root at the child.
Fallback semantics. `_resolved_workdir_for_spec` now honours a wrapped
entry's `None` instead of widening it to the runner workspace. That
distinction is load-bearing: a wrapped entry has been resolved and its
answer stands, while a bare spec never carried bundle information and keeps
the previous `runner_workspace` fallback, so ordinary top-level sessions are
unaffected. Builtin (non-spec-local) tools keep the workspace, which is
correct for them. `ToolManager` accepts a `None` workdir and skips local-tool
registration. `_rewrap_like` carries that same rule at the turn-dispatch cache
write: re-wrap only when the previous entry was wrapped, so a bare spec is not
promoted into a wrapper that would assert a bundle verdict it never had.
The claude-native / codex-native temp-bundle paths are deliberately
unchanged: each already mints a fresh empty dir seeded only with the
framework-owned `build-omnigent` skill, which is not parent content. A test
pins that so the claim stays true.
Docs. Permitting `name != directory` made every doc asserting the opposite
wrong, across four renderings: prose ("must have a corresponding
directory"), path templates (`skills/<name>/SKILL.md`), tree diagrams
(`<skill-name>/`), and the `build-omnigent` generation template, which
reused a single token as directory name, `tools.agents` entry and `name:` —
actively teaching generating agents to derive the path from the name. All
are corrected across AGENTSPEC.md, the validator's prose and error text, the
bundled onboarding skills, the example agents and the docstrings that mirror
bundle layout; `openapi.json` is regenerated for the coupled `schemas.py`
description. Worked examples now demonstrate the independence (`name:
critic` in `agents/code-critic/`) rather than only asserting it. Also
corrected a contradiction found in the same region: only the PARENT needs
the `omnigent` executor — sub-agents may use any executor, which is what
lets one orchestrator drive children across different harnesses.
This change also carries the merge with upstream/main. Upstream added a
`_warn_unresolved_sub_agent` log to the `else` of each sub-agent spec-swap
site; that logging is preserved at all four sites alongside the resolver
call. The resolver returns `None` on a lookup miss and the surrounding code
leaves the parent entry in place, which is exactly the fallback upstream's
message describes, so the warning stays accurate.
Tests cover all 7 harnesses: claude-sdk / codex / pi / cursor / copilot
assert `HARNESS_*_BUNDLE_DIR` is the child dir or absent and never the
parent's, and claude-native / codex-native assert the terminal-ensure
`bundle_dir`. Also covered: the grandchild chain, the synthetic
`__web_researcher`, segment validation, wrapper survival across turn
dispatch's double cache write, child-rooted relative `local_tools` paths,
and the isolated-framework-bundle pin.
Closes#3525
Signed-off-by: Andrew Reid <andrew@reid.ee>
Signed-off-by: Tomu Hirata <tomu.hirata@gmail.com>
Co-authored-by: Tomu Hirata <tomu.hirata@gmail.com>
Andrew Reid
0bea9873e6