## Summary
Allow all five shipped agents to inherit an OAuth-backed host model,
including OpenAI Codex, by validating the inherited model binding with
the runtime credential check after parent session overrides.
- Reuse the launcher's inheritance decision in setup and update its
English/Chinese message.
- Preserve raw provider settings, routing, reasoning effort and product
limits. OAuth tokens remain in the host credential store.
- Cover OAuth aliases, access/refresh tokens, missing or malformed
credentials, custom token paths, parent bindings and independent agent
keys. Remove the old API-key-only gate exemptions from the auth contract
test.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Selected regression tests: **321 passed, 48 deselected** on Windows with
Python 3.12. The selection focuses on inheritance and excludes untouched
POSIX permission/pruning scenarios.
```powershell
uv run --no-sync pytest tests/test_config_product_render.py tests/test_subagent_vendored_agents.py tests/test_cli_subagent_setup.py tests/test_provider_auth_method.py tests/test_providers_factory.py tests/test_openai_codex_provider.py tests/test_providers_oauth_login.py tests/test_i18n_prompts.py tests/test_i18n_boundary.py -q -o addopts='' -p no:cacheprovider -k '(not test_config_product_render or inherit_llm or launchers_inherit_oauth or launchers_own_keys or secret_slots or env_wins or dig_and_put) and not prune and not backup and not locks_it_down and not test_a_page_sign_in_runs_the_real_driver_and_leaves_the_token_owner_only' --cov=raven.config.product_render --cov=raven.agent.subagent.vendored_agents --cov=raven.cli.subagent_setup --cov=raven.i18n --cov-branch --cov-report=json:C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_final.json --cov-report=term-missing:skip-covered
```
The following checks passed: Ruff across the repository, formatting
(2149 files), relevant type checks, all 10 import contracts, commit
messages, source language and file/asset checks.
```powershell
uv run --no-sync ruff check raven evolver agents plugins-dist tests scripts docs-site
uv run --no-sync ruff format --check raven evolver agents plugins-dist tests scripts docs-site
uv run --no-sync ty check raven/config/product_render.py raven/agent/subagent/vendored_agents.py raven/cli/subagent_setup.py
uv run --no-sync lint-imports
uv run --no-sync python scripts/check_commit_messages.py main..HEAD
uv run --no-sync python scripts/check_source_language.py main..HEAD
uv run --no-sync python scripts/check_large_files.py main..HEAD
```
Changed-line coverage: **100% (22/22 executable lines)** after
normalizing the Windows report's path separators.
```powershell
uv run --no-sync python -c "import json,pathlib; p=pathlib.Path('C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_final.json'); d=json.loads(p.read_text(encoding='utf-8')); d['files']={k.replace(chr(92), '/'):v for k,v in d['files'].items()}; p.with_name('raven_issue809_coverage_posix.json').write_text(json.dumps(d), encoding='utf-8')"
uv run --no-sync python scripts/coverage_gate.py --coverage-json C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_posix.json diff --base-ref main --head HEAD --threshold 90
```
Full local CI remains unverified: `make ci` could not run because make
is unavailable. Existing POSIX file-permission tests fail on Windows.
`uv run --no-sync deptry raven` reports 12 missing optional channel
dependencies in this environment.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Inheritance now refuses an unavailable selected model even when an
unrelated provider has an API key. API-key and independent-agent-key
paths remain covered. Credential validation only reads stored OAuth
credentials; it does not sign in or serialize tokens. Revert this change
to restore the previous inheritance gate.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes #809
---------
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: KT <74288668+0xKT@users.noreply.github.com>
agents/
Agent definitions built on installed raven, serving over raven acp.
Five shipped agents today: raven-code, raven-design, raven-oncall,
raven-ppt, raven-research. A new agent starts as raven agents new <name>
-- the scaffold command that instantiates this whole shape into a fresh
folder; BUILDING.md in this directory is the from-zero guide.
Agents that have no model key of their own inherit the host's model binding,
provider configuration, routing and reasoning effort. Inheritance uses the
same credential check as the host runtime, including stored OAuth sign-ins
such as OpenAI Codex. The child reads OAuth credentials from the host's
RAVEN_HOME (or the provider's configured token-directory override); tokens
stay in that credential store rather than the rendered agent config.
What one agent directory carries:
-
run.py-- a stdlib-only launcher: render the agent's config (secret slots, host LLM inheritance, mode catalogue), then execpython -m raven acp --config <rendered>on the installed raven. -
config.json-- the baseline profile. -
modes/*.json-- optional per-session overlays, surfaced asacp.modesfor a client's mode picker (research,raven-oncall, andcodeship one today). An agent that ships nomodes/renders noacpblock, and the raven it execs then falls back to its own three built-in tiers -- sosession/set_modeanswers with those rather than method-not-found. An overlay'sagents.defaults.reasoningEffortis lifted onto the mode entry as the trunk'sreasoningEffortknob; the rest of an overlay is the agent's own hooks' to read. -
subagent.json-- the roster row templateinstall.pyregisters throughraven.config.update_subagents(the same pinned surface the retired vendored installers used). The inverse is the uninstall story -- delete the roster row with the interpreter that serves raven:# Unquoted on purpose: the shebang may be an `env` line, which is two words. $(sed -n '1s/^#!//p' "$(command -v raven)") -c \ 'from raven.config.update_subagents import remove_third_party_subagent as rm; print(rm("raven-code"))'The folder itself can stay -- an unregistered folder is inert. A live raven holds the roster it read at startup; restart it afterwards. Two manifest fields shape how the row is reached rather than what it runs:
"hidden": truekeeps the row off the roster the dispatching model reads (and off the WebUI's sub-agent page) while a task routed to it still runs there;"routes": [{"to": "<name>"}, ...]makes this row's backend a routing entry (agent/subagent/backends/routing.py): every caller --spawn, a DAG node, a direct chat -- runs the row, and the entry picks the implementation onrun, reading the task as the model wrote it (authored_task), never the rendering with file contents inlined. A reused instance handle stays where its transport bound it; otherwise the host's own model picks between the targets' roster lines and this row. A fronting row is only as ready as its targets: a route to a folder that is missing, unready or switched off disables the row with the reason on it, so a half-installed agent does not run the missing half's work on the wrong implementation. A route entry may also carry"owes"and"note": what the work still owes when the entry keeps it on this row instead of sending it, and what to tell this row's own implementation when that happens, appended to the task under a[host]marker. Both are the row's words, because the gate that closes a route serves every row that declares one; a route that declares neither hands the task over exactly as it arrived. Prose past a sentence goes in"noteFile": "<name>.md"beside the manifest instead -- discovery reads that file intonote, so a requirement long enough to be worth writing stays reviewable as a diff; declaring both is refused. What puts a route under that gate at all is its own declaration, and the three parts are independent:"needs": ["image_generation", "image_search"]names what the target's own pipeline cannot work without,"needsFile": ".pptx"a file the user attached that the dispatch hands over (a direct chat's media, or an attachment of the turn that the spawn task names -- a path in the text alone is not one) for the route to open, and"minTier": "max"the lowest tier the route may open at. A route naming none is dispatched exactly as routes were before the gate existed -- never probed, never asked for a file, never tiered -- becauseroutesis a general facility and a row routing for reasons of its own must not inherit conditions it never asked for. The names inneedscome from a closed vocabulary (ROUTE_REQUIREMENTS), since the host is what answers them; one outside it is warned about and treated as met, so a manifest written for a later raven keeps its route on an older one. And the probe answers for the target's lane, reading the product folder's own.envfirst (PPT_SERPER_API_KEY,PPT_IMAGE_API_KEY) and falling back to the host sections the launcher would inherit -- the host's own credentials answer for the host loop, and a lane is free to be equipped differently. It follows the launcher one branch further than the explicit keys: with no image key anywhere and an OpenRouter endpoint, the key paying for the lane's words pays for its pictures, so a folder holding onlyPPT_API_KEYstill counts as able to draw -- and towards any other gateway it does not. All four fields are manifest facts: a stored row takes them from the folder on every merge.raven-pptships hidden behindraven-design's routes, so the model sees one design agent and decks still build on the deck engine, its own model and key; the two halves share one everos identity (raven-design), so what the user says over a deck is remembered for the next design turn. ItsPPT_API_KEYis configured throughraven subagents setupor the folder's.env, since the page no longer lists it. -
plugins/<id>/-- the agent's own harness as raven plugins: hooks on the loop's six phases, replacement tools under the built-in names, its own config slice underplugins.config["<id>"].run.pynames the directory throughplugins.dirs; nothing inraven/knows the plugin exists. An agent's harness may instead ship as a standalone distribution:raven-pptandraven-designcarry noplugins/directory -- their engines are theplugins-dist/ppt-engineandplugins-dist/design-enginewheels, found through theraven.pluginsentry-point group. Each engine underplugins-dist/belongs to its agent -- but an entry-point plugin withenabled_by_default = trueACTIVATES in every raven process in the environment; staying out of the host's and the sibling agents' turns is the engine's own duty, done by factories that decline when their config slice is absent (what the scaffold's engine templates do), or by the operator'splugins.disabledlist. Prompt assets ride with the plugin whose conduct they teach, underplugins/<id>/prompts/: the workspace guiderun.pyseeds once (oncall's TOOLS.md section, code's whole-file TOOLS.md) lives there.raven-codealso seeds its identity assoul.md(besiderun.py, the raven-research shape) and a coding conduct asagent.md(one variant per model family, the fork's split; a partition still carrying the other variant or older managed seed is refreshed, an operator's edit never is), and its code-flow hook contributes the working directory's own instruction files (AGENTS.md/CLAUDE.md/CONTEXT.md, the slice'sprojectFiles) to each turn's system message through the context assembler, without rewriting the query. The same plugin carries one more surface:code-flow/code_flow/tools/-- the product's own tool face, contributed by the same plugin: the fork's spelling (file_path/old_string, with the host's names accepted as aliases),glob,todo. Four of them ride the built-in names, which is how a product serves its own file tools without touchingraven/agent/tools/or the four other products that share it: plugin tools register last and a same-name registration replaces the built-in instance, so the model is only ever shown this one. Disabling the built-in name instead is not the same thing -- withholding is by name and would take the replacement with it. The face is a section of the flow slice (tools), with its own switch and arestrictToWorkspacethe launcher renders from the product'stoolsblock: a plugin factory cannot read that field, and a replacement built without it is fenceless whatever the product asked for. The ask tier is decided per hosting, not product-wide: the ACP hosting keeps trunk'sask(raven dispatching a sub-agent answers those prompts itself, and a person in an editor should still be asked), and the one-turn CLI hosting renderspermissions.mode: fullbecause that hosting has no channel to ask on -- with the default it refused every write and the model reported the task incomplete.
-
soul.md+ the contract the plugin renders intoagent.md-- optional: the agent's own identity, seeded into the workspace once, for an agent that replaces the host identity (research does; itscontext.dropSegmentskeeps the host's own identity segment out of the prompt). An agent whose vendored twin served the host-generic identity carries nosoul.mdand keeps the host identity segment -- oncall and design: each of those forks' SOUL.md is byte-identical to trunk's own template, its ACP path never seeded it into a workspace, so an added identity file would change the very prompt face the parity tests pin.raven-codeis the exception with a reason: its one-turn CLI hosting runsraven agent, whose workspace sync writes trunk's templatesoul.md-- a personal assistant with a personality -- in front of the coding conduct, while its ACP hosting (no sync) read none; seeding its ownsoul.mdfirst gives both hostings one identity and keeps the host identity segment.raven-pptalso carries nosoul.md, for a different reason: its fork's SOUL.md is its own, and it rides byte-for-byte at the engine wheel's prompts home (raven_ppt/prompts/), seeded into the pinned home by the engine plugin's hook at first turn.
Agent vocabulary:
- Rendered config -- what
run.pywrites and execs against: the baselineconfig.jsonafter secret slots, host LLM inheritance and the mode catalogue are applied. Rendered files live under the state root, never in the agent directory. - State root -- where the agent keeps its work (repos, instance
buckets, flow stores, rendered configs):
product_state_root()inraven/config/product_render.py, default<raven home>/workspace/subagent_sessions/<agent>, overridden by the agent's*_STATE_ROOTvariable. - ACP home -- the engine's own Agent home,
product_acp_home(): under the raven data directory, never inside the host's Agent home (the host hands its home out as a session working directory, and a raven engine refuses a working directory that contains its own home). The agent's*_ACP_HOMEvariable overrides it outright. - Tool-face pin -- each launcher test pins the exact tool face the
rendered config exposes (
VENDORED_TOOL_FACEintests/test_agents_<agent>_launcher.py) to its vendored twin's face. - Seed-once -- workspace assets (guides, identity) are written only when
absent (
seed_once()inraven/config/product_render.py), so a user's later edits survive relaunches.
Agent notes:
raven-designgives each session its own working directory under<workdir>/designs/<session-slug>-<hash>/, following the deck agent's per-session directory mechanism. The hash uses the full session key so channel names, normalized characters and truncated names remain distinct. Task State is still stored under the configuredtaskState.stateRoot, keyed by this session directory; relative file and render paths use the same directory. The reply ends with that directory's absolute path and the note that its paths resolve against it: a caller dispatched the run into the directory above, which is what its dispatch receipt names, so it would otherwise resolve the reply's relative paths one level too high and deliver nothing. A symlink used asdesigns/or as the session directory stops the turn before model or tool execution, preserving the original working directory's access boundary. The caller's working directory may itself be a symlink; its resolved location is the root. Resuming a session with the same working directory returns to its files and Task State. Setplugins.config["design-engine"].workdirPerSessiontofalseto keep the caller's directory directly. Existing files and Task State from the shared directory are left there: their owning session cannot be inferred safely.raven-ppt(the deck agent) needs the ten bundled templates theppt-engineplugin offers, and gets them from the clone: they are tracked underplugins-dist/ppt-engine/raven_ppt/assets/templates/, which the editable install serves and the ppt-engine wheel bundles. Nothing to fetch and no token to hold -- the registry they used to be fetched from is private, and requiring it left an outside install with an empty catalogue and a wheel carrying zero templates.plugins-dist/ppt-engine/templates.manifest.jsonstill pins every file by sha256;make verify-templateschecks the tracked copies against those pins,make fetch-templateslands a fresh cut over them (maintainers,GITLAB_TOKEN), and release.yml refuses a wheel that does not carry all ten.
Ground rules:
- The A side of the comparison is the retired vendored tree: byte snapshots
of its record live under
tests/fixtures/vendored_fork/, and the full trees remain in git history (the commit that removedsubagents/is the anchor). Nothing here may re-grow a dependency on that tree. - The runtime never imports this directory -- enforced by the import-linter contract "the runtime does not import the agents pilots".
- In the wheel as data, never as code:
hatch_build.pymaps the tracked files toraven/agentsfor the roster's file-level discovery, and the import-linter contract still keeps the runtime from importing any of it. - Acceptance for a shipped agent is transport-face equivalence against its vendored twin: transcript shape, timeout semantics, everos records field by field.