feat(codex): enable native subagent dispatch

[CNHLAIA]

Closes #444

Summary

Ready for review. Targeted automated validation and Windows manual tests are complete;
full-suite baseline failures are noted below.

This change enables Trellis to deliver role-specific task context to native
Codex subagents through SubagentStart. The default auto mode dispatches
subagents by default, while explicit inline execution remains available and
the child-side pull path remains a fallback.

Motivation

Codex now exposes a role-filtered subagent-start hook, the parent session ID,
and developer-context injection. Trellis currently has only a pull-based
Codex integration, which can make a child agent load main-session workflow
routing and lose its precise task context.

Implemented changes

• Register a SubagentStart hook for the three Trellis Codex roles.
• Resolve the active task from the parent Codex session without a sole-session
  fallback and inject each role's curated developer context.
• Keep unrelated agents untouched and fail open when no valid task exists.
• Use a marker-gated pull fallback when the native hook does not run; preserve
  explicit inline and retain sub-agent as a compatibility alias for auto.
• Align templates, config parsing, workflow routing, JSONL seeding, update
  collection, and regression coverage.

The generated marketplace native workflow is updated together with the built-in
workflow template. The resolver keeps its existing defaults for every caller;
only the native Codex hook opts out of environment-context and single-session
fallbacks.

Validation

• Unit-test role matching, parent-session resolution, role-specific context,
  no-task behavior, and non-Trellis agent isolation.
• Regression-test dispatch modes, fallback behavior, recursion prevention, and
  trellis init / trellis update template consistency.
• Run the targeted CLI suite, then lint, typecheck, and the full test suite.

Completed validation:

• pnpm lint, pnpm typecheck, and the relevant Python syntax checks pass.
• 97 directly related Codex/template/shared-hook/platform assertions pass,
  including the three native Codex workflow-routing assertions. The native-hook
  black-box cases and migration assertions pass.
• The core package test suite passes (327 tests). A current Windows execution
  of the larger CLI regression file has 22 failures out of 346 tests, dominated
  by the missing python3 executable and CRLF/LF-sensitive legacy assertions.
  It is therefore not claimed as a green full-suite result; Linux CI should
  provide the final full-suite verification.
• The built-in workflow template and marketplace native workflow were updated
  together. The marketplace update is committed at c78392a; the parent
  repository records that submodule pointer in 8438c0fd.
• Windows manual testing previously passed for generated SubagentStart hooks,
  default native auto dispatch, strict two-session sentinel isolation,
  explicit inline, and the legacy sub-agent alias. The current 0.6.7
  tarball passes a version smoke check; re-running the UI scenarios on that
  artifact remains recommended before treating manual testing as final-package
  evidence. The optional unapproved-hook fallback scenario was not manually
  repeated; it is covered by automated tests.

Compatibility

• Explicit inline remains available.
• Native injection is additive; if it does not run, the child self-loads its
  context through the established pull path.
• The parent-session resolver remains backward compatible for all existing
  callers. Only the Codex SubagentStart path disables its sole-session
  fallback, preventing cross-session task-context injection.

Summary by CodeRabbit

• New Features
  • Codex now defaults to automatic sub-agent dispatch for implement, check, and research.
  • Added native Codex SubagentStart context injection with strict resolver rules and safe child-side fallback when needed.
• Bug Fixes
  • Active-task/context resolution can optionally ignore environment-derived identity to prevent cross-session/window contamination.
  • Improved handling of missing, stale, or malformed parent task context for Codex sub-agent startup.
• Documentation
  • Updated guides for codex.dispatch_mode (auto default, inline opt-out, sub-agent alias) and the new context delivery protocol.
  • Refreshed workflow guidance and readiness gates for sub-agent execution.
• Tests
  • Expanded Codex native SubagentStart regression coverage and updated template/config expectations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4bd747d5-8929-4d7b-8a39-6826f10399e5

📥 Commits

Reviewing files that changed from the base of the PR and between 9992e0f and 81b9a8e.

📒 Files selected for processing (2)

• packages/cli/test/configurators/platforms.test.ts
• packages/cli/test/regression.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/cli/test/configurators/platforms.test.ts
• packages/cli/test/regression.test.ts

---

📝 Walkthrough

Walkthrough

Codex dispatch now defaults to auto, installs native SubagentStart context injection, constrains parent-task resolution, updates agent templates and workflow guidance, and adds coverage for native context delivery and dispatch-mode routing.

Changes

Codex native dispatch

Layer / File(s)	Summary
Dispatch modes and workflow routing .trellis/scripts/common/{config,task_store,workflow_phase}.py, .trellis/workflow.md, packages/cli/src/templates/trellis/..., packages/cli/src/templates/shared-hooks/inject-workflow-state.py	Codex defaults to auto; inline remains explicit, sub-agent aliases auto, and platform, breadcrumb, task-seeding, and workflow routing reflect the new modes.
Native context resolution and injection .trellis/scripts/common/active_task.py, packages/cli/src/templates/trellis/scripts/common/active_task.py, packages/cli/src/templates/shared-hooks/inject-subagent-context.py, packages/cli/src/templates/codex/hooks.json, .trellis/spec/cli/backend/platform-integration.md	Native Codex sub-agent starts resolve parent tasks without environment or single-session fallbacks and emit role-specific additionalContext.
Codex installation and agent behavior packages/cli/src/configurators/*, packages/cli/src/templates/codex/agents/*, packages/cli/src/templates/shared-hooks/index.ts, .trellis/config.yaml, packages/cli/src/templates/trellis/config.yaml	Codex agents and hooks are written directly; profiles use marker-gated context loading, fallback task paths, and research role isolation.
Dispatch validation and regression coverage packages/cli/test/{configurators,templates}/*, packages/cli/test/regression.test.ts, packages/cli/test/commands/update.integration.test.ts	Tests cover hook wiring, agent content, native context resolution, mode routing, workflow text, and platform classification.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• #442: Covers the Codex native sub-agent dispatch improvements implemented here.
• #370: Also concerns sub-agent context injection, though this PR specifically implements Codex SubagentStart handling.

Possibly related PRs

• mindfold-ai/Trellis#307: Both modify sub-agent capability detection in task_store.py.
• mindfold-ai/Trellis#361: Both update curated JSONL readiness requirements.
• mindfold-ai/Trellis#404: Both modify Codex dispatch-mode handling for task-store seeding.

Suggested reviewers: taosu0216

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: enabling native Codex subagent dispatch.
Linked Issues check	✅ Passed	The changes match #444 by using SubagentStart, agent_type matching, additionalContext, parent session resolution, auto default, inline fallback, and recursion limits.
Out of Scope Changes check	✅ Passed	The documented changes stay focused on Codex native subagent support, template wiring, workflow routing, and tests, with no clear unrelated additions.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.trellis/scripts/common/workflow_phase.py:
- Around line 160-171: Update the Codex dispatch parsing in
_trellis/scripts/common/workflow_phase.py_ (lines 160-171) and
_packages/cli/src/templates/trellis/scripts/common/workflow_phase.py_ (lines
160-171) so a non-dictionary codex_cfg explicitly sets mode to "inline" instead
of retaining the "auto" default; preserve the existing handling for valid
dictionary configurations and return mapping.

In @.trellis/spec/cli/backend/platform-integration.md:
- Around line 463-470: Update the existing Codex platform classification and
related Class-2 table to identify Codex as native hook-inject with pull loading
retained only as fallback; remove the statement that its native spawn hook is
unavailable, and revise the class counts and rationale consistently with this
reclassification.

In `@packages/cli/src/templates/codex/hooks.json`:
- Around line 14-24: Update the SubagentStart matcher to use an exact anchored
regular expression matching only trellis-implement, trellis-check, or
trellis-research, preventing names with extra suffixes from triggering the hook.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5ee2f69f-bb3d-4190-b4a7-a82deff36ed2

📥 Commits

Reviewing files that changed from the base of the PR and between 51a5674 and 8438c0f.

📒 Files selected for processing (28)

• .trellis/config.yaml
• .trellis/scripts/common/active_task.py
• .trellis/scripts/common/config.py
• .trellis/scripts/common/task_store.py
• .trellis/scripts/common/workflow_phase.py
• .trellis/spec/cli/backend/platform-integration.md
• .trellis/workflow.md
• marketplace
• packages/cli/src/configurators/codex.ts
• packages/cli/src/configurators/index.ts
• packages/cli/src/templates/codex/agents/trellis-check.toml
• packages/cli/src/templates/codex/agents/trellis-implement.toml
• packages/cli/src/templates/codex/agents/trellis-research.toml
• packages/cli/src/templates/codex/hooks.json
• packages/cli/src/templates/shared-hooks/index.ts
• packages/cli/src/templates/shared-hooks/inject-subagent-context.py
• packages/cli/src/templates/shared-hooks/inject-workflow-state.py
• packages/cli/src/templates/trellis/config.yaml
• packages/cli/src/templates/trellis/scripts/common/active_task.py
• packages/cli/src/templates/trellis/scripts/common/config.py
• packages/cli/src/templates/trellis/scripts/common/task_store.py
• packages/cli/src/templates/trellis/scripts/common/workflow_phase.py
• packages/cli/src/templates/trellis/workflow.md
• packages/cli/test/configurators/platforms.test.ts
• packages/cli/test/regression.test.ts
• packages/cli/test/templates/codex.test.ts
• packages/cli/test/templates/shared-hooks.test.ts
• packages/cli/test/templates/trellis.test.ts

Withdrawn — we'll handle the submodule and verification on our side.