@mindfoldhq/trellis 0.5.4 → 0.5.5

package/dist/configurators/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmF/D"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyG/D"}

package/dist/configurators/codex.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import { AI_TOOLS } from "../types/ai-tools.js";
 import { getAllAgents, getAllCodexSkills, getAllHooks, getConfigTemplate, getHooksConfig, } from "../templates/codex/index.js";
+import { getCommandTemplates } from "../templates/common/index.js";
 import { ensureDir, writeFile } from "../utils/file-writer.js";
-import { resolvePlaceholders, resolveAllAsSkillsNeutral, resolveBundledSkills, applyPullBasedPreludeToml, writeSkills, writeSharedHooks, replacePythonCommandLiterals, } from "./shared.js";
+import { resolvePlaceholders, resolvePlaceholdersNeutral, resolveAllAsSkillsNeutral, resolveBundledSkills, applyPullBasedPreludeToml, wrapWithSkillFrontmatter, writeSkills, writeSharedHooks, replacePythonCommandLiterals, } from "./shared.js";
 /**
  * Configure Codex by writing:
  * - .agents/skills/ — shared skills from common source
@@ -18,6 +19,18 @@ export async function configureCodex(cwd) {
     // safe when both writers produce identical output).
     const sharedSkillsRoot = path.join(cwd, ".agents", "skills");
     await writeSkills(sharedSkillsRoot, resolveAllAsSkillsNeutral(AI_TOOLS.codex.templateContext), resolveBundledSkills(AI_TOOLS.codex.templateContext));
+    // Additionally write `trellis-start` to .agents/skills/ — Codex-specific.
+    // The SessionStart hook was removed (de-recursion fix); inject-workflow-state.py
+    // injects a `<trellis-bootstrap>` block on no_task turns instructing the AI to
+    // invoke `$trellis-start` to load workflow context. Without this skill, that
+    // invocation has nothing to resolve. Other agent-capable platforms keep their
+    // working SessionStart hooks and don't need this.
+    const startTemplate = getCommandTemplates().find((t) => t.name === "start");
+    if (startTemplate) {
+        const trellisStartDir = path.join(sharedSkillsRoot, "trellis-start");
+        ensureDir(trellisStartDir);
+        await writeFile(path.join(trellisStartDir, "SKILL.md"), wrapWithSkillFrontmatter("trellis-start", resolvePlaceholdersNeutral(startTemplate.content, AI_TOOLS.codex.templateContext)));
+    }
     const codexRoot = path.join(cwd, ".codex");
     // Codex-specific skills (platform-specific) → .codex/skills/
     const codexSkillsRoot = path.join(codexRoot, "skills");

package/dist/configurators/codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/configurators/codex.ts"],"names":[],"mappings":"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"}

package/dist/migrations/manifests/0.5.5.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.5.5",
+  "description": "Patch: structural fix for Codex sub-agent recursion (#240, #242) — drop SessionStart hook, bootstrap via trellis-start skill.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**Bug Fixes:**\n- fix(codex): drop SessionStart hook, bootstrap via `trellis-start` skill (#240, #242). Codex fires SessionStart for every spawn, and its hook input exposes no `agent_id` / `agent_type` field (`openai/codex#16226`) — so the dispatch directive in `codex/hooks/session-start.py` kept reaching sub-agent sessions, the sub-agent mistook itself for the main session and re-dispatched its own sub-agent (recursive turtles). The 0.5.4 patch (`#237`) added a self-exemption clause but it sat alongside the dispatch directive in the same prompt block; LLMs kept picking the command-style instruction. Structural fix: removed the `SessionStart` entry from `codex/hooks.json`. `inject-workflow-state.py` (UserPromptSubmit hook) now injects a `<trellis-bootstrap>` block on `no_task` turns telling the AI to invoke `$trellis-start` once to load workflow context. Codex configurator additionally writes the new skill to `.agents/skills/trellis-start/SKILL.md` (other agent-capable platforms keep their working SessionStart hooks). Sub-agent sessions only see the existing `<sub-agent-notice>` — no command-style \"must dispatch\" text exists anywhere in the new injection, so the recursion vector is gone at source.",
+  "migrations": [],
+  "notes": "Patch on top of 0.5.4. Run `trellis update` (no `--migrate` needed). Codex users get a new `.agents/skills/trellis-start/SKILL.md` and a `hooks.json` without `SessionStart` wiring; other platforms unchanged."
+}

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

@@ -75,6 +75,22 @@ Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份
 Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
 </first-reply-notice>"""
 
+SUB_AGENT_NOTICE = """<sub-agent-notice>
+SUB-AGENT NOTICE - READ FIRST IF SPAWNED VIA spawn_agent
+
+If your parent session spawned you via spawn_agent with an explicit task
+message above this hook output, that message is your only job.
+- Execute the parent message exactly as written, then return.
+- Ignore all Trellis workflow guidance below this notice.
+- Do NOT call task.py start, task.py add-context, or task.py archive.
+- Do NOT call wait_agent or spawn_agent.
+- Do NOT modify .trellis/tasks/* or any other file unless the parent message
+  explicitly asks for that.
+
+If you are the main interactive Codex session and the user is typing at the
+terminal with no parent agent, use the workflow guidance below normally.
+</sub-agent-notice>"""
+
 
 def should_skip_injection() -> bool:
     if os.environ.get("TRELLIS_HOOKS") == "0":
@@ -336,6 +352,9 @@ def main() -> None:
 
     output = StringIO()
 
+    output.write(SUB_AGENT_NOTICE)
+    output.write("\n\n")
+
     output.write("""<session-context>
 You are starting a new session in a Trellis-managed project.
 Read and follow all instructions below carefully.

package/dist/templates/codex/hooks.json

@@ -1,17 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "{{PYTHON_CMD}} .codex/hooks/session-start.py",
-            "timeout": 15,
-            "statusMessage": "Loading Trellis context..."
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -36,6 +36,47 @@ from pathlib import Path
 from typing import Optional
 
 
+CODEX_SUB_AGENT_NOTICE = """<sub-agent-notice>
+SUB-AGENT NOTICE - READ FIRST IF SPAWNED VIA spawn_agent
+
+If your parent session spawned you via spawn_agent with an explicit task
+message above this hook output, that message is your only job.
+- Execute the parent message exactly as written, then return.
+- Ignore all Trellis workflow guidance below this notice.
+- Do NOT call task.py start, task.py add-context, or task.py archive.
+- Do NOT call wait_agent or spawn_agent.
+- Do NOT modify .trellis/tasks/* or any other file unless the parent message
+  explicitly asks for that.
+
+If you are the main interactive Codex session and the user is typing at the
+terminal with no parent agent, use the workflow guidance below normally.
+</sub-agent-notice>"""
+
+
+# Bootstrap notice for Codex while the session has no active task. Replaces the
+# heavyweight SessionStart context injection — instead of pushing 9.5 KB of
+# workflow text up front, we just nudge the AI to read the `trellis-start` skill once.
+# The nudge keeps showing up while status == "no_task" (cheap text, AI won't
+# re-read after the first time). Once a task is created the breadcrumb status
+# flips and this notice stops appearing automatically. Sub-agents are warded
+# off by the <sub-agent-notice> above plus the explicit exemption below.
+CODEX_NO_TASK_BOOTSTRAP_NOTICE = """<trellis-bootstrap>
+You are running in a Trellis-managed Codex session and there is no active task yet.
+If you have not already loaded Trellis context this session, read the `trellis-start` skill once:
+
+  $trellis-start
+
+(equivalent to reading `.agents/skills/trellis-start/SKILL.md` and following its Steps 1-3)
+
+The skill walks you through workflow.md, dev profile, git status, active tasks, and spec
+indexes. Then route the user's request per the <workflow-state> A/B/C rules below.
+
+Sub-agent exemption: if you are a sub-agent (spawned via spawn_agent with a parent task
+message), DO NOT read `$trellis-start`. Execute the parent message directly as instructed by the
+<sub-agent-notice> above.
+</trellis-bootstrap>"""
+
+
 # ---------------------------------------------------------------------------
 # CWD-robust Trellis root discovery (fixes hook-path-robustness for this hook)
 # ---------------------------------------------------------------------------
@@ -219,11 +260,19 @@ def main() -> int:
         task_id, status, source = task
         breadcrumb = build_breadcrumb(task_id, status, templates, source)
 
+    platform = _detect_platform(data)
+    if platform == "codex":
+        parts: list[str] = [CODEX_SUB_AGENT_NOTICE]
+        if task is None:
+            parts.append(CODEX_NO_TASK_BOOTSTRAP_NOTICE)
+        parts.append(breadcrumb)
+        breadcrumb = "\n\n".join(parts)
+
     # Gemini CLI 0.40.x rejects "UserPromptSubmit" — its per-turn event is
     # named "BeforeAgent". Other platforms (Claude/Cursor/Qoder/CodeBuddy/
     # Droid/Codex/Copilot) accept the original Claude-style name.
     hook_event_name = (
-        "BeforeAgent" if _detect_platform(data) == "gemini" else "UserPromptSubmit"
+        "BeforeAgent" if platform == "gemini" else "UserPromptSubmit"
     )
 
     output = {

package/package.json

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