@mindfoldhq/trellis 0.6.6 → 0.6.8

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

@@ -96,6 +96,9 @@ def _detect_platform(input_data: dict) -> str | None:
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
     env_map = {
+        # ZCode may set both ZCODE_PROJECT_DIR and CLAUDE_PROJECT_DIR; check
+        # ZCODE first so ZCode sessions aren't misdetected as claude.
+        "ZCODE_PROJECT_DIR": "zcode",
         "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
@@ -128,6 +131,8 @@ def _detect_platform(input_data: dict) -> str | None:
         return "kiro"
     if ".trae" in script_parts:
         return "trae"
+    if ".zcode" in script_parts:
+        return "zcode"
     return None
 
 
@@ -223,28 +228,50 @@ def _read_trellis_config(root: Path) -> dict:
         return {}
 
 
-def _codex_mode_banner(config: dict) -> str:
-    """Emit a `<codex-mode>` banner for the additionalContext payload.
+def _resolve_codex_dispatch_mode(config: dict) -> str:
+    """Normalize `codex.dispatch_mode` from .trellis/config.yaml to "auto" or "inline".
 
-    Reads `codex.dispatch_mode` from .trellis/config.yaml; defaults to
-    `inline` when missing or invalid because Codex sub-agents run with
-    `fork_turns="none"` isolation and can't inherit the parent session's
-    task context. The banner makes the active mode explicit to Codex AI
-    per turn, complementing the workflow-state body which is per-status.
-    Mode tells AI which dispatch protocol to follow; workflow-state tells
-    AI what step it's at.
+    Defaults to `auto`. The legacy `sub-agent` value is an alias for `auto`.
+    Any other explicit value (including invalid ones) falls back to `inline`
+    without per-turn warnings. Shared by `_codex_mode_banner` (the per-turn
+    banner) and `resolve_breadcrumb_key` (the breadcrumb tag key) so the two
+    stay in lockstep.
     """
-    mode = "inline"
+    mode = "auto"
     if isinstance(config, dict):
         codex_cfg = config.get("codex")
         if isinstance(codex_cfg, dict):
-            cfg_mode = codex_cfg.get("dispatch_mode")
-            if cfg_mode in ("inline", "sub-agent"):
-                mode = cfg_mode
-    if mode == "sub-agent":
+            cfg_mode = str(codex_cfg.get("dispatch_mode", mode)).strip().lower()
+            if cfg_mode == "inline":
+                mode = "inline"
+            elif cfg_mode in ("auto", "sub-agent"):
+                mode = "auto"
+            else:
+                mode = "inline"
+    return mode
+
+
+def _codex_mode_banner(config: dict) -> str:
+    """Emit a `<codex-mode>` banner for the additionalContext payload.
+
+    Reads `codex.dispatch_mode` from .trellis/config.yaml; defaults to
+    `auto`, which dispatches Trellis sub-agents using native Codex context
+    injection with a child-side fallback. This does not rely on inherited
+    parent transcripts: `fork_turns` remains caller-controlled, and
+    fresh-history sub-agents still receive their explicit delegated task and
+    inherited session configuration. `inline` is an explicit opt-out; the
+    legacy `sub-agent` value is an alias for `auto`. Invalid explicit values
+    fall back to `inline` without per-turn warnings. The banner makes the
+    active mode explicit to Codex AI per turn, complementing the workflow-state
+    body which is per-status. Mode tells AI which dispatch protocol to follow;
+    workflow-state tells AI what step it's at.
+    """
+    mode = _resolve_codex_dispatch_mode(config)
+    if mode == "auto":
         meaning = (
-            "sub-agent: implement/check work defaults to Trellis sub-agents; "
-            "the main session still coordinates, clarifies, updates specs, commits, and finishes."
+            "auto: implement/check work defaults to Trellis sub-agents; native Codex "
+            "context injection is preferred and child-side loading is the fallback. "
+            "The main session still coordinates, clarifies, updates specs, commits, and finishes."
         )
     else:
         meaning = (
@@ -259,22 +286,17 @@ def resolve_breadcrumb_key(
 ) -> str:
     """Pick the breadcrumb tag key based on Codex dispatch_mode.
 
-    Codex defaults to ``inline`` because sub-agents run with ``fork_turns="none"``
-    isolation and can't inherit the parent session's task context. Users can
-    opt into ``codex.dispatch_mode: sub-agent`` in ``.trellis/config.yaml``
-    to use the parallel ``<status>-inline`` tag → ``<status>`` flip. Invalid
-    or missing values fall back to inline.
+    Codex defaults to ``auto`` and therefore uses the ordinary ``<status>``
+    breadcrumb for native SubagentStart dispatch with child-side fallback;
+    it does not depend on an inherited parent transcript. ``inline`` selects
+    the parallel ``<status>-inline`` tag; ``sub-agent`` remains an alias for
+    ``auto``. Invalid explicit values fall back to inline without per-turn
+    warnings.
 
     Non-codex platforms return the plain status unchanged.
     """
     if platform == "codex":
-        mode = "inline"
-        if isinstance(config, dict):
-            codex_cfg = config.get("codex")
-            if isinstance(codex_cfg, dict):
-                cfg_mode = codex_cfg.get("dispatch_mode")
-                if cfg_mode in ("inline", "sub-agent"):
-                    mode = cfg_mode
+        mode = _resolve_codex_dispatch_mode(config)
         return f"{status}-inline" if mode == "inline" else status
     return status
 

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

@@ -68,8 +68,14 @@ def _normalize_windows_shell_path(path_str: str) -> str:
 
 
 FIRST_REPLY_NOTICE = """<first-reply-notice>
-First visible reply: say once in Chinese that Trellis SessionStart context is loaded, then answer directly.
-This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+On the first visible assistant reply in this session, briefly acknowledge that Trellis SessionStart context loaded.
+Choose the acknowledgment language in this order:
+1. Use the language of the user's current request (the user message that triggered this reply).
+2. If that request has no clear natural language, use an explicitly established project communication language.
+3. If neither provides a language, output the language-neutral fallback exactly: `Trellis SessionStart ✓`.
+Continue directly with the user's request after the acknowledgment.
+The acknowledgment must not alter the language used for the remainder of the response.
+This notice is one-shot: do not repeat it after the first visible assistant reply in this session.
 </first-reply-notice>"""
 
 # Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
@@ -138,6 +144,7 @@ def should_skip_injection() -> bool:
         "KIRO_NON_INTERACTIVE",
         "COPILOT_NON_INTERACTIVE",
         "TRAE_NON_INTERACTIVE",
+        "ZCODE_NON_INTERACTIVE",
     ]
     return any(os.environ.get(var) == "1" for var in non_interactive_vars)
 
@@ -188,6 +195,9 @@ def _detect_platform(input_data: dict) -> str | None:
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
     env_map = {
+        # ZCode may set both ZCODE_PROJECT_DIR and CLAUDE_PROJECT_DIR; check
+        # ZCODE first so ZCode sessions aren't misdetected as claude.
+        "ZCODE_PROJECT_DIR": "zcode",
         "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
@@ -220,6 +230,8 @@ def _detect_platform(input_data: dict) -> str | None:
         return "kiro"
     if ".trae" in script_parts:
         return "trae"
+    if ".zcode" in script_parts:
+        return "zcode"
     return None
 
 
@@ -744,6 +756,7 @@ def main():
         "KIRO_PROJECT_DIR",
         "COPILOT_PROJECT_DIR",
         "TRAE_PROJECT_DIR",
+        "ZCODE_PROJECT_DIR",
     ]
     project_dir = None
     for var in project_dir_env_vars:
@@ -826,15 +839,22 @@ Context loaded. Follow <task-status>. Load workflow/spec/task details only when
         print(context_text, flush=True)
         return
 
-    result = {
-        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot format
+    platform = _detect_platform(hook_input)
+    result: dict[str, object] = {
+        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot / Trae /
+        # ZCode format.
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": context_text,
         },
-        # Cursor sessionStart format (top-level snake_case per Cursor docs)
-        "additional_context": context_text,
     }
+    # Cursor sessionStart format (top-level snake_case per Cursor docs).
+    # ZCode reads BOTH `hookSpecificOutput.additionalContext` and top-level
+    # `additional_context` without deduplication, so emitting both keys would
+    # duplicate the context in the conversation. Keep the previous shared output
+    # shape for every other platform.
+    if platform != "zcode":
+        result["additional_context"] = context_text
 
     # Output JSON - stdout is already configured for UTF-8
     print(json.dumps(result, ensure_ascii=False), flush=True)

package/dist/templates/trellis/config.yaml

@@ -99,12 +99,14 @@ channel:
 #-------------------------------------------------------------------------------
 # Codex (dispatch behavior)
 #-------------------------------------------------------------------------------
-# Codex-only knob; other platforms ignore it. Default ("inline") makes the
-# main Codex agent edit code directly because Codex sub-agents run with
-# `fork_turns="none"` isolation and can't inherit the parent session's
-# task context. Set to "sub-agent" to opt into the legacy dispatch model
-# (main agent spawns trellis-implement / trellis-check / trellis-research
-# sub-agents).
+# Codex-only knob; other platforms ignore it. Default ("auto") dispatches
+# trellis-implement / trellis-check / trellis-research sub-agents. This does
+# not rely on inherited parent transcripts: `fork_turns` remains
+# caller-controlled, while Codex's native SubagentStart hook injects task
+# context when trusted and child-side loading remains the fallback when it is
+# unavailable. Set to "inline" only to keep implementation and checks in the
+# main session. "sub-agent" remains a backwards-compatible alias for "auto".
+# Invalid explicit values safely use inline mode.
 #
 # codex:
-#   dispatch_mode: inline  # or "sub-agent" to dispatch trellis-* sub-agents
+#   dispatch_mode: auto  # or "inline"; legacy alias: "sub-agent"

package/dist/templates/trellis/scripts/common/active_task.py

@@ -44,6 +44,9 @@ _KNOWN_PLATFORMS = {
     "copilot",
     "pi",
     "trae",
+    "grok",
+    "kimi",
+    "zcode",
 }
 
 _ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
@@ -59,6 +62,11 @@ _ENV_SESSION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
     ("copilot", ("COPILOT_SESSION_ID", "COPILOT_SESSIONID")),
     ("pi", ("PI_SESSION_ID", "PI_SESSIONID")),
     ("trae", ("TRAE_SESSION_ID",)),
+    # ZCode reuses CLAUDE_SESSION_ID (it does not document a ZCODE_SESSION_ID).
+    # Platform-scoped lookup (_iter_env_keys filters by platform name), so this
+    # only fires when the resolver already detected "zcode" — no collision with
+    # the claude entry above.
+    ("zcode", ("CLAUDE_SESSION_ID",)),
 )
 _ENV_CONVERSATION_KEYS: tuple[tuple[str, tuple[str, ...]], ...] = (
     ("cursor", ("CURSOR_CONVERSATION_ID", "CURSOR_CONVERSATIONID")),
@@ -78,6 +86,12 @@ _ENV_PLATFORM_ALIASES = {
     "factory-ai": "droid",
     "github-copilot": "copilot",
 }
+# ZCode intentionally reuses CLAUDE_SESSION_ID. Hooks know the host is ZCode,
+# while later shell commands see only the shared env name and resolve it through
+# the Claude entry. Canonicalize both paths to one runtime filename.
+_CONTEXT_KEY_PLATFORM_ALIASES = {
+    "zcode": "claude",
+}
 
 
 @dataclass(frozen=True)
@@ -191,6 +205,7 @@ def _detect_platform(platform_input: dict[str, Any] | None, platform: str | None
 
 
 def _context_key(platform_name: str, kind: str, value: str) -> str:
+    platform_name = _CONTEXT_KEY_PLATFORM_ALIASES.get(platform_name, platform_name)
     if kind == "transcript":
         return f"{platform_name}_transcript_{_hash_value(value)}"
     safe_value = _sanitize_key(value)
@@ -382,15 +397,18 @@ def _lookup_cursor_shell_ticket_context_key() -> str | None:
 def resolve_context_key(
     platform_input: dict[str, Any] | None = None,
     platform: str | None = None,
+    *,
+    allow_environment_context: bool = True,
 ) -> str | None:
     """Resolve a stable session/window context key, if one is available.
 
     `TRELLIS_CONTEXT_ID` is an explicit context-key override used by CLI
     scripts and subprocesses. It does not store the task itself.
     """
-    override = _string_value(os.environ.get("TRELLIS_CONTEXT_ID"))
-    if override:
-        return _sanitize_key(override) or _hash_value(override)
+    if allow_environment_context:
+        override = _string_value(os.environ.get("TRELLIS_CONTEXT_ID"))
+        if override:
+            return _sanitize_key(override) or _hash_value(override)
 
     data = _as_dict(platform_input)
     platform_name = _detect_platform(data, platform) if data or platform else None
@@ -408,11 +426,12 @@ def resolve_context_key(
         if transcript_path:
             return _context_key(platform_name or "session", "transcript", transcript_path)
 
-    env_context_key = _lookup_env_context_key(platform_name)
-    if env_context_key:
-        return env_context_key
+    if allow_environment_context:
+        env_context_key = _lookup_env_context_key(platform_name)
+        if env_context_key:
+            return env_context_key
 
-    if platform_name in (None, "session", "cursor"):
+    if allow_environment_context and platform_name in (None, "session", "cursor"):
         return _lookup_cursor_shell_ticket_context_key()
     return None
 
@@ -471,17 +490,24 @@ def resolve_active_task(
     repo_root: Path,
     platform_input: dict[str, Any] | None = None,
     platform: str | None = None,
+    *,
+    allow_single_session_fallback: bool = True,
+    allow_environment_context: bool = True,
 ) -> ActiveTask:
     """Resolve the active task from session runtime state only.
 
     A stale session task is returned as stale. Missing context identity or a
     missing/empty session context falls back to single-session inference: if
     exactly one session file exists in the runtime, return its task with
-    source_type="session-fallback" — covers class-2 platform sub-agents (codex,
-    copilot, gemini, qoder) that don't inherit the parent's session id. ≥2
+    source_type="session-fallback" — covers pull-based platform sub-agents
+    (copilot, gemini, qoder) that don't inherit the parent's session id. ≥2
     files or 0 files yield ActiveTask(None) — refuses to guess across windows.
     """
-    context_key = resolve_context_key(platform_input, platform)
+    context_key = resolve_context_key(
+        platform_input,
+        platform,
+        allow_environment_context=allow_environment_context,
+    )
     if context_key:
         context = _read_json(_context_path(repo_root, context_key)) or {}
         task_ref = _string_value(context.get("current_task"))
@@ -489,9 +515,10 @@ def resolve_active_task(
         if active:
             return active
 
-    fallback = _resolve_single_session_fallback(repo_root)
-    if fallback is not None:
-        return fallback
+    if allow_single_session_fallback:
+        fallback = _resolve_single_session_fallback(repo_root)
+        if fallback is not None:
+            return fallback
 
     return ActiveTask(None, "none", context_key)
 

package/dist/templates/trellis/scripts/common/cli_adapter.py

@@ -20,6 +20,9 @@ Supported platforms:
 - droid: Factory Droid (commands-based)
 - pi: Pi Agent (extension-backed)
 - trae: Trae IDE (IDE-only, hooks-based)
+- omp: Oh My Pi
+- grok: Grok Build (pull-based skills/agents; no hook context injection)
+- kimi: Kimi Code (pull-based skills; commands delivered as skills; no hook context injection)
 
 Usage:
     from common.cli_adapter import CLIAdapter
@@ -56,6 +59,8 @@ Platform = Literal[
     "pi",
     "trae",
     "omp",
+    "grok",
+    "kimi",
 ]
 
 
@@ -134,6 +139,10 @@ class CLIAdapter:
             return ".trae"
         elif self.platform == "omp":
             return ".omp"
+        elif self.platform == "grok":
+            return ".grok"
+        elif self.platform == "kimi":
+            return ".kimi-code"
         else:
             return ".claude"
 
@@ -191,7 +200,8 @@ class CLIAdapter:
                     filename = filename[:-3]
                 return prompts_dir / f"trellis-{filename}.md"
             return prompts_dir / Path(*parts)
-        if self.platform == "omp":
+        # OMP and Grok: flat slash commands under .{platform}/commands/trellis-<name>.md
+        if self.platform in ("omp", "grok"):
             commands_dir = self.get_config_dir(project_root) / "commands"
             if not parts:
                 return commands_dir
@@ -202,6 +212,17 @@ class CLIAdapter:
                 return commands_dir / f"trellis-{filename}.md"
             return commands_dir / Path(*parts)
 
+        # Kimi: commands are skills under .kimi-code/skills/trellis-<name>/SKILL.md
+        if self.platform == "kimi":
+            skills_dir = self.get_config_dir(project_root) / "skills"
+            if not parts:
+                return skills_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                if filename.endswith(".md"):
+                    filename = filename[:-3]
+                return skills_dir / f"trellis-{filename}" / "SKILL.md"
+            return skills_dir / Path(*parts)
 
         if self.platform == "devin":
             workflow_dir = self.get_config_dir(project_root) / "workflows"
@@ -286,8 +307,10 @@ class CLIAdapter:
             return f".factory/commands/trellis/{name}.md"
         elif self.platform == "pi":
             return f".pi/prompts/trellis-{name}.md"
-        elif self.platform == "omp":
-            return f".omp/commands/trellis-{name}.md"
+        elif self.platform in ("omp", "grok"):
+            return f"{self.config_dir_name}/commands/trellis-{name}.md"
+        elif self.platform == "kimi":
+            return f".kimi-code/skills/trellis-{name}/SKILL.md"
         else:
             return f"{self.config_dir_name}/commands/trellis/{name}.md"
 
@@ -329,6 +352,10 @@ class CLIAdapter:
             return {}
         elif self.platform == "omp":
             return {}
+        elif self.platform == "grok":
+            return {}
+        elif self.platform == "kimi":
+            return {}
         else:
             return {"CLAUDE_NON_INTERACTIVE": "1"}
 
@@ -422,6 +449,13 @@ class CLIAdapter:
             raise ValueError(
                 "OMP uses native task tool for agent runs; CLI agent run is not supported."
             )
+        elif self.platform == "grok":
+            # Headless single-prompt; sub-agents use in-process spawn_subagent.
+            cmd = ["grok", "-p", prompt, "--yolo"]
+        elif self.platform == "kimi":
+            # Headless single-prompt with auto-approval; sub-agents are the
+            # built-in coder/explore/plan agents dispatched in-session.
+            cmd = ["kimi", "-p", prompt, "--yolo"]
 
         else:  # claude
             cmd = ["claude", "-p"]
@@ -496,6 +530,10 @@ class CLIAdapter:
             raise ValueError(
                 "OMP uses native task tool for agent runs; CLI resume is not supported."
             )
+        elif self.platform == "grok":
+            return ["grok", "-c"]
+        elif self.platform == "kimi":
+            return ["kimi", "--session", session_id]
         else:
             return ["claude", "--resume", session_id]
 
@@ -574,6 +612,10 @@ class CLIAdapter:
             return "trae"
         elif self.platform == "omp":
             return "omp"
+        elif self.platform == "grok":
+            return "grok"
+        elif self.platform == "kimi":
+            return "kimi"
         else:
             return "claude"
 
@@ -584,7 +626,15 @@ class CLIAdapter:
         Claude Code, OpenCode, iFlow, and Codex support CLI agent execution.
         Cursor is IDE-only and doesn't support CLI agents.
         """
-        return self.platform in ("claude", "opencode", "iflow", "codex", "pi")
+        return self.platform in (
+            "claude",
+            "opencode",
+            "iflow",
+            "codex",
+            "pi",
+            "grok",
+            "kimi",
+        )
 
     @property
     def requires_agent_definition_file(self) -> bool:
@@ -671,9 +721,11 @@ def get_cli_adapter(platform: str = "claude") -> CLIAdapter:
         "pi",
         "trae",
         "omp",
+        "grok",
+        "kimi",
     ):
         raise ValueError(
-            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', 'pi', 'trae', or 'omp')"
+            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'devin', 'qoder', 'codebuddy', 'copilot', 'droid', 'pi', 'trae', 'omp', 'grok', or 'kimi')"
         )
 
     return CLIAdapter(platform=platform)  # type: ignore
@@ -698,6 +750,8 @@ _ALL_PLATFORM_CONFIG_DIRS = (
     ".pi",
     ".trae",
     ".omp",
+    ".grok",
+    ".kimi-code",
 )
 """Platform-specific config directory names used by detect_platform exclusion
 checks. `.agents/skills/` is NOT listed here: it is a shared cross-platform
@@ -768,6 +822,8 @@ def detect_platform(project_root: Path) -> Platform:
         "pi",
         "trae",
         "omp",
+        "grok",
+        "kimi",
     ):
         return env_platform  # type: ignore
 
@@ -852,6 +908,14 @@ def detect_platform(project_root: Path) -> Platform:
     if (project_root / ".omp").is_dir():
         return "omp"
 
+    # Check for .grok directory (Grok Build-specific)
+    if (project_root / ".grok").is_dir():
+        return "grok"
+
+    # Check for .kimi-code directory (Kimi Code-specific)
+    if (project_root / ".kimi-code").is_dir():
+        return "kimi"
+
     # Fallback: checkout only has the Codex shared-skills layer
     # (.agents/skills/trellis-* dirs) and no explicit platform config dir.
     # Happens on fresh clones where .codex/ is gitignored/absent but the

package/dist/templates/trellis/scripts/common/config.py

@@ -167,7 +167,7 @@ def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_SESSION_AUTO_COMMIT = True
-DEFAULT_CODEX_DISPATCH_MODE = "inline"
+DEFAULT_CODEX_DISPATCH_MODE = "auto"
 
 CONFIG_FILE = "config.yaml"
 
@@ -247,8 +247,14 @@ def get_session_auto_commit(repo_root: Path | None = None) -> bool:
 def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     """Return Codex dispatch mode.
 
-    Default is ``inline``. ``sub-agent`` is an explicit opt-in because Codex
-    sub-agents do not inherit the parent session context.
+    Default is ``auto``, which dispatches Trellis sub-agents and uses native
+    context injection with a child-side fallback. ``inline`` is an explicit
+    opt-out. ``sub-agent`` remains a backwards-compatible alias for ``auto``.
+
+    Invalid explicit configuration falls back to ``inline`` rather than
+    unexpectedly dispatching a sub-agent. This CLI-facing parser is the only
+    place that emits a warning for invalid values; hook readers fail safely
+    without producing per-turn warning noise.
     """
     config = _load_config(repo_root)
     codex = config.get("codex")
@@ -256,20 +262,22 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
         return DEFAULT_CODEX_DISPATCH_MODE
     if not isinstance(codex, dict):
         print(
-            f"[WARN] invalid codex config: {codex!r}; using {DEFAULT_CODEX_DISPATCH_MODE}",
+            f"[WARN] invalid codex config: {codex!r}; using inline",
             file=sys.stderr,
         )
-        return DEFAULT_CODEX_DISPATCH_MODE
+        return "inline"
 
     raw = codex.get("dispatch_mode", DEFAULT_CODEX_DISPATCH_MODE)
     mode = str(raw).strip().lower()
-    if mode in ("inline", "sub-agent"):
+    if mode in ("auto", "inline"):
         return mode
+    if mode == "sub-agent":
+        return "auto"
     print(
-        f"[WARN] invalid codex.dispatch_mode value: {raw!r}; using {DEFAULT_CODEX_DISPATCH_MODE}",
+        f"[WARN] invalid codex.dispatch_mode value: {raw!r}; using inline",
         file=sys.stderr,
     )
-    return DEFAULT_CODEX_DISPATCH_MODE
+    return "inline"
 
 
 def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:

package/dist/templates/trellis/scripts/common/git.py

@@ -29,3 +29,39 @@ def run_git(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
         return result.returncode, result.stdout, result.stderr
     except Exception as e:
         return 1, "", str(e)
+
+
+def resolve_default_branch(repo_root: Path) -> str | None:
+    """Resolve the repository's default branch (origin/HEAD target).
+
+    Tries the local `refs/remotes/origin/HEAD` symbolic ref first (no
+    network access), then falls back to `git remote show origin` (which
+    may hit the network but also repairs a missing/stale symbolic-ref).
+    Returns None when neither resolves, so callers can fall back to their
+    own pre-existing behavior.
+    """
+    rc, out, _ = run_git(["symbolic-ref", "refs/remotes/origin/HEAD"], cwd=repo_root)
+    if rc == 0 and out.strip():
+        return out.strip().rsplit("/", 1)[-1]
+
+    rc, out, _ = run_git(["remote", "show", "origin"], cwd=repo_root)
+    if rc == 0:
+        for line in out.splitlines():
+            line = line.strip()
+            if line.startswith("HEAD branch:"):
+                branch = line.split(":", 1)[1].strip()
+                if branch and branch != "(unknown)":
+                    return branch
+
+    return None
+
+
+def branch_exists_locally(branch: str, repo_root: Path) -> bool:
+    """Check whether a local branch ref exists in the repository."""
+    if not branch:
+        return False
+    rc, _, _ = run_git(
+        ["rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"],
+        cwd=repo_root,
+    )
+    return rc == 0

package/dist/templates/trellis/scripts/common/io.py

@@ -8,6 +8,8 @@ for JSON file operations across all Trellis scripts.
 from __future__ import annotations
 
 import json
+import os
+import tempfile
 from pathlib import Path
 
 
@@ -25,13 +27,35 @@ def read_json(path: Path) -> dict | None:
 def write_json(path: Path, data: dict) -> bool:
     """Write dict to JSON file with pretty formatting.
 
+    The write is atomic: content goes to a temp file in the same directory
+    and is then renamed over the target. A crash or Ctrl-C mid-write leaves
+    the existing file intact rather than truncated, so a corrupted task.json
+    can never make a task silently vanish from `task.py list`.
+
     Returns True on success, False on error.
     """
+    payload = json.dumps(data, indent=2, ensure_ascii=False)
     try:
-        path.write_text(
-            json.dumps(data, indent=2, ensure_ascii=False),
-            encoding="utf-8",
+        fd, tmp = tempfile.mkstemp(
+            dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
         )
+    except OSError:
+        return False
+
+    try:
+        try:
+            f = os.fdopen(fd, "w", encoding="utf-8")
+        except OSError:
+            # fdopen never took ownership of fd; close it ourselves.
+            os.close(fd)
+            raise
+        with f:
+            f.write(payload)
+        os.replace(tmp, path)
         return True
-    except (OSError, IOError):
+    except OSError:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
         return False