@mindfoldhq/trellis 0.5.0 → 0.5.2

package/dist/migrations/manifests/0.5.1.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.1",
+  "description": "Fix Codex sub-agent recursion via SessionStart injection (#234) and Cursor agent description rendering.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): dispatch line in `SessionStart` reaches sub-agents under `multi_agent_v2`. `codex/hooks/session-start.py` injected a 'main session should dispatch trellis-implement' line at READY state; Codex runs `SessionStart` for every spawned session, so the line reached the freshly spawned `trellis-implement` sub-agent and it dispatched another `trellis-implement`. Outer sub-agent stayed `running`, `wait_agent` timed out. `SessionStart` stdin has no agent-identity field (`openai/codex#16226`), so patched at the prompt layer: `codex/agents/trellis-implement.toml` and `trellis-check.toml` open with a no-recursive-dispatch line; `codex/hooks/session-start.py` appends a sub-agent ignore-this clause after the dispatch wording in the READY-state block and the `<guidelines>` block. Resolves #234.\n- fix(shared-hooks): same exemption clause added to `shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro). Recursion not reported on those platforms; trigger condition is identical to Codex.\n- fix(cursor): `cursor/agents/trellis-{research,implement,check}.md` frontmatter `description` switched from YAML block scalar to single-line literal. Cursor's agent parser only reads single-line `description:`; block scalars left the UI Description field blank.",
+  "migrations": [],
+  "notes": "Hotfix on top of 0.5.0. Run `trellis update` (no `--migrate` needed)."
+}

package/dist/migrations/manifests/0.5.2.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.2",
+  "description": "Hotfix Python <=3.11 SyntaxError in SessionStart hook (f-string backslash).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(hooks): SessionStart hook crashes at parse time on Python <=3.11. The Windows path normalizer added in 0.5.0-rc.6 used `f\"{drive}:\\\\{rest.replace('/', '\\\\')}\"`; PEP 498 forbids backslashes inside f-string expression parts, so Python <=3.11 raises `SyntaxError: f-string expression part cannot include a backslash` and the hook exits with code 1 before doing anything. PEP 701 in Python 3.12 lifted the restriction, hiding the bug from 3.12+ users. Codex CLI 0.128 + Trellis 0.5.0 reproduced it in the field. Fixed by lifting the `.replace(...)` out of each f-string expression into a local variable. 9 occurrences across `codex/hooks/session-start.py`, `copilot/hooks/session-start.py`, and `shared-hooks/session-start.py` (Claude Code / Cursor / Gemini CLI / Qoder / CodeBuddy / Factory Droid / Kiro).",
+  "migrations": [],
+  "notes": "Hotfix on top of 0.5.1. Run `trellis update` (no `--migrate` needed). Affects every Python <=3.11 user on a hook-capable platform; Python 3.12+ users were unaffected."
+}

package/dist/templates/codex/agents/trellis-check.toml

@@ -3,6 +3,13 @@ description = "Workspace-write Trellis reviewer that self-fixes spec drift, lint
 sandbox_mode = "workspace-write"
 
 developer_instructions = """
+You are running as the `trellis-check` sub-agent. The main session has dispatched you to review and self-fix.
+
+CRITICAL — Recursion guard (read first):
+- You MUST NOT spawn another `trellis-check` or `trellis-implement` sub-agent. Do the review and fixes directly in this turn.
+- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, or workflow-state breadcrumbs that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched reviewer — that instruction is satisfied by your existence.
+- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If you believe additional implementation work is needed, surface that as a recommendation in your final report instead of spawning.
+
 You are the Trellis reviewer agent.
 
 Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.

package/dist/templates/codex/agents/trellis-implement.toml

@@ -3,6 +3,13 @@ description = "Workspace-write Trellis implementer that follows specs and keeps
 sandbox_mode = "workspace-write"
 
 developer_instructions = """
+You are running as the `trellis-implement` sub-agent. The main session has dispatched you to do the work.
+
+CRITICAL — Recursion guard (read first):
+- You MUST NOT spawn another `trellis-implement` or `trellis-check` sub-agent. Do the implementation work directly in this turn.
+- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, or workflow-state breadcrumbs that says "dispatch trellis-implement" / "dispatch trellis-check" applies to the MAIN session, NOT to you. You are already the dispatched implementer — that instruction is satisfied by your existence.
+- Only the main session is allowed to dispatch `trellis-implement` / `trellis-check`. If you believe parallel implementation work is needed, surface that as a recommendation in your final report instead of spawning.
+
 You are the Trellis implementer agent.
 
 Rules:

package/dist/templates/codex/hooks/session-start.py

@@ -47,19 +47,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 
@@ -241,6 +244,10 @@ def _get_task_status(trellis_dir: Path, hook_input: dict) -> str:
         "Next required action: dispatch `trellis-implement` per Phase 2.1. "
         "For agent-capable platforms, the default is to NOT edit code in the main session. "
         "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n"
