@blulotus/trellis 0.7.0 → 0.7.2

package/dist/templates/shared-hooks/inject-subagent-context.py

@@ -90,26 +90,14 @@ def find_repo_root(start_path: str) -> str | None:
 def _detect_platform(input_data: dict) -> str | None:
     if _hook_event_name(input_data) == "SubagentStart":
         return "codex"
-    if isinstance(input_data.get("cursor_version"), str):
-        return "cursor"
-    # CLAUDE_PROJECT_DIR is a compatibility alias that several hosts set
-    # alongside their own variable — CodeBuddy, ZCode and Trae all do. It must
-    # therefore be checked LAST, or every one of them is detected as claude and
-    # the context key becomes `claude_<their-session-id>`. That key does not
-    # match the session file `task.py start` wrote under the host's real name,
-    # so the sub-agent starts with no task context while the pointer exists on
-    # disk. Same fix as inject-workflow-state.py and session-start.py; this
-    # third copy was missed when those two were corrected.
+    # CLAUDE_PROJECT_DIR is a compatibility alias other hosts may also set, so
+    # it is checked last — a vendor-specific key always wins. Detecting the
+    # wrong host would build the context key `claude_<their-session-id>`, which
+    # never matches the session file `task.py start` wrote under the host's
+    # real name, so the sub-agent would start with no task context while the
+    # pointer exists on disk.
     env_map = {
-        "ZCODE_PROJECT_DIR": "zcode",
-        "CURSOR_PROJECT_DIR": "cursor",
-        "CODEBUDDY_PROJECT_DIR": "codebuddy",
-        "FACTORY_PROJECT_DIR": "droid",
-        "GEMINI_PROJECT_DIR": "gemini",
-        "QODER_PROJECT_DIR": "qoder",
-        "KIRO_PROJECT_DIR": "kiro",
-        "COPILOT_PROJECT_DIR": "copilot",
-        "TRAE_PROJECT_DIR": "trae",
+        "CODEX_PROJECT_DIR": "codex",
         # Last: the shared alias, only meaningful once no vendor key matched.
         "CLAUDE_PROJECT_DIR": "claude",
     }
@@ -119,20 +107,8 @@ def _detect_platform(input_data: dict) -> str | None:
     script_parts = set(Path(sys.argv[0]).parts)
     if ".claude" in script_parts:
         return "claude"
-    if ".cursor" in script_parts:
-        return "cursor"
-    if ".gemini" in script_parts:
-        return "gemini"
-    if ".qoder" in script_parts:
-        return "qoder"
-    if ".codebuddy" in script_parts:
-        return "codebuddy"
-    if ".factory" in script_parts:
-        return "droid"
-    if ".kiro" in script_parts:
-        return "kiro"
-    if ".zcode" in script_parts:
-        return "zcode"
+    if ".codex" in script_parts:
+        return "codex"
     return None
 
 
@@ -888,8 +864,8 @@ def _handle_codex_subagent_start(input_data: dict) -> None:
     if not subagent_type or not parent_session_id:
         return
 
-    # Payload cwd first, then our own — some hosts (CodeBuddy IDE 4.10.4)
-    # report "/" for every hook event. See inject-workflow-state.py.
+    # Payload cwd first, then our own — a host may report "/" for every hook
+    # event. See inject-workflow-state.py.
     repo_root = None
     for candidate in (_string_value(input_data.get("cwd")), os.getcwd()):
         if not candidate:
@@ -938,11 +914,11 @@ def _handle_codex_subagent_start(input_data: dict) -> None:
 
 
 def _extract_subagent_name(value: Any) -> str:
-    """Extract a sub-agent name from common platform encodings.
+    """Extract a sub-agent name from the shapes hook JSON can carry.
 
