Skip to content

docs(adr): fullsend-owned mechanism for Codex sub-agents - #7827

Merged
waynesun09 merged 29 commits into
fullsend-ai:mainfrom
dhshah13:docs/adr-0126-codex-child-policy
Oct 1, 2026
Merged

waynesun09 merged 29 commits into
fullsend-ai:mainfrom
dhshah13:docs/adr-0126-codex-child-policy

Conversation

@dhshah13

@dhshah13 dhshah13 commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

ADR 0126 decides whether Codex review and retro get native child agents, and under what policy. Docs only. #7809 and fullsend-ai/agents#1542 are closed; the implementation follows as small PRs after this is decided.

Related Issue

Part of #6970. It decides the approach but does not close the issue.

Related: ADR 0112 in #7808 rejects routed subagents keys on codex because it has no persona roster.

Changes

  • docs/ADRs/0126-fullsend-owned-codex-subagents.md: new ADR.
  • docs/architecture.md: one Decided line under the runtime section, marked not yet implemented.
  • docs/ADRs/0104-per-persona-model-resolution.md and docs/ADRs/0100-codex-sandbox-hooks.md (Accepted): each adds a two-line cross-reference to 0126 under Status. Their Context, Decision and Consequences sections are unchanged.

Questions for review:

  1. Is it worth an ADR? On Codex it departs from ADR 0104: persona model: and tools: are not applied, the child model chain is the one decided on codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970, and unregistered roles are always rejected. If it's rejected, review and retro stay single-context on Codex, as they are today.
  2. Is a spawn-time digest check worth keeping? Within an iteration the parent can rewrite the hook adapter itself, so the check adds coverage only against a mid-iteration role or hooks.json edit that leaves the adapter untouched. Option 4, write protection through Landlock, a read-only OpenShell path or image-baked roles, closes the residual and would be a separate ADR.
  3. Who delegates? As codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970 plans it and as on Claude Code and pi: every agent with the Agent tool, which includes code and fix, when harness security is enabled. The alternative is opt-in through subagents.
  4. Is V1 only acceptable? A parent Codex resolves to collaboration V2 gets the multi-agent tools turned off at Bootstrap and runs in one context (a new restriction: today a V2 parent has collaborationspawn_agent with no policy on it, which fix(codex): turn off codex's native multi-agent tools #7829 turns off); an entry without a version takes V1 from Codex's multi_agent feature, on by default. On rust-v0.159.3 (the sandbox pin since chore(deps): update dependency @openai/codex to v0.159.3 #7747) that leaves gpt-5.6-luna and gpt-5.5 as delegating parents; every gpt-6 model and the other gpt-5.6 tiers run in one context, the main outcome at the pin.

Testing

  • make lint passes

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO) — human and human-directed agent sessions only
  • I wrote this contribution myself and can explain all changes in it

🤖 Generated with Claude Code

Record the decision fullsend-ai#6970 needs before any implementation: Codex review
and retro children run under roles and models the runner provisions, a
mandatory dispatch hook that admits only fresh-context V1 spawns of
registered roles, and a spawn-time digest check on the hook and role
files. Write protection of those files is an option, not chosen.

Cross-reference the new ADR from the Accepted ADR 0104, whose persona
frontmatter the Codex policy does not apply.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@dhshah13
dhshah13 requested a review from a team September 29, 2026 12:59
@github-actions

Copy link
Copy Markdown

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer with write access must add the ok-to-test label after the latest push.

See E2E testing guide for details.

@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Document runner-owned policy for native Codex child agents

📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Accept an ADR defining runner-controlled roles, model resolution, and dispatch checks for Codex
 children.
• Record Codex-specific departures from persona policy and the remaining file-integrity race.
• Cross-reference the decision from the existing ADR and runtime architecture guide.
Diagram

graph TD
  B["Runner Bootstrap"] --> R["Registered Roles"] --> H["Dispatch Hook"] --> V{"Fresh V1 spawn?"} --> C["Codex Child"]
  B --> D["Runner Digests"] --> H
  P["Codex Parent"] --> H
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Keep Codex single-context
  • ➕ Requires no new dispatch controls.
  • ➖ Review and retro remain without independent child contexts on Codex.
2. Govern native children through instructions
  • ➕ Avoids runner-provisioned roles and a mandatory hook.
  • ➖ Cannot enforce fresh context, role selection, or model choice.
3. Add write protection to the chosen policy
  • ➕ Closes the documented check-to-load integrity window.
  • ➖ Introduces platform or release constraints that warrant a separate decision.

Recommendation: The runner-owned role and dispatch policy is the best fit for enforced native delegation without adding a platform requirement now. Reviewers should explicitly accept or reject the documented check-to-load residual before implementation proceeds.

Files changed (3) +91 / -0

Documentation (3) +91 / -0
0104-per-persona-model-resolution.mdCross-reference the Codex-specific child policy +3/-0

Cross-reference the Codex-specific child policy

• Adds a Status-section link to ADR 0126 without changing ADR 0104's existing decision.

docs/ADRs/0104-per-persona-model-resolution.md

0126-runner-owned-codex-child-policy.mdDefine the native Codex child-agent policy +87/-0

Define the native Codex child-agent policy

• Accepts runner-provisioned roles and model resolution with a mandatory hook restricting spawns to registered, fresh-context V1 children. Compares alternatives and records Codex-specific persona behavior, delegation limits, and the remaining check-to-load race.

docs/ADRs/0126-runner-owned-codex-child-policy.md

architecture.mdAdd the Codex child policy to runtime architecture +1/-0

Add the Codex child policy to runtime architecture

• Adds a Decided entry summarizing Bootstrap role provisioning, mandatory dispatch checks, and the ADR reference.

docs/architecture.md

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:01 PM UTC · Completed 1:20 PM UTC

Commit: ba5f4e7 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $4.97

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://75bb427b-site.fullsend-ai.workers.dev

Commit: 6c0ad3a0d625f1cdf8d69bf821ced3dca01292f3

@codecov

codecov Bot commented Sep 29, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Review

Findings

Medium

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:134 — The Decision's claim that the runner "closes" the fail-open spawn path after the fact (a hook-recorded admission in the findings log, cross-checked against each child's rollout after the run) does not establish that property. The admission record is written to the in-sandbox findings log, whose hash chain (internal/security/trace.go's computeHash) has no MAC or signature — VerifyChain detects edits to an existing chain but not a well-formed entry appended by the same agent that controls the sandbox. Child rollouts under $CODEX_HOME/sessions are likewise agent-writable and are only read by ExtractTranscripts after the agent process exits. A parent that starves the admission hook can therefore both spawn an unauthorized child (unregistered role, V2, or forbidden argument) and append a matching admission entry, or delete the unadmitted child's rollout before extraction — so the cross-check does not actually close the fail-open gate for spawns; resume is not the only residual the design leaves, as the Consequences section implies. This finding replaces a lower-severity fail-open finding from the prior review (same passage, pre-rewrite) — the text has changed substantially since then, and on re-analysis the new mechanism's own stronger claim ("closes that path") is not supported by the design.
    Remediation: Qualify "the runner closes that path" so it does not read as fail-closed, or redesign the cross-check against evidence the agent cannot write — e.g. the host-teed codex exec --json collab_tool_call stream (keyed by item.id/receiver_thread_ids), rather than the sandbox-side findings log or child rollouts. If an admission receipt is kept, MAC or sign it with a runner-held secret bound to the host stream's identifiers. State the residual precisely: fail-open resume, plus any spawn whose host-stream evidence can only be forged by replacing the adapter itself.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run

Review

Findings

Low

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:129 — The ADR's Decision and Consequences sections disclose that a dispatch-hook handler Codex cannot complete, whose interpreter fails to start, or that is starved of CPU/I/O until timeout, is recorded Failed and the call proceeds — on that path the whole admission policy (hook name, spawn arguments, caller identity) is unenforced for one call. The incremental rewrite since the prior review completed this disclosure (it now explicitly covers resume, V2 spawns, forbidden arguments, unregistered roles, and child callers, and states the opt-in tool allowlist is not a backstop). This is an accepted residual of Option 3, inherited from ADR 0100's Failed/timeout contract, with Option 4 named as the alternative that still would not close the starvation sub-case. Not a defect in the document as written, but worth resolving before implementation.
    Remediation: Before implementation, decide whether a dispatch-hook Failed/timeout outcome should abort the iteration at the runner (fail-closed for the run), or keep Codex multi-agent tools off until that control exists. Expanding the ADR's disclosure further does not close the residual.
Previous run (2)

Review

Findings

Medium

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:123 — The Decision states that a Codex handler it cannot complete (interpreter start failure, CPU/I/O starvation until timeout) is recorded as failed and "lets the spawn proceed." That outcome is not limited to a policy-compliant spawn: the same matcher covers resume and the V2 collaboration tools, and the handler is the only enforcement of fork_context=false, forbidden model/reasoning_effort keys, registered-role admission, and child-spawn rejection. The opt-in, default-off ADR 0100 tool allowlist is not a backstop for this path. The Consequences residual names starvation as the path that remains under Option 4 but does not enumerate which policy clauses and tools that path actually admits.
    Remediation: In the Decision's fail-open paragraph and the Option 4 residual, state that a Codex Failed/timeout outcome unenforces the entire admission policy for every matched multi-agent tool (V1 spawn including forbidden fork_context/model/effort/unregistered-role, resume, V2 tools, and spawn-from-child), not only that "the spawn proceeds." Note that the default-off Agent allowlist is not a compensating control for that path.

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:95 — Child-spawn rejection is defined solely by recognising agent_id as a field Codex puts only in a child's hook payload, with native depth=1/open-children=4 as the only backup if that signal is ever wrong. Neither the agent_id-only-on-child invariant nor those native limits appear in the per-bump revalidation list or the Verified-against list. If a future CLI bump omits agent_id from child payloads, the hook's nested-spawn deny fails open and depends entirely on a native depth limit that is also not scheduled for revalidation.
    Remediation: Add to both the per-bump revalidation bullet and the Verified-against list: (1) agent_id is present in child hook payloads and absent from parent payloads, (2) native depth remains 1, (3) open children remain 4 and overflow is rejected, not queued. Treat a payload-shape change as fail-open for nested spawn unless the hook is updated in the same bump.

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:101 — The admission matcher and the residual-risk sentence disagree about the V1 spawn tool itself. Context states the V1 spawn is the bare name spawn_agent; Decision's matcher is defined as three clauses (two namespace prefixes, plus any bare name ending in spawn_agent/resume_agent). Two sentences later it says a dispatch tool "outside both namespaces would not reach the hook" — read literally, that ignores the third (bare-name) clause and would describe the bare spawn_agent tool (which is outside both namespaces) as unreached, when it is in fact the one tool the hook must admit. Separately, collaborationspawn_agent matches both the collaboration... prefix and the ...spawn_agent suffix, and the handler's instruction to "admit the V1 spawn under the policy above" doesn't state that admission requires the exact name spawn_agent, which could be misread as admitting any spawn-suffixed name including V2's.
    Remediation: Define the matcher as the union of (1) multi_agent_v1*, (2) collaboration*, (3) bare names ending in spawn_agent/resume_agent, and rewrite the residual sentence to: a tool matching none of those three clauses never reaches the hook. State the handler's admission rule by exact hook name (spawn_agent only), not by matcher-suffix alone.

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:108 — The same paragraph both rejects resume at the dispatch hook and maps resume onto the Claude name Agent for ADR 0100 allowlist purposes, which removes the only remaining gate on the fail-open paths documented elsewhere in this ADR (a Codex handler timeout/interpreter-failure/starvation is recorded failed and the call proceeds, per lines 116–126). After a legitimate first spawn, Agent is on an org's allowlist; if the dispatch hook then fails open on multi_agent_v1resume_agent, the allowlist also treats resume as Agent and a closed child could be reopened — the bypass Context itself warns about. Wait/close/send_input need the Agent map so an allowlist admitting spawn doesn't block the rest of an admitted delegation; resume does not, because it is never admitted by the hook in the first place.
    Remediation: Map only spawn, wait_agent, close_agent, and send_input to Agent. Leave resume unmapped (or map it to a name the allowlist does not admit) so a fail-open dispatch hook is still subject to the allowlist for resume. Replace "admits the whole delegation" with text noting spawn/wait/close/send_input follow the Agent allowlist entry while resume stays denied by the dispatch hook even when that entry is present.
    See also: [fail-open] finding at line 123 — same underlying residual (a hook Failed/timeout outcome removes enforcement on resume, and the default-off Agent allowlist is not a backstop for it).

Low

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:99 — The handler rejects resume and spawn-from-a-child but "passes the V1 wait_agent, close_agent and send_input through" with no stated caller restriction. The design doesn't say whether those three tools are parent-only at the Codex layer, or whether a child may wait/close/send_input to a sibling. Combined with unrestricted child tools (parent shell and apply_patch) and up to four concurrent children, an unspecified pass-through would allow lateral prompt injection from one child into another if Codex exposes these tools to children.
    Remediation: Specify that wait/close/send_input are admitted only when agent_id is absent (parent caller), or record as verified that Codex does not expose those tools to children at the pinned version and revalidate that on each CLI bump.

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:106 — The 4-child instruction contract is internally ambiguous between parallelism 4 and parallelism 1. Decision says a spawn past the cap is rejected (not queued), a finished child holds its slot until closed, "so the paired instructions dispatch at most four children at a time and close each finished child before the next spawn." Consequences separately says review/retro delegate "in waves of at most four children." Read literally, "close each finished child before the next spawn" forbids spawning the 2nd/3rd/4th member of a wave while earlier siblings are still open, which contradicts running four children concurrently.
    Remediation: Replace "close each finished child before the next spawn" with: instructions may run up to four children concurrently; a finished child must be closed before a further spawn that would exceed four open children; the runner does not queue overflow.

  • [sub-agent-failure] N/A — The challenger adversarial-review pass was skipped: the time-budget check before dispatch found under 600s remaining in the run's time budget (536s). The finding set above is reported without a challenger pass.

Other dimensions dispatched clean against the current diff: intent-coherence confirmed the ADR traces to open issue #6970 (decides the approach, does not close it), found ADR 0100/0104 immutability respected (only two-line Status cross-references added, Context/Decision/Consequences unchanged), and found no architectural conflict with in-flight ADR 0112 (#7808). docs-currency confirmed the new ADR is auto-discovered by docs/.vitepress/config.ts's ADR directory globbing and search-scope registration, confirmed reciprocal backlinks to ADR 0100/0104, and found no other in-repo documentation that should reference this not-yet-implemented mechanism yet. style-conventions found the new ADR's structure and frontmatter consistent with sibling ADRs. correctness's initial dispatch on this PR timed out during external verification; a rescoped retry (internal textual-consistency only, no CLI execution) produced the logic-error findings above.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (3)

Review

Findings

Medium

  • [consumer-completeness] docs/ADRs/0126-fullsend-owned-codex-subagents.md:96 — The Decision admits V1 spawn and explicitly passes V1 wait_agent/close_agent/send_input through under namespaced hook names. Today's ADR 0100 adapter map (internal/runtime/codex_hook/fullsend-codex-hook.py's CLAUDE_TOOL_FOR_CODEX) only translates spawn_agent → Agent and apply_patch → Edit; any other codex tool name is forwarded verbatim. The separate, matcher-omitted AllTools PreToolUse group fires on every tool call, and tool_allowlist_pretool.py fail-closes on any name not in FULLSEND_TOOL_ALLOWLIST (Claude vocabulary only). When an org enables that opt-in allowlist hook, a parent could spawn a registered child under the new policy and then have its wait_agent/close_agent/send_input calls blocked by the pre-existing allowlist hook — a control-plane coupling this Accepted ADR does not record or fold into the per-bump hook-name revalidation.
    Remediation: State in the Decision (or as an explicit open question) whether the ADR 0100 adapter's CLAUDE_TOOL_FOR_CODEX map must be extended to translate the V1 control-plane hook names into Claude vocabulary before the AllTools allowlist hook runs, or whether those names must be exempted from allowlist enforcement, and fold that into the per-bump revalidation of the hook-name rule.

  • [runtime-mechanism] docs/ADRs/0126-fullsend-owned-codex-subagents.md:101 — The ADR states Codex's native open-children limit of four still applies, but does not say whether a 5th concurrent spawn_agent call is queued or rejected, and describes no runner-side queuing. Pi's equivalent cap queues excess calls rather than rejecting them (internal/runtime/pi_extension/fullsend-agent.js's maxConcurrent waiter queue; docs/runtimes/pi.md:548). The review agent's own roster dispatches more than four dimension sub-agents in parallel, already exceeding the native cap. Consequences states review/retro can delegate on Codex once instructions ship, without noting this overflow caveat.
    Remediation: Clarify the overflow semantics — verify and cite whether Codex queues or rejects spawns beyond the native open-children cap, and if it rejects, either state that parallel rosters larger than four are not yet supported on Codex until a runner-side queue is added, or add that queue to the Decision/open questions.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (4)

Review

Findings

Medium

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:102 — The spawn-time integrity set in the Decision covers only hooks.json and the role files. The ADR itself says only personas with a subagents.<persona> entry carry a model in their (digested) role file; every other child takes agents.default_subagent_model at each spawn, which is not named as part of that digest set. A mid-iteration rewrite of that default — leaving the hook adapter and role files untouched — could change which model an unlisted-persona child runs under without tripping the described check. This is a distinct gap from the already-disclosed adapter-rewrite residual (that one assumes a dishonest adapter; this one is an honest adapter plus a file the spawn-time check doesn't hash).
    Remediation: In the Decision, name the spawn-time source of agents.default_subagent_model and add it to the integrity set — e.g. write the resolved model into every generated role file (not only personas with their own subagents entry) so the existing role-file digest covers all admitted spawns, or add the relevant config.toml keys to the spawn-time digest set.

Low

  • [incomplete-doc] docs/ADRs/0126-fullsend-owned-codex-subagents.md:127 — Option 3 cannot enforce persona tools: (Codex has no per-child allowlist), so every native child inherits the parent's shell and apply_patch. This is already disclosed as a departure from ADR 0104 in Consequences, but — unlike the adapter-rewrite and fail-open residuals discussed in the same section — it is not framed as a security residual, even though the ADR's own frontmatter lists security-threat-model as a related topic and review/retro are the motivating workload.
    Remediation: Add a sentence to the residual/Consequences discussion stating that Codex review/retro children are not tool-restricted relative to the parent, and that this is an accepted platform limit of Option 3 rather than a missed control.
  • [incomplete-doc] docs/runtimes/codex.md:308 — The ## See also section, and the "Keep review and retro on Claude Code" passage under "Not yet exercised" (around line 209), still describe the current unimplemented state with no pointer to the newly accepted ADR 0126. The existing wording remains accurate (nothing is implemented yet), but is incomplete without a forward reference to the decision, mirroring the cross-reference this PR itself added to docs/architecture.md.
    Remediation: Add a ## See also link to ADR 0126, and/or a short note under the review/retro passage that native dispatch is the accepted, not-yet-implemented design.
  • [incomplete-doc] docs/contributing/runtime-implementation.md:1014 — The "codex runtime internals (Track Codex (openai/codex) as a supported agent runtime — same secretless GPT path as pi, pinned in the sandbox image #6920)" section still names only ADR 0099 and ADR 0100 as governing decisions, and its "Not yet exercised" subsection ("Sub-agent rosters are not wired, so review/retro are unsupported", ~line 1367) does not point at ADR 0126.
    Remediation: Add ADR 0126 to the governing-decisions list at line 1014, and cross-reference it from the "Sub-agent rosters are not wired" bullet.

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (5)

Review

Findings

Low

  • [design-doc-alignment] docs/ADRs/0126-fullsend-owned-codex-subagents.md:70 — The Decision attributes the four-step child model chain (subagents.<persona> → FULLSEND_CODEX_SUBAGENT_MODEL → subagents.default → gpt-5.6-luna) to "the order decided on codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970." Issue codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970's Design section actually specifies a different default (children run the parent's live model, with the env var mapped to agents.default_subagent_model); the subagents.* map and the luna floor are this ADR's own choices, and Consequences already lists this chain as a departure from ADR 0104.
    Remediation: Drop "the order decided on codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970" from the Decision and present the chain as ADR 0126's own decision.

  • [api-contract] docs/ADRs/0126-fullsend-owned-codex-subagents.md:80 — Child specs must be "OpenAI model IDs," checked against codex debug models --bundled, but the ADR doesn't say whether this reuses the existing Codex parent-model translation (which strips an openai/ prefix). If not, the natural operator value openai/gpt-5.6-luna would fail the catalog lookup even though that id is the ADR's own documented floor.
    Remediation: Add a sentence stating child specs go through the same openai/ prefix-strip as parent Codex model translation before the catalog check.

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:86 — The hook admits a spawn "with fork_context: false and no model or effort override" and rejects "any spawn from a child," but doesn't specify whether an omitted fork_context counts as false (admit) or inherit (deny), nor which payload field signals a spawn-from-child. Two independent implementations could diverge on the exact isolation guarantee.
    Remediation: Optionally clarify omitted-vs-present semantics once verified against the pinned Codex CLI; avoid asserting unverified payload field names in the ADR text.

  • [logic-error] docs/ADRs/0126-fullsend-owned-codex-subagents.md:90 — The Decision names the pass-through allowlist using short V1 tool names (wait_agent, close_agent, send_input), while Context states every multi-agent tool but the V1 spawn is exposed as namespace+name joined. The two sections are consistent when read together, but a reader implementing the matcher from the Decision text alone could allowlist the wrong literal strings.
    Remediation: Note explicitly in the Decision bullet that the pass-through set is the V1 tools under the Context namespace-join rule.

  • [internal-inconsistency] docs/architecture.md:246 — The new bullet summarizes Bootstrap role registration as happening "for an agent with the Agent tool," omitting the ADR's other two gates (harness security enabled, parent resolved to Codex collaboration V1). It correctly ends with "not yet implemented," so it doesn't claim the feature is live, but the compressed description of when it will apply is narrower in the ADR than in this summary.
    Remediation: Qualify the bullet with the ADR's full gating (Agent tool, harness security enabled, parent collaboration V1).

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:128 — Consequences states the spawn-time digest check "adds coverage only against a mid-iteration role or hooks.json edit that leaves the adapter untouched." This slightly overstates coverage: Codex rereads hooks.json and the role file again when the child actually starts, so a parent could pass the digest check and still swap those files before the child-start reread.
    Remediation: Qualify the "adds coverage" claim to note the pre-admit digest check doesn't cover the post-admit/pre-child-start reread window.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (6)

Review

Findings

High

  • [sub-agent-failure] N/A — The correctness sub-agent (Opus-tier, safety-critical dimension) did not return findings: it timed out after 900s during this review run. This is the third consecutive review run on this PR in which the correctness sub-agent has failed to complete (two prior timeouts at 900s are documented in the prior review's sticky comment, one of which used a tightened scope constraint of ≤12 tool calls). Correctness review of ADR 0126's technical claims (model-resolution precedence chain, Bootstrap validation rationale, the fail-closed/fail-open hook language, and the hook matcher/deny-by-default logic) was not completed for this run. This is a review-process gap rather than a confirmed defect: the PR is documentation-only (new ADR 0126 plus two-line backlinks to ADR 0100/0104) and docs/architecture.md explicitly marks the described mechanism as "not yet implemented."

Other dimensions dispatched clean against the current revision:

  • security re-verified both prior findings against the current text of docs/ADRs/0126-fullsend-owned-codex-subagents.md and found both resolved: the Decision now states precisely which hook outcomes are honored as a block (exit 2 with a non-empty reason) versus which fail open (a handler Codex cannot complete — timeout or interpreter-start failure — recorded as failed, as under ADR 0100), and the Consequences section no longer contradicts it; the matcher is now described as deny-by-default across both multi-agent tool namespaces plus the bare spawn_agent/resume_agent suffixes, with the per-CLI-bump revalidation process stated to cover newly-added dispatch tool names specifically.
  • intent-coherence confirmed the ADR traces to issue codex runtime: run the review/retro sub-agent rosters through codex's native spawn_agent roles #6970 (decides the approach, does not close it), found no architectural conflict with in-flight ADR 0112 (docs(adr): route runtime and model per task from a config policy #7808) given this mechanism is explicitly not yet implemented, and confirmed ADR 0100/0104 immutability is respected (only two-line Status cross-references added). It also checked and resolved an apparent discrepancy between the ADR number the linked issue originally referenced ("ADR 0101") and this PR's "ADR 0126" — attributable to sequential ADR numbering having advanced on main since the issue was filed, not a numbering error.
  • docs-currency found the new ADR correctly auto-discovered by docs/.vitepress/config.ts's ADR directory globbing and search-scope registration (no manual sidebar entry needed), confirmed reciprocal backlinks were added to ADR 0100 and ADR 0104, and found no other in-repo documentation (runtime/Codex docs) that should describe the new policy yet, since it is explicitly deferred to follow-up implementation PRs.
  • style-conventions found no issues with the new ADR's formatting against the repository's standard ADR template.

A challenger pass adjudicated the sub-agent-failure finding above: it proposed downgrading the severity to medium on the grounds that the underlying change is documentation-only and not-yet-implemented. The orchestrator preserves the high severity here per this review process's fixed rule for Opus-tier sub-agent dispatch failures — a correctness review that cannot complete on a security-relevant ADR (hook admission policy, fail-open/fail-closed behavior, model-resolution precedence) is a gap serious enough to warrant a human rather than being silently treated as a pass. This is the third consecutive run in which the correctness sub-agent has failed to complete on this specific PR, which may indicate the ADR's length/density or its external-verification-shaped claims are triggering excessive tool use for the Opus-tier reviewer; manual correctness review of docs/ADRs/0126-fullsend-owned-codex-subagents.md is recommended before merge.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (7)

Review

Findings

High

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:90 — The Decision's "fails closed" claim for the mandatory dispatch-admission hook contradicts the Consequences section. Decision: "The hook fails closed: a policy violation, a digest mismatch, a missing file, unreadable input or any error in the hook denies the spawn by exiting 2 with a reason on stderr. Codex lets the call proceed after exit 2 without a reason or any other non-zero exit." Consequences (line 111-112): "As in ADR 0100, a handler Codex cannot complete, such as one that times out or whose interpreter fails to start, is recorded as failed and does not block." These cannot both be true for "any error in the hook": a timeout, interpreter-start failure, crash, or an exit 2 with empty stderr never produces "exit 2 with a reason," so by the Consequences' own account the spawn proceeds anyway. For the sole mandatory enforcement gate on native child dispatch — unlike ADR 0100's optional, defense-in-depth sandbox hooks, which disclose and partly mitigate this residual via a timeout-budget withhold — an unqualified "fails closed" claim overclaims relative to the ADR's own disclosed failure mode.
    Remediation: Reconcile the two sections — state precisely which hook outcomes are honored as a deny (exit 2 with non-empty stderr) versus which fail open (timeout, crash, interpreter-start failure, empty-stderr exit 2), and either adopt ADR 0100's budget-withhold mitigation for this hook specifically or drop the blanket "fails closed" / "any error in the hook denies the spawn" language in favor of an accurate statement of the residual.

  • [sub-agent-failure] N/A — The correctness sub-agent (Opus-tier, safety-critical dimension) did not return findings after two dispatch attempts, each timing out at 900s, despite a tightened scope constraint on the retry (≤12 tool calls, explicit instruction to avoid external/CLI verification). Correctness review of this ADR's technical claims (model-resolution precedence chain, Bootstrap validation rationale, and the fail-closed/fail-open language also flagged by the security dimension) was not completed for this run.

Medium

  • [fail-open] docs/ADRs/0126-fullsend-owned-codex-subagents.md:81 — The dispatch hook's matcher ("a pattern on the tool-name suffix (spawn_agent or resume_agent), not an exact name, so it runs for every namespace the CLI prefixes") is not a deny-by-default allowlist of all dispatch-capable tools — it is an allowlist of two known suffixes. A future or undocumented Codex tool name that does not end in spawn_agent or resume_agent would never invoke the hook and would reach Codex's native multi-agent dispatch unchecked. The ADR's own Context section notes that spawn/resume tool names already differ across collaboration versions on the same CLI build, which is evidence this is a live risk, not a hypothetical one.
    Remediation: State explicitly that the "revalidated on each Codex CLI bump" process specifically covers new/renamed dispatch tool names (not just the already-known ones), or change the matcher to a broader catch-all on the agent-dispatch tool namespace with an explicit allowlist of the single admitted spawn name, so an unrecognized tool name is deny-by-default rather than silently unmatched.

Low

  • [sub-agent-failure] N/A — The challenger adversarial-review pass was skipped: the time-budget check before dispatch found under 600s remaining in the run's time budget. The finding set above is reported without a challenger pass.

Other dimensions dispatched clean: intent-coherence confirmed the ADR traces to open issue #6970, is appropriately scoped as a design-only decision with implementation deferred to follow-up PRs, respects ADR immutability (0100/0104 receive only minor cross-reference annotations), and found no contradiction with the in-flight ADR 0112 (#7808) given this feature is explicitly "not yet implemented." style-conventions and docs-currency returned no findings.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (8)

Looks good to me

Previous run (9)

Looks good to me

Previous run (10)

Looks good to me

Previous run (11)

Looks good to me

Previous run (12)

Review

Findings

Medium

  • [runtime-mechanism] docs/ADRs/0126-runner-owned-codex-child-policy.md:60 — The Decision requires per-persona child models (subagents.<persona>, then subagents.default, then the parent's live model) and forbids a spawn-time model or effort override, while Context notes that Codex rereads the role file on child start and that the parent otherwise chooses spawn model. architecture.md's "resolves their models" doesn't name the remaining channel once spawn model is forbidden. That leaves two implementable readings for the paired runtime work: (1) bake the runner-resolved OpenAI id into each registered role at Bootstrap (stripping persona model:), or (2) omit model on spawn and inherit the parent — in which subagents.<persona> can pass Bootstrap validation and still never apply. Persona model: is "reported, not applied"; registering skill files unchanged would let a Codex role reread apply Claude aliases and contradict that rule.
    Remediation: State the binding explicitly: Bootstrap writes the resolved OpenAI model into each registered role (stripping persona model:), and the hook's "no model override" means the parent cannot replace that baked-in spec. If Codex instead ignores role-file model unless spawn carries one, say that the hook may pass a model argument only when it equals the runner-resolved spec.

The prior medium finding on this ADR (the admission hook's failure mode being unstated) is not observed in the current diff: the Decision now states the hook fails closed for policy violation, digest mismatch, missing/unreadable input, or any in-hook error (mapped to exit 2), and Bootstrap fails if the hook cannot be installed. The Consequences separately disclose that a handler Codex cannot complete (timeout, interpreter failure) is recorded "Failed" and does not block — the same platform residual ADR 0100 already accepts for all Codex hooks, now explicitly named rather than left silent.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run (13)

Review

Findings

Medium

  • [fail-open] docs/ADRs/0126-runner-owned-codex-child-policy.md:66 — The Decision's mandatory PreToolUse dispatch-admission hook ("admits only a V1 spawn of a registered role...") never states its failure mode. ADR 0100 records that a Codex hook exiting anything other than 0 or 2 is "Failed" and does not block — only a translating adapter that maps a deny to exit 2 is fail-closed. ADR 0126 analogizes its spawn-time digest check to "the ADR 0100 adapter" but does not require this new admission hook itself to run through that same adapter, nor state that a timeout, crash, non-0/2 exit, or an absent/unverifiable hooks.json must deny the spawn rather than allow it silently. Because this hook is the policy's sole enforcement point and is installed even when optional security hooks are off, an implementation that follows the ADR text literally could leave spawn admission advisory only.
    Remediation: State in the Decision that the dispatch hook is fail-closed: denials must go through the ADR 0100 translating adapter (or an equivalent that maps deny to exit 2 with a reason on stderr), and that hook timeout, crash, non-0/2 exit, or an absent/unverifiable hooks.json must deny the spawn (or leave multi-agent tools off entirely for that agent).

Other candidate findings raised by dimension sub-agents (an internal-inconsistency claim about tools: semantics, a model-resolution-precedence concern, a residual/TOCTOU characterization concern, an "explore" role privilege-expansion concern, an ADR-number collision with draft PR #7809, and a premature-acceptance concern on the docs/architecture.md update) were adversarially reviewed and found to be either false positives (contradicted by established tools: conventions elsewhere in the repo) or already explicitly disclosed/accepted trade-offs in the ADR's own Options/Consequences sections and the PR description's numbered questions — not omitted or contradictory.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

A policy violation, digest mismatch, missing file, unreadable input or
hook error denies the spawn with exit 2, the only exit Codex treats as a
block. Name the timeout residual ADR 0100 already records.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Started 1:24 PM UTC · Ended 1:29 PM UTC

Commit: 66a8f94 · View workflow run →

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

🤖 Review · ⚠️ Cancelled · Started 1:31 PM UTC · Ended 1:32 PM UTC

Commit: de5760c · View workflow run →

…hook residual

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@dhshah13

Copy link
Copy Markdown
Contributor Author

Addressed the fail-open finding in 66a8f94 and 5a6f3d7:

  • Decision: the dispatch hook fails closed. A policy violation, digest mismatch, missing file, unreadable input or hook error denies the spawn with exit 2 and a reason; Bootstrap fails if the hook cannot be installed.
  • Consequences: a handler Codex cannot complete, such as one that times out or whose interpreter fails to start, is recorded as failed and does not block. That is ADR 0100's residual and cannot be closed from inside the hook.

🤖 Addressed by Claude Code

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:34 PM UTC · Completed 1:49 PM UTC

Commit: 5a6f3d7 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $3.64

@fullsend-ai-review

fullsend-ai-review Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR addition with no code modifications or protected paths, elevated to moderate risk by high commit churn (74 commits in 30 days) and multi-author contention (15 authors in 90 days) on docs/architecture.md; consistent with prior runs on this PR.

Previous run

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR addition with no code modifications or protected paths, elevated to moderate risk by high commit churn (74 commits in 30 days) and multi-author contention (15 authors in 90 days) on docs/architecture.md; consistent with 10+ prior runs on this PR.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR addition with no code modifications or protected paths, elevated to moderate risk by high commit churn and multi-author contention on docs/architecture.md. Consistent with prior runs on this PR.

Previous run (3)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or code modifications, moderate file churn driven by the architecture index, and clean rollback safety.

Previous run (4)

Risk Assessment: moderate (2/5)

Details

Documentation-only change (new ADR plus cross-reference edits) with no protected paths, no security-sensitive files, and no dependency changes, but high historical churn and author contention on the modified ADR/architecture documentation elevate the composite risk from low to moderate.

Previous run (5)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk (consistent with 5+ prior runs on this PR) due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (6)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk (consistent with 5+ prior runs on this PR) due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (7)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (8)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (9)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (10)

Risk Assessment: moderate (2/5)

Details

Documentation-only ADR change with no protected paths or dependency modifications, anchored to moderate risk due to high churn, multi-author contention, and regression history on docs/architecture.md.

Previous run (11)

Risk Assessment: moderate (2/5)

Details

Small documentation-only ADR change with no protected paths, but assigned moderate risk due to high churn, multi-author contention, and regression history on docs/architecture.md.

fullsend-ai-review[bot]

This comment was marked as outdated.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
Signed-off-by: Dharit Shah <dhshah@redhat.com>
Signed-off-by: Dharit Shah <dhshah@redhat.com>
@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Oct 1, 2026
@fullsend-ai-review
fullsend-ai-review Bot dismissed stale reviews from themself October 1, 2026 20:04

Superseded by updated review

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Oct 1, 2026
@waynesun09
waynesun09 added this pull request to the merge queue Oct 1, 2026
Answers the review bot's low finding on 6c0ad3a, which asked for a
decision on the fail-open path before implementation. Codex's exec
stream drops hook outcomes and its rollout does not persist them
(exec/src/event_processor_with_jsonl_output.rs, rollout/src/policy.rs),
so the runner cannot see a failed guard directly; instead the guard
records each admission with the spawn's tool_use_id in the findings log
and the runner, which already reads every child's rollout, fails the run
when a child has no admission, as it fails a run whose audit log does not
verify. A resume on that path is the residual that remains. The switch
ships after the cross-check.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
waynesun09, 2026-10-01: an implementation-time choice, not an ADR
defect; fullsend-ai#7829 keeps the multi-agent tools off until the hook ships, and
whether a Failed/timeout dispatch outcome aborts the run is for the
implementation PRs under fullsend-ai#6970. The ADR keeps the two verified facts an
implementation needs (exec --json drops hook outcomes; the rollout does
not persist them) and no longer decides the cross-check itself.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 1, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:13 PM UTC · Completed 8:31 PM UTC

Commit: 095c62e · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $6.97

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review October 1, 2026 20:31

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot removed the ready-for-merge All reviewers approved — ready to merge label Oct 1, 2026
Answers the review bot's medium finding on 095c62e: the findings log
and the children's rollouts are agent-writable, so they cannot establish
that an unadmitted spawn fails the run. The claim itself is already gone
(the abort choice is left to the implementation PRs); this commit
replaces the pointer to those two stores with the exec stream's
collab_tool_call items (a spawn's sender and receiver thread ids and
status), which the host captures outside the sandbox, and notes that the
stream carries no item for a resume.

Signed-off-by: Dharit Shah <dhshah@redhat.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Oct 1, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:36 PM UTC · Completed 8:47 PM UTC

Commit: e9dd839 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5 · Effort: high · Cost: $2.27

Merged via the queue into fullsend-ai:main with commit 48d41b6 Oct 1, 2026
16 checks passed
@fullsend-ai-review

Copy link
Copy Markdown

Review skipped — this PR is already merged.

The /fs-review command only reviews open PRs/MRs.

Posted by fullsend post-review check

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants