> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# v0.5.7

> 2026-05-08

After upgrading Codex 0.129, run `/hooks` once and approve the Trellis hook (without approval the workflow won't auto-inject; details below). New `codex.dispatch_mode` knob lets Codex projects opt into `inline` dispatch. Fixes: Codex sub-agent `wait_agent` deadlock ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241)), Kiro CLI rejecting agent JSON ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247)), Windows `trellis init` not finding `python3` / `py -3` ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236)). No new migrations.

## Codex 0.129 compatibility

### `/hooks` review gate (TUI approval required)

Codex 0.129 gates each installed hook behind a one-time `/hooks` TUI review. Until the user runs `/hooks` in Codex and approves the Trellis `UserPromptSubmit` hook, the workflow breadcrumb won't auto-inject; every fresh Codex session looks like Trellis isn't wired in.

The existing `<trellis-bootstrap>` fallback in `inject-workflow-state.py` covers this gap: when the hook hasn't fired, the fallback directs the AI to read the `trellis-start` skill manually so the workflow still runs (just less smoothly). No Trellis code change needed for the fallback. **Run `/hooks` once after upgrading Codex** to restore full auto-injection.

### `[features].codex_hooks` to `[features].hooks` rename

Codex 0.129 renamed `[features].codex_hooks` to `[features].hooks` (legacy name still works but emits a deprecation warning on startup). Trellis docs (`advanced/multi-platform`, `advanced/architecture`, `advanced/custom-hooks`, `advanced/appendix-f`, `start/install-and-first-task`, `start/everyday-use`, `start/how-it-works`), the `spec/cli/backend/platform-integration.md` rules, and the `trellis init` runtime warning now point at the new name. The uninstall scrubber recognizes both `hooks = true` and the legacy `codex_hooks = true` so older projects still clean up cleanly.

## Enhancements

### Codex configurable dispatch mode

New project-level knob in `.trellis/config.yaml`:

```yaml theme={null}
codex:
  dispatch_mode: sub-agent # default; set to "inline" to skip sub-agent dispatch
```

When `inline` is set, the `<workflow-state>` breadcrumb tells the main Codex agent to load `trellis-before-dev`, edit code directly, then load `trellis-check` for lint / typecheck / tests, instead of dispatching `trellis-implement` / `trellis-check` sub-agents.

Mechanism: `inject-workflow-state.py` reads the config and resolves `[workflow-state:in_progress-inline]` / `[workflow-state:planning-inline]` blocks from `workflow.md` when codex+inline is set; `get_context.py --platform codex` swaps to the `[Kilo, Antigravity, Windsurf]` block content. Per-turn override phrases (`do it inline` / `你直接改` / etc.) keep working in both modes.

Codex-only. Class-1 platforms (Claude Code, Cursor, OpenCode, Kiro, CodeBuddy, Droid) and the other class-2 platforms keep the dispatch default. `.codex/agents/*.toml` files are still written; sub-agent infrastructure stays installed.

### `configSectionsAdded` manifest field

New optional manifest field declares which top-level keys this release introduces in `.trellis/config.yaml`:

```jsonc theme={null}
{
  "version": "0.5.7",
  "configSectionsAdded": [
    {
      "file": ".trellis/config.yaml",
      "sentinel": "codex:",
      "sectionHeading": "Codex (sub-agent dispatch behavior)",
    },
  ],
}
```

`trellis update` walks each manifest's `configSectionsAdded`, and for each entry whose `sentinel` is missing from the user's target file, appends the section content extracted from the bundled template. Append-only, idempotent (sentinel check on rerun). User customizations stay untouched. Future config additions declare a new entry in their own manifest, no `update.ts` change needed per addition.

Replaces the prior "modified-file confirm prompt" path, where users who customized `config.yaml` had to either accept template (losing edits) or skip (missing the new section).

## Bug Fixes

### Codex sub-agent collab tools, structural disable ([`#240`](https://github.com/mindfold-ai/Trellis/issues/240) follow-up, [`#241`](https://github.com/mindfold-ai/Trellis/issues/241))

[v0.5.5](/changelog/v0.5.5) removed the `SessionStart` injection vector. [v0.5.6](/changelog/v0.5.6) added prompt-layer `fork_turns="none"` guidance to `AGENTS.md`. Both were prompt-layer mitigations. [Ca11back's reproduction on `#241`](https://github.com/mindfold-ai/Trellis/issues/241) showed the prompt-layer fix didn't reach reality:

* The main agent still spawned `trellis-research` with default `fork_turns="all"` despite the AGENTS.md rule.
* The child inherited the parent's transcript including prior `spawn_agent(...)` tool-call records.
* The child read AGENTS.md's "ALWAYS wait for every spawned subagent..." rule, applied it to *itself*, and called `wait_agent` on the inherited records.
* No agents to wait for. `No agents completed yet`. Stuck.

Structural fix: each `packages/cli/src/templates/codex/agents/trellis-{implement,check,research}.toml` now contains:

```toml theme={null}
[features]
multi_agent = false

[features.multi_agent_v2]
enabled = false
```

With both flags off, Codex doesn't register `spawn_agent` / `wait_agent` / `list_agents` / `close_agent` for the sub-agent.

Adds `[issue-241-followup]` regression test asserting all three template toml files retain the disable block.

### Codex `trellis-start` skill missing on update path

0.5.5's `configureCodex()` writes `.agents/skills/trellis-start/SKILL.md` so the `<trellis-bootstrap>` notice from `inject-workflow-state.py` resolves to a real skill. But `collectPlatformTemplates.codex.collectTemplates()` (used by `trellis update`) was missed.

Result: users upgrading from 0.4.x to 0.5.5/0.5.6 ran the safe-file-delete migration that removed `.agents/skills/start/`, then `trellis update` regenerated all the other `trellis-*` skill dirs from `collectTemplates`, but never wrote `trellis-start`. Their AI then reported "no `.agents/skills/trellis-start/SKILL.md`" on every turn that hit `<trellis-bootstrap>`.

Fix: extracted `resolveCodexTrellisStartSkill()` helper in `configurators/shared.ts`, called from both `configureCodex()` (init) and `collectPlatformTemplates.codex` (update) so the file shows up on both paths. No drift possible. Both call the same helper.

### Kiro CLI agent JSON schema migration ([`#247`](https://github.com/mindfold-ai/Trellis/issues/247))

Kiro CLI rejected Trellis's pre-0.5.7 agent JSON with "invalid agent". Three schema changes per Kiro's [Agent Configuration Reference](https://kiro.dev/docs/cli/custom-agents/configuration-reference):

1. **`instructions` becomes `prompt`**. Kiro CLI no longer accepts `instructions`.
2. **Adds `allowedTools` field** mirroring `tools`. Kiro splits "available tools" from "permitted tools"; without `allowedTools` the agent can't actually invoke anything.
3. **`hooks` array becomes object keyed by event name**:

   ```json theme={null}
   // before
   "hooks": [
     { "on": "agentSpawn", "command": "...", "timeout_ms": 30000 }
   ]
   // after
   "hooks": {
     "agentSpawn": [{ "command": "..." }]
   }
   ```

   `on` field removed (event is now the key). `timeout_ms` removed.

Affects all three `trellis-{implement,check,research}.json` files. Adds `[issue-247]` regression test asserting the new schema (prompt present, instructions absent, allowedTools array, hooks object not array).

### Windows Python detection fallback chain ([`#236`](https://github.com/mindfold-ai/Trellis/issues/236))

`trellis init` previously tried only `python --version` on Windows. If the host had Python under `python3` (Microsoft Store) or `py -3` (python.org launcher) but not `python`, init failed outright with `Python command "python" not found`.

`resolveSupportedPython()` in `packages/cli/src/commands/init.ts` now walks a per-platform candidate list:

| Platform | Candidate order              |
| -------- | ---------------------------- |
| Windows  | `python`, `python3`, `py -3` |
| Other    | `python3`, `python`          |

First candidate whose `--version` matches Python ≥ 3.9 wins. The resolved command is cached via `setResolvedPythonCommand()` in `configurators/shared.ts` so `replacePythonCommandLiterals()` and all downstream template / configurator writes pick up the same value.

Two env-var escape hatches:

* `TRELLIS_PYTHON_CMD=<cmd>` for explicit override (no probe).
* `TRELLIS_SKIP_PYTHON_CHECK=1` for skipping the probe entirely (pre-existing).

Failure case throws an aggregated error listing every candidate's probe result plus a Windows-specific install hint pointing at python.org with the "Add Python to PATH" reminder.

6 new unit tests in `packages/cli/test/commands/init-internals.test.ts` cover the fallback chain, env-var overrides, sandbox-restricted EPERM, and aggregated failure mode.

## Upgrade

```bash theme={null}
npm install -g @mindfoldhq/trellis@latest
trellis update
```

No `--migrate` needed. Codex users get hardened sub-agent role files; Windows users no longer need to install 0.4.0 first. Codex 0.129+ users should run `/hooks` once after upgrading Codex to approve the Trellis `UserPromptSubmit` hook.