-    Cursor's native Task args encode custom sub-agents as a protobuf oneof,
-    which can appear in hook JSON as either ``{"custom": {"name": "..."}}``
-    or ``{"type": {"case": "custom", "value": {"name": "..."}}}``.
+    A plain string is the common case; a host may instead nest the name as
+    ``{"custom": {"name": "..."}}`` or
+    ``{"type": {"case": "custom", "value": {"name": "..."}}}``.
     """
     direct = _string_value(value)
     if direct:
@@ -1013,14 +989,8 @@ def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:
     """Parse hook input across different platform formats.
 
     Returns (subagent_type, original_prompt, tool_input).
-    Handles:
-    - Claude Code / Qoder / Droid: tool_name=Task|Agent, tool_input.subagent_type
-    - CodeBuddy: tool_name=task (IDE) or Task (CLI), tool_input.subagent_name
-    - Cursor: tool_name=Task|Subagent, tool_input.subagent_type
-    - Copilot CLI: toolName=task (camelCase key, lowercase value)
-    - ZCode: toolName=Agent, toolInput/tool_input.subagent_type
-    - Gemini CLI: tool_name IS the agent name (BeforeTool matcher already filtered)
-    - Kiro: agentSpawn hook, agent_name field at top level
+    Handles the Claude Code shape: tool_name=Task|Agent with
+    tool_input.subagent_type (camelCase key spellings accepted too).
     """
     tool_input = input_data.get("tool_input", {})
     if not isinstance(tool_input, dict):
@@ -1037,21 +1007,6 @@ def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:
             tool_input,
         )
 
-    # Kiro: agentSpawn hook passes agent_name at top level
-    agent_name = input_data.get("agent_name", "")
-    if agent_name:
-        return agent_name, tool_input.get("prompt", input_data.get("prompt", "")), tool_input
-
-    # Gemini CLI: BeforeTool where tool_name IS the agent name
-    # (matcher already ensured it's one of our agents)
-    if tool_name in AGENTS_ALL:
-        return tool_name, tool_input.get("prompt", ""), tool_input
-
-    # Copilot CLI: toolName field (camelCase), value might be the agent name
-    tool_name_camel = input_data.get("toolName", "")
-    if tool_name_camel in AGENTS_ALL:
-        return tool_name_camel, input_data.get("toolArgs", ""), tool_input
-
     return "", "", tool_input
 
 
@@ -1140,32 +1095,15 @@ def main():
     if not context:
         sys.exit(0)
 
-    # Return updated input. Most platforms ignore unrecognized fields, so we
-    # include multiple formats. ZCode is stricter; live probing confirmed the
-    # nested Claude-compatible shape below reaches the sub-agent prompt.
+    # Return updated input in the Claude Code PreToolUse shape.
     updated = {**tool_input, "prompt": new_prompt}
-    if _detect_platform(input_data) == "zcode":
-        output = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "allow",
-                "updatedInput": updated,
-            }
-        }
-    else:
-        output = {
-            # Claude Code / Qoder / CodeBuddy / Droid format
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "allow",
-                "updatedInput": updated,
-            },
-            # Cursor format
-            "permission": "allow",
-            "updated_input": updated,
-            # Gemini format
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
             "updatedInput": updated,
         }
+    }
 
     print(json.dumps(output, ensure_ascii=False))
     sys.exit(0)

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

@@ -1,15 +1,16 @@
 #!/usr/bin/env python3
 """Trellis per-turn breadcrumb hook (UserPromptSubmit / BeforeAgent equivalent).
 
-Runs on every user prompt. Resolves the active task through Trellis'
-session-aware active task resolver and emits a short <workflow-state>
-block reminding the main AI what task is active and its expected flow.
-
-The emitted ``hookEventName`` field is platform-aware: most hosts expect
-``UserPromptSubmit`` (Claude Code naming, also accepted by Cursor / Qoder /
-CodeBuddy / Droid / Codex / Copilot wiring), but Gemini CLI 0.40.x renamed
-its per-turn event to ``BeforeAgent`` and its schema validator rejects the
-legacy name. ``_detect_platform`` picks the right value at runtime.
+Runs on every user prompt, but emits nothing until the session opts into the
+Trellis workflow by invoking `trellis-start`, `trellis-continue` or
+`trellis-finish-work` (each runs `task.py engage`). Once engaged, it resolves the
+active task through Trellis' session-aware active task resolver and emits a short
+<workflow-state> block reminding the main AI what task is active and its expected
+flow.
+
+The emitted ``hookEventName`` field is ``UserPromptSubmit`` (Claude Code
+naming, also accepted by Codex wiring). ``_detect_platform`` reports which
+host is running so the payload shape can stay host-aware.
 Breadcrumb text is pulled exclusively from the resolved workflow file's
 [workflow-state:STATUS] tag blocks — the active task may select a
 per-task variant (`.trellis/workflows/<id>.md` via task.json `workflow`),