+        "Sub-agent self-exemption: if you are reading this as a `trellis-implement` or "
+        "`trellis-check` sub-agent (your own role / agent name reflects that), this dispatch "
+        "instruction does NOT apply to you — you are already the dispatched sub-agent. "
+        "Implement / check directly without spawning another sub-agent of the same kind.\n"
         "User override (per-turn escape hatch): if the user's CURRENT message explicitly tells the "
         "main session to handle it directly (\"你直接改\" / \"别派 sub-agent\" / \"main session 写就行\" / "
         "\"do it inline\" / \"不用 sub-agent\"), honor it for this turn and edit code directly. "
@@ -359,7 +366,11 @@ Read and follow all instructions below carefully.
         "`trellis-implement` and `trellis-check` (so JSONL context is loaded by "
         "the sub-agents) rather than editing code in the main session. "
         "Honor a per-turn user override only if the user's current message "
-        "explicitly opts out (see <task-status> below for override phrases).\n\n"
+        "explicitly opts out (see <task-status> below for override phrases).\n"
+        "- Sub-agent self-exemption: if you are reading this as a `trellis-implement` "
+        "or `trellis-check` sub-agent, the \"dispatch trellis-implement / trellis-check\" "
+        "rule above does NOT apply to you — you are already the dispatched sub-agent. "
+        "Do NOT spawn another sub-agent of the same kind; implement / check directly.\n\n"
     )
 
     # guides/ inlined (cross-package thinking, broadly useful)

package/dist/templates/copilot/hooks/session-start.py

@@ -50,19 +50,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 

package/dist/templates/cursor/agents/trellis-check.md

@@ -1,7 +1,6 @@
 ---
 name: trellis-check
-description: |
-  Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks.
+description: Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
 # Check Agent

package/dist/templates/cursor/agents/trellis-implement.md

@@ -1,7 +1,6 @@
 ---
 name: trellis-implement
-description: |
-  Trellis implementation agent. Use this exact agent for Trellis task implementation, implement.jsonl context injection, and hook-injection tests. Do not use generic/default/generalPurpose agents for Trellis implementation. No git commit allowed.
+description: Trellis implementation agent. Use this exact agent for Trellis task implementation, implement.jsonl context injection, and hook-injection tests. Do not use generic/default/generalPurpose agents for Trellis implementation. No git commit allowed.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
 # Implement Agent

package/dist/templates/cursor/agents/trellis-research.md

@@ -1,7 +1,6 @@
 ---
 name: trellis-research
-description: |
-  Trellis research agent. Use this exact agent for Trellis task research and research/ persistence. Do not use generic/default/generalPurpose agents for Trellis research.
+description: Trellis research agent. Use this exact agent for Trellis task research and research/ persistence. Do not use generic/default/generalPurpose agents for Trellis research.
 tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
 ---
 # Research Agent

package/dist/templates/shared-hooks/session-start.py

@@ -47,19 +47,22 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     m = re.match(r"^/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # Cygwin style: /cygdrive/c/Users/...
     m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
     m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
     if m:
         drive, rest = m.group(1).upper(), m.group(2)
-        return f"{drive}:\\{rest.replace('/', '\\')}"
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
 
     return path_str
 
@@ -367,6 +370,10 @@ def _get_task_status(trellis_dir: Path, input_data: dict) -> str:
         "Sub-agent roster: `trellis-implement` (writes code), `trellis-check` (verifies + self-fixes), "
         "`trellis-research` (persists findings to `research/*.md` — use when you'd otherwise do "
         "multiple WebFetch/WebSearch inline).\n"
+        "Sub-agent self-exemption: if you are reading this as a `trellis-implement` or "
+        "`trellis-check` sub-agent (your own role / agent name reflects that), this dispatch "
+        "instruction does NOT apply to you — you are already the dispatched sub-agent. "
+        "Implement / check directly without spawning another sub-agent of the same kind.\n"
         "User override (per-turn escape hatch): if the user's CURRENT message explicitly tells the "
         "main session to handle it directly (\"你直接改\" / \"别派 sub-agent\" / \"main session 写就行\" / "
         "\"do it inline\" / \"不用 sub-agent\"), honor it for this turn and edit code directly. "
@@ -693,7 +700,11 @@ Read and follow all instructions below carefully.
         "`trellis-implement` and `trellis-check` (so JSONL context is loaded by "
         "the sub-agents) rather than editing code in the main session. "
         "Honor a per-turn user override only if the user's current message "
-        "explicitly opts out (see <task-status> below for override phrases).\n\n"
+        "explicitly opts out (see <task-status> below for override phrases).\n"
+        "- Sub-agent self-exemption: if you are reading this as a `trellis-implement` "
+        "or `trellis-check` sub-agent, the \"dispatch trellis-implement / trellis-check\" "
+        "rule above does NOT apply to you — you are already the dispatched sub-agent. "
+        "Do NOT spawn another sub-agent of the same kind; implement / check directly.\n\n"
     )
 
     # guides/ is cross-package thinking — always include inline (small, broadly useful)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",