@@ -20,14 +21,10 @@ missing or a tag is absent, the breadcrumb degrades to a generic
 the broken state instead of the hook silently masking it.
 
 Which platforms register this hook is decided by SHARED_HOOKS_BY_PLATFORM
-in templates/shared-hooks/index.ts — currently Claude, Codex, Gemini,
-Qoder, Copilot, CodeBuddy, Droid, Kiro, Trae and ZCode. That table is the
-source of truth; each listed platform's collect<Platform>Templates() pulls
-this file into its template map through collectSharedHooks(), and a single
-writer puts that map on disk at init time. Kiro wires this via the CLI
-custom agent's ``hooks.userPromptSubmit`` and the IDE ``.kiro.hook``
-``promptSubmit`` event; its output branch emits a plain-text breadcrumb
-(Kiro adds hook stdout directly to the conversation context).
+in templates/shared-hooks/index.ts — currently Claude Code and Codex. That
+table is the source of truth; each listed platform's
+collect<Platform>Templates() pulls this file into its template map through
+collectSharedHooks(), and a single writer puts that map on disk at init time.
 
 Silent exit 0 cases (no output):
   - No .trellis/ directory found (not a Trellis project)
@@ -67,14 +64,6 @@ if sys.platform.startswith("win"):
 from typing import Optional
 
 
-# Bootstrap notice for Codex while the session has no active task. Codex does not
-# get the full SessionStart overview; this short reminder points the main session
-# at the start skill once and leaves the per-turn state block compact.
-CODEX_NO_TASK_BOOTSTRAP_NOTICE = """<trellis-bootstrap>
-If you have not already loaded Trellis context this session, read the `trellis-start` skill once.
-</trellis-bootstrap>"""
-
-
 # ---------------------------------------------------------------------------
 # CWD-robust Trellis root discovery (fixes hook-path-robustness for this hook)
 # ---------------------------------------------------------------------------
@@ -98,26 +87,13 @@ def find_trellis_root(start: Path) -> Optional[Path]:
 # ---------------------------------------------------------------------------
 
 def _detect_platform(input_data: dict) -> str | None:
-    if isinstance(input_data.get("cursor_version"), str):
-        return "cursor"
-    # CLAUDE_PROJECT_DIR is a compatibility alias that several hosts set
-    # alongside their own variable — CodeBuddy, ZCode and Trae all do. It must
-    # therefore be checked LAST, or every one of them is detected as claude and
-    # the context key becomes `claude_<their-session-id>`. That key does not
-    # match the session file `task.py start` wrote under the host's real name,
-    # so every turn reports no_task while the pointer exists on disk.
-    # Observed on CodeBuddy IDE 4.10.4: session file `codebuddy_ae54840e….json`
-    # alongside marker `update-check-claude_ae54840e….marker`, same id.
+    # CLAUDE_PROJECT_DIR is a compatibility alias other hosts may also set, so
+    # it is checked last — a vendor-specific key always wins. Detecting the
+    # wrong host would build the context key `claude_<their-session-id>`, which
+    # never matches the session file `task.py start` wrote under the host's
+    # real name, and every turn would report no_task while the pointer exists.
     env_map = {
-        "ZCODE_PROJECT_DIR": "zcode",
-        "CURSOR_PROJECT_DIR": "cursor",
-        "CODEBUDDY_PROJECT_DIR": "codebuddy",
-        "FACTORY_PROJECT_DIR": "droid",
-        "GEMINI_PROJECT_DIR": "gemini",
-        "QODER_PROJECT_DIR": "qoder",
-        "KIRO_PROJECT_DIR": "kiro",
-        "COPILOT_PROJECT_DIR": "copilot",
-        "TRAE_PROJECT_DIR": "trae",
+        "CODEX_PROJECT_DIR": "codex",
         # Last: the shared alias, only meaningful once no vendor key matched.
         "CLAUDE_PROJECT_DIR": "claude",
     }
@@ -127,24 +103,8 @@ def _detect_platform(input_data: dict) -> str | None:
     script_parts = set(Path(sys.argv[0]).parts)
     if ".claude" in script_parts:
         return "claude"
-    if ".cursor" in script_parts:
-        return "cursor"
     if ".codex" in script_parts:
         return "codex"
-    if ".gemini" in script_parts:
-        return "gemini"
-    if ".qoder" in script_parts:
-        return "qoder"
-    if ".codebuddy" in script_parts:
-        return "codebuddy"
-    if ".factory" in script_parts:
-        return "droid"
-    if ".kiro" in script_parts:
-        return "kiro"
-    if ".trae" in script_parts:
-        return "trae"
-    if ".zcode" in script_parts:
-        return "zcode"
     return None
 
 
@@ -157,6 +117,30 @@ def _resolve_active_task(root: Path, input_data: dict):
     return resolve_active_task(root, input_data, platform=_detect_platform(input_data))
 
 
+def _is_session_engaged(root: Path, input_data: dict) -> bool:
+    """Whether this session opted into the Trellis workflow.
+
+    A project too old to have `is_session_engaged` (hooks updated, `.trellis/scripts`
+    not) raises ImportError. Reporting False then would silently stop the per-turn
+    breadcrumb — the one channel that enforces the planning and commit gates — so
+    the stale-scripts case keeps the old always-inject behavior and says why.
+    """
+    scripts_dir = root / ".trellis" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import is_session_engaged  # type: ignore[import-not-found]
+    except ImportError:
+        print(
+            "trellis inject-workflow-state: .trellis/scripts predates opt-in "
+            "engagement; injecting unconditionally. Run `trellis update`.",
+            file=sys.stderr,
+        )
+        return True
+
+    return is_session_engaged(root, input_data, platform=_detect_platform(input_data))
+
+
 def get_active_task(root: Path, input_data: dict) -> Optional[tuple[str, str, str]]:
     """Return (task_id, status, source) from the current active task."""
     active = _resolve_active_task(root, input_data)
@@ -400,8 +384,8 @@ def build_breadcrumb(
 def _load_hook_input() -> dict:
     """Read hook JSON without trusting host runners to close stdin.
 
-    Kiro IDE `runCommand` and similar hook runners can leave stdin open while
-    sending no payload. A plain `json.load(sys.stdin)` then blocks forever.
+    A hook runner can leave stdin open while sending no payload. A plain
+    `json.load(sys.stdin)` then blocks forever.
     Normal hook runners write the complete JSON payload and close stdin, so the
     short daemon read preserves that path while failing closed to `{}` for
     non-piping hosts.
@@ -443,6 +427,12 @@ def main() -> int:
     if root is None:
         return 0  # not a Trellis project
 
+    # Opt-in gate, ahead of every read below: a session that never invoked an
+    # entry point gets no breadcrumb, and does not pay the task-resolution and
+    # workflow.md reads either.
+    if not _is_session_engaged(root, data):
+        return 0
+
     config = _read_trellis_config(root)
     if prompt_has_skip_keyword(data.get("prompt", ""), _resolve_skip_keyword(config)):
         return 0  # user opted out of the per-turn breadcrumb for this turn
@@ -451,8 +441,8 @@ def main() -> int:
     platform = _detect_platform(data)
     task = get_active_task(root, data)
     if task is None:
-        # No active task — still emit a breadcrumb nudging AI toward
-        # trellis-brainstorm + task.py create when user describes real work.
+        # Engaged but no active task: either the entry point has not created one
+        # yet, or `task.py finish` / archive cleared the pointer mid-session.
         no_task_key = resolve_breadcrumb_key("no_task", platform, config)
         breadcrumb = build_breadcrumb(
             None, "no_task", templates, breadcrumb_key=no_task_key
@@ -465,31 +455,11 @@ def main() -> int:
             task_id, status, templates, source_for_breadcrumb, breadcrumb_key=status_key
         )
     if platform == "codex":
-        parts: list[str] = []
-        if task is None:
-            parts.append(CODEX_NO_TASK_BOOTSTRAP_NOTICE)
-        parts.append(_codex_mode_banner(config))
-        parts.append(breadcrumb)
-        breadcrumb = "\n\n".join(parts)
-
-    # Kiro (CLI userPromptSubmit / IDE promptSubmit) adds a hook's stdout
-    # directly to the conversation context — no JSON envelope. Emit the bare
-    # breadcrumb text. Conditionally isolated: all other platforms keep the
-    # hookSpecificOutput JSON path below unchanged.
-    if platform == "kiro":
-        print(breadcrumb)
-        return 0
-
-    # 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 platform == "gemini" else "UserPromptSubmit"
-    )
+        breadcrumb = f"{_codex_mode_banner(config)}\n\n{breadcrumb}"
 
     output = {
         "hookSpecificOutput": {
-            "hookEventName": hook_event_name,
+            "hookEventName": "UserPromptSubmit",
             "additionalContext": breadcrumb,
         }
     }

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

@@ -2,6 +2,11 @@
 # -*- coding: utf-8 -*-
 """
 Session Start Hook - Inject structured context
+
+Emits nothing until the session opts into the Trellis workflow by invoking
+`trellis-start`, `trellis-continue` or `trellis-finish-work` (each runs
+`task.py engage`). The session-identity env bridge still runs unconditionally —
+it is plumbing, not context, and `task.py engage` depends on it.
 """
 from __future__ import annotations
 
@@ -67,38 +72,27 @@ def _normalize_windows_shell_path(path_str: str) -> str:
     return path_str
 
 
-_FIRST_REPLY_NOTICE_HEAD = """<first-reply-notice>
-On the first visible assistant reply in this session, briefly acknowledge that Trellis SessionStart context loaded."""
-
-_FIRST_REPLY_NOTICE_TAIL = """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>"""
-
-FIRST_REPLY_NOTICE = f"{_FIRST_REPLY_NOTICE_HEAD}\n{_FIRST_REPLY_NOTICE_TAIL}"
-
-
-def _build_first_reply_notice(update_hint: str | None) -> str:
-    """First-reply notice, carrying the Trellis update reminder when there is one.
+def _build_update_notice(update_hint: str | None) -> str:
+    """Escalate a pending Trellis update into the visible reply.
 
     The reminder has to reach the *user*, not just the model's context — a line
     buried in SessionStart context is exactly how the update step kept getting
-    skipped. This block is already the payload's one "say it out loud" channel,
-    so the hint rides along instead of growing a second mechanism.
-
-    With no hint the notice is byte-identical to the plain constant: no empty
-    block, no placeholder line.
+    skipped. So it gets an explicit "relay this out loud" instruction rather
+    than a plain state line.
+
+    Emits nothing when no update is pending, which is the normal case: the block
+    exists only on the sessions that have something to report. Replaces the old
+    <first-reply-notice>, whose other job — making the AI announce that Trellis
+    context loaded — died with opt-in engagement, where the user invoked the
+    entry point and its output is the acknowledgment.
     """
     if not update_hint:
-        return FIRST_REPLY_NOTICE
+        return ""
     return (
-        f"{_FIRST_REPLY_NOTICE_HEAD}\n"
-        f"Also relay this Trellis maintenance notice on its own line in that same reply: {update_hint}\n"
-        f"{_FIRST_REPLY_NOTICE_TAIL}"
+        "<trellis-maintenance-notice>\n"
+        "Relay this Trellis maintenance notice on its own line in your next "
+        f"visible reply, verbatim: {update_hint}\n"
+        "</trellis-maintenance-notice>\n\n"
     )
 
 
@@ -160,15 +154,7 @@ def should_skip_injection() -> bool:
         return True
     non_interactive_vars = [
         "CLAUDE_NON_INTERACTIVE",
-        "QODER_NON_INTERACTIVE",
-        "CODEBUDDY_NON_INTERACTIVE",
-        "FACTORY_NON_INTERACTIVE",
-        "CURSOR_NON_INTERACTIVE",
-        "GEMINI_NON_INTERACTIVE",
-        "KIRO_NON_INTERACTIVE",
-        "COPILOT_NON_INTERACTIVE",
-        "TRAE_NON_INTERACTIVE",
-        "ZCODE_NON_INTERACTIVE",
+        "CODEX_NON_INTERACTIVE",
     ]
     return any(os.environ.get(var) == "1" for var in non_interactive_vars)
 
@@ -216,26 +202,13 @@ def _format_git_state(repo_root: Path) -> str:
 
 
 def _detect_platform(input_data: dict) -> str | None:
-    if isinstance(input_data.get("cursor_version"), str):
-        return "cursor"
-    # CLAUDE_PROJECT_DIR is a compatibility alias that several hosts set
-    # alongside their own variable — CodeBuddy, ZCode and Trae all do. It must
-    # therefore be checked LAST, or every one of them is detected as claude and
-    # the context key becomes `claude_<their-session-id>`. That key does not
-    # match the session file `task.py start` wrote under the host's real name,
-    # so every turn reports no_task while the pointer exists on disk.
-    # Observed on CodeBuddy IDE 4.10.4: session file `codebuddy_ae54840e….json`
-    # alongside marker `update-check-claude_ae54840e….marker`, same id.
+    # CLAUDE_PROJECT_DIR is a compatibility alias other hosts may also set, so
+    # it is checked last — a vendor-specific key always wins. Detecting the
+    # wrong host would build the context key `claude_<their-session-id>`, which
+    # never matches the session file `task.py start` wrote under the host's
+    # real name, and every turn would report no_task while the pointer exists.
     env_map = {
-        "ZCODE_PROJECT_DIR": "zcode",
-        "CURSOR_PROJECT_DIR": "cursor",
-        "CODEBUDDY_PROJECT_DIR": "codebuddy",
-        "FACTORY_PROJECT_DIR": "droid",
-        "GEMINI_PROJECT_DIR": "gemini",
-        "QODER_PROJECT_DIR": "qoder",
-        "KIRO_PROJECT_DIR": "kiro",
-        "COPILOT_PROJECT_DIR": "copilot",
-        "TRAE_PROJECT_DIR": "trae",
+        "CODEX_PROJECT_DIR": "codex",
         # Last: the shared alias, only meaningful once no vendor key matched.
         "CLAUDE_PROJECT_DIR": "claude",
     }
@@ -245,24 +218,8 @@ def _detect_platform(input_data: dict) -> str | None:
     script_parts = set(Path(sys.argv[0]).parts)
     if ".claude" in script_parts:
         return "claude"
-    if ".cursor" in script_parts:
-        return "cursor"
     if ".codex" in script_parts:
         return "codex"
-    if ".gemini" in script_parts:
-        return "gemini"
-    if ".qoder" in script_parts:
-        return "qoder"
-    if ".codebuddy" in script_parts:
-        return "codebuddy"
-    if ".factory" in script_parts:
-        return "droid"
-    if ".kiro" in script_parts:
-        return "kiro"
-    if ".trae" in script_parts:
-        return "trae"
-    if ".zcode" in script_parts:
-        return "zcode"
     return None
 
 
@@ -275,6 +232,35 @@ def _resolve_context_key(trellis_dir: Path, input_data: dict) -> str | None:
     return resolve_context_key(input_data, platform=_detect_platform(input_data))
 
 
+def _is_session_engaged(trellis_dir: Path, input_data: dict) -> bool:
+    """Whether this session opted into the Trellis workflow.
+
+    A project too old to have `is_session_engaged` (pre-opt-in `.trellis/scripts`,
+    e.g. an install that upgraded the hooks but not the scripts) raises ImportError
+    here. Reporting False then would make Trellis look uninstalled on every
+    session with no way to diagnose it, so the stale-scripts case keeps the old
+    always-inject behavior and says why on stderr.
+    """
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import is_session_engaged  # type: ignore[import-not-found]
+    except ImportError:
+        print(
+            "trellis session-start: .trellis/scripts predates opt-in engagement; "
+            "injecting context unconditionally. Run `trellis update`.",
+            file=sys.stderr,
+        )
+        return True
+
+    return is_session_engaged(
+        trellis_dir.parent,
+        input_data,
+        platform=_detect_platform(input_data),
+    )
+
+
 def _persist_context_key_for_bash(context_key: str | None) -> None:
     """Expose Trellis session identity to later Claude Code Bash commands.
 
@@ -853,15 +839,7 @@ def main():
     # Try platform-specific env vars, hook cwd, fallback to cwd
     project_dir_env_vars = [
         "CLAUDE_PROJECT_DIR",
-        "QODER_PROJECT_DIR",
-        "CODEBUDDY_PROJECT_DIR",
-        "FACTORY_PROJECT_DIR",
-        "CURSOR_PROJECT_DIR",
-        "GEMINI_PROJECT_DIR",
-        "KIRO_PROJECT_DIR",
-        "COPILOT_PROJECT_DIR",
-        "TRAE_PROJECT_DIR",
-        "ZCODE_PROJECT_DIR",
+        "CODEX_PROJECT_DIR",
     ]
     project_dir = None
     for var in project_dir_env_vars:
@@ -876,6 +854,21 @@ def main():
     context_key = _resolve_context_key(trellis_dir, hook_input)
     _persist_context_key_for_bash(context_key)
 
+    # Context injection is opt-in. Everything below this point costs tokens, and
+    # a session that never invoked an entry point (`trellis-start` /
+    # `trellis-continue` / `trellis-finish-work`) is not doing Trellis work — an
+    # in-flight task belonging to some other window is not consent.
+    #
+    # The env bridge above runs FIRST and unconditionally: it is the only channel
+    # by which session identity reaches `task.py` in a Bash child on Claude Code,
+    # so gating it would leave `task.py engage` unable to write the very flag
+    # this check reads.
+    #
+    # An engaged session still re-enters here on /clear and /compact, which is
+    # the point: compaction drops the workflow context a long task depends on.
+    if not _is_session_engaged(trellis_dir, hook_input):
+        sys.exit(0)
+
     # Load config for scope filtering and legacy detection
     is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(
         trellis_dir,
@@ -892,8 +885,7 @@ Trellis compact SessionStart context. Use it to orient the session; load details
 </session-context>
 
 """)
-    output.write(_build_first_reply_notice(_resolve_update_hint(trellis_dir, context_key)))
-    output.write("\n\n")
+    output.write(_build_update_notice(_resolve_update_hint(trellis_dir, context_key)))
 
     # Legacy migration warning
     legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
@@ -937,29 +929,15 @@ Context loaded. Follow <task-status>. Load workflow/spec/task details only when
 
     context_text = output.getvalue()
 
-    # Kiro (CLI trellis agent agentSpawn) adds a hook's stdout directly to the
-    # conversation context — no JSON envelope. Emit the bare overview text.
-    # Conditionally isolated: all other platforms keep the JSON path below.
-    if _detect_platform(hook_input) == "kiro":
-        print(context_text, flush=True)
-        return
-
-    platform = _detect_platform(hook_input)
     result: dict[str, object] = {
-        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot / Trae /
-        # ZCode format.
+        # Claude Code / Codex format.
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": context_text,
         },
+        # Snake_case alias for hosts that read the top-level key instead.
+        "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)