@blulotus/trellis 0.7.0

package/dist/templates/shared-hooks/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared hook templates — platform-independent Python hook scripts.
+ *
+ * These scripts read only from .trellis/ paths (JSONL, prd.md, spec/) and
+ * have no platform-specific placeholders. They can be written as-is to any
+ * platform's hooks directory.
+ */
+export interface HookScript {
+    /** Filename (e.g., "session-start.py") */
+    name: string;
+    /** Script content — no placeholders, ready to write directly */
+    content: string;
+}
+export type SharedHookName = "session-start.py" | "inject-shell-session-context.py" | "inject-workflow-state.py" | "inject-subagent-context.py" | "inject-spec-context.py";
+export type SharedHookPlatform = "claude" | "cursor" | "codex" | "opencode" | "gemini" | "qoder" | "copilot" | "codebuddy" | "droid" | "kiro" | "trae" | "zcode";
+/**
+ * Which shared hooks each platform actually invokes. Single source of truth
+ * for shared-hook distribution — `collectSharedHooks` reads this table, and
+ * both `trellis init` and `trellis update` consume the map it returns.
+ *
+ * Routing rules encoded here:
+ * - `session-start.py` — shipped by every platform with a SessionStart
+ *   hook event *except* codex + copilot, which bundle a platform-specific
+ *   session-start.py under their own template dirs.
+ * - `inject-workflow-state.py` — every platform with a UserPromptSubmit
+ *   (or equivalent) event. Kiro + codex self-included; platforms without
+ *   per-turn main-session hooks are excluded.
+ * - `inject-subagent-context.py` — platforms with native sub-agent context
+ *   delivery. Most use a PreToolUse prompt mutation; Codex uses its
+ *   SubagentStart `additionalContext` event. Class-2 (pull-based) platforms
+ *   such as copilot, gemini, qoder, and trae still load context from a
+ *   self-loading agent profile.
+ * - `inject-shell-session-context.py` — platforms with a hook that fires
+ *   *before* a shell command and receives both the session id and the pending
+ *   command. That hook is the only channel by which session identity reaches
+ *   `task.py`, which runs in the shell child: no platform researched exports a
+ *   session id into that child (2026-08-05 audit of 21 platforms). Declaring a
+ *   platform here also requires an entry in its own hook config template —
+ *   `shared-hooks.test.ts` fails the build when the two disagree, because a
+ *   script on disk that nothing invokes is indistinguishable from success.
+ *   Kiro is deliberately absent: its two hook surfaces (CLI agent JSON
+ *   `hooks.{agentSpawn,userPromptSubmit}` and IDE `.kiro.hook` `when.type`)
+ *   publish no pre-tool trigger, and an unknown key in the agent JSON risks
+ *   the whole agent failing to load. Settle it by running Kiro and checking
+ *   its hook trigger list before adding it.
+ * - Kiro supports per-turn + spawn hooks on both surfaces (per the official
+ *   docs https://kiro.dev/docs/cli/hooks/): the CLI custom agent declares
+ *   `hooks.userPromptSubmit` + `hooks.agentSpawn`, and the IDE declares a
+ *   `.kiro.hook` with `when.type=promptSubmit`. So Kiro ships
+ *   `session-start.py` (agentSpawn overview), `inject-workflow-state.py`
+ *   (per-turn breadcrumb), and `inject-subagent-context.py` (sub-agent
+ *   spawn). The scripts emit a plain-text Kiro branch — Kiro adds a hook's
+ *   stdout directly to the conversation context (no JSON envelope).
+ * - `inject-spec-context.py` — path-scoped spec injection. Claude Code uses
+ *   PostToolUse Read/Edit/Write/MultiEdit; Codex and OpenCode use PreToolUse.
+ *   Codex passes the native apply_patch payload directly. OpenCode's plugin
+ *   adapts write/edit/apply_patch calls and blocks a FULL emission once so the
+ *   model sees the specs before retrying. Class-2 platforms use
+ *   `get_context.py --mode spec` pull mode instead.
+ * - Claude Code `statusLine` is intentionally not installed by default.
+ *   Users can add their own statusLine command in `.claude/settings.json`,
+ *   or opt in to the Trellis one via `trellis init --with-statusline`
+ *   (installed from `templates/claude/hooks/`, not from this table — no
+ *   other platform has a statusLine event).
+ * - ZCode (3.x) ships a workspace hook config at `.zcode/config.json` covering
+ *   SessionStart + UserPromptSubmit in the main session, plus PreToolUse for
+ *   `Agent|Task`. Live probing confirmed `hookSpecificOutput.updatedInput`
+ *   reaches the sub-agent prompt, so ZCode is class-1 and ships
+ *   `inject-subagent-context.py`.
+ */
+export declare const SHARED_HOOKS_BY_PLATFORM: Record<SharedHookPlatform, readonly SharedHookName[]>;
+/**
+ * Get all shared hook scripts. Content is platform-independent and can be
+ * written directly without placeholder resolution.
+ */
+export declare function getSharedHookScripts(): HookScript[];
+/**
+ * Get the shared hook scripts that a given platform actually registers.
+ * Drives `collectSharedHooks` so distribution never drifts from the
+ * per-platform capability declared above.
+ */
+export declare function getSharedHookScriptsForPlatform(platform: SharedHookPlatform): HookScript[];
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/shared-hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,iCAAiC,GACjC,0BAA0B,GAC1B,4BAA4B,GAC5B,wBAAwB,CAAC;AAE7B,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CA0D1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CAGd"}

package/dist/templates/shared-hooks/index.js

@@ -0,0 +1,152 @@
+/**
+ * Shared hook templates — platform-independent Python hook scripts.
+ *
+ * These scripts read only from .trellis/ paths (JSONL, prd.md, spec/) and
+ * have no platform-specific placeholders. They can be written as-is to any
+ * platform's hooks directory.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+/**
+ * Which shared hooks each platform actually invokes. Single source of truth
+ * for shared-hook distribution — `collectSharedHooks` reads this table, and
+ * both `trellis init` and `trellis update` consume the map it returns.
+ *
+ * Routing rules encoded here:
+ * - `session-start.py` — shipped by every platform with a SessionStart
+ *   hook event *except* codex + copilot, which bundle a platform-specific
+ *   session-start.py under their own template dirs.
+ * - `inject-workflow-state.py` — every platform with a UserPromptSubmit
+ *   (or equivalent) event. Kiro + codex self-included; platforms without
+ *   per-turn main-session hooks are excluded.
+ * - `inject-subagent-context.py` — platforms with native sub-agent context
+ *   delivery. Most use a PreToolUse prompt mutation; Codex uses its
+ *   SubagentStart `additionalContext` event. Class-2 (pull-based) platforms
+ *   such as copilot, gemini, qoder, and trae still load context from a
+ *   self-loading agent profile.
+ * - `inject-shell-session-context.py` — platforms with a hook that fires
+ *   *before* a shell command and receives both the session id and the pending
+ *   command. That hook is the only channel by which session identity reaches
+ *   `task.py`, which runs in the shell child: no platform researched exports a
+ *   session id into that child (2026-08-05 audit of 21 platforms). Declaring a
+ *   platform here also requires an entry in its own hook config template —
+ *   `shared-hooks.test.ts` fails the build when the two disagree, because a
+ *   script on disk that nothing invokes is indistinguishable from success.
+ *   Kiro is deliberately absent: its two hook surfaces (CLI agent JSON
+ *   `hooks.{agentSpawn,userPromptSubmit}` and IDE `.kiro.hook` `when.type`)
+ *   publish no pre-tool trigger, and an unknown key in the agent JSON risks
+ *   the whole agent failing to load. Settle it by running Kiro and checking
+ *   its hook trigger list before adding it.
+ * - Kiro supports per-turn + spawn hooks on both surfaces (per the official
+ *   docs https://kiro.dev/docs/cli/hooks/): the CLI custom agent declares
+ *   `hooks.userPromptSubmit` + `hooks.agentSpawn`, and the IDE declares a
+ *   `.kiro.hook` with `when.type=promptSubmit`. So Kiro ships
+ *   `session-start.py` (agentSpawn overview), `inject-workflow-state.py`
+ *   (per-turn breadcrumb), and `inject-subagent-context.py` (sub-agent
+ *   spawn). The scripts emit a plain-text Kiro branch — Kiro adds a hook's
+ *   stdout directly to the conversation context (no JSON envelope).
+ * - `inject-spec-context.py` — path-scoped spec injection. Claude Code uses
+ *   PostToolUse Read/Edit/Write/MultiEdit; Codex and OpenCode use PreToolUse.
+ *   Codex passes the native apply_patch payload directly. OpenCode's plugin
+ *   adapts write/edit/apply_patch calls and blocks a FULL emission once so the
+ *   model sees the specs before retrying. Class-2 platforms use
+ *   `get_context.py --mode spec` pull mode instead.
+ * - Claude Code `statusLine` is intentionally not installed by default.
+ *   Users can add their own statusLine command in `.claude/settings.json`,
+ *   or opt in to the Trellis one via `trellis init --with-statusline`
+ *   (installed from `templates/claude/hooks/`, not from this table — no
+ *   other platform has a statusLine event).
+ * - ZCode (3.x) ships a workspace hook config at `.zcode/config.json` covering
+ *   SessionStart + UserPromptSubmit in the main session, plus PreToolUse for
+ *   `Agent|Task`. Live probing confirmed `hookSpecificOutput.updatedInput`
+ *   reaches the sub-agent prompt, so ZCode is class-1 and ships
+ *   `inject-subagent-context.py`.
+ */
+export const SHARED_HOOKS_BY_PLATFORM = {
+    claude: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+        "inject-spec-context.py",
+    ],
+    cursor: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-subagent-context.py",
+    ],
+    codex: [
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+        "inject-spec-context.py",
+    ],
+    opencode: ["inject-spec-context.py"],
+    gemini: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+    ],
+    qoder: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+    ],
+    copilot: ["inject-workflow-state.py"],
+    codebuddy: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+    ],
+    droid: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+    ],
+    kiro: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+    ],
+    trae: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+    ],
+    zcode: [
+        "session-start.py",
+        "inject-shell-session-context.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+    ],
+};
+/**
+ * Get all shared hook scripts. Content is platform-independent and can be
+ * written directly without placeholder resolution.
+ */
+export function getSharedHookScripts() {
+    const scripts = [];
+    const files = readdirSync(__dirname)
+        .filter((f) => f.endsWith(".py"))
+        .sort();
+    for (const file of files) {
+        scripts.push({ name: file, content: readTemplate(file) });
+    }
+    return scripts;
+}
+/**
+ * Get the shared hook scripts that a given platform actually registers.
+ * Drives `collectSharedHooks` so distribution never drifts from the
+ * per-platform capability declared above.
+ */
+export function getSharedHookScriptsForPlatform(platform) {
+    const allowed = new Set(SHARED_HOOKS_BY_PLATFORM[platform]);
+    return getSharedHookScripts().filter((h) => allowed.has(h.name));
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/shared-hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,wBAAwB;KACzB;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,4BAA4B;KAC7B;IACD,KAAK,EAAE;QACL,0BAA0B;QAC1B,4BAA4B;QAC5B,wBAAwB;KACzB;IACD,QAAQ,EAAE,CAAC,wBAAwB,CAAC;IACpC,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;KAC3B;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;KAC3B;IACD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE;QACJ,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE;QACJ,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;KAC3B;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,iCAAiC;QACjC,0BAA0B;QAC1B,4BAA4B;KAC7B;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,OAAO,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/templates/shared-hooks/inject-shell-session-context.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Pre-shell hook: bridge the host's session identity into task.py.
+
+No researched platform exports a session id into its shell tool's child
+process, but every hook-capable one puts that id on hook stdin. So the hook
+that fires just before a shell command writes a short-lived runtime ticket
+whenever the pending command calls `task.py start/current/finish`, and the
+task script consumes it when it has no native session environment.
+
+Registered on whichever pre-shell event the host provides — Cursor's
+`beforeShellExecution`, Claude-shaped `PreToolUse`, Gemini's `BeforeTool` —
+which is why the only thing here that knows about payload variation is
+`_pending_shell_command`.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shlex
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+# Hook hosts send UTF-8 JSON regardless of the process locale.
+_stdin_reconfigure = getattr(sys.stdin, "reconfigure", None)
+if callable(_stdin_reconfigure):
+    try:
+        _stdin_reconfigure(encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        pass
+
+
+DIR_WORKFLOW = ".trellis"
+DIR_RUNTIME = ".runtime"
+DIR_SHELL_TICKETS = "shell-tickets"
+SESSION_SUBCOMMANDS = {"start", "current", "finish"}
+TICKET_TTL_SECONDS = 30
+CONTEXT_IDENTITY_KEYS = (
+    "session_id",
+    "sessionId",
+    "sessionID",
+    "conversation_id",
+    "conversationId",
+    "conversationID",
+    "transcript_path",
+    "transcriptPath",
+    "transcript",
+)
+# Tool-call payloads nest the command one level down; same casing spread as
+# CONTEXT_IDENTITY_KEYS above.
+TOOL_INPUT_KEYS = ("tool_input", "toolInput")
+# Answering a shell-execution event with an explicit allow is what keeps
+# Cursor from re-prompting for a command Trellis itself asked for. Tool-call
+# hosts read a different response schema, so they get no answer at all rather
+# than a key they would have to ignore.
+SHELL_EVENT_RESPONSE = {"permission": "allow"}
+
+
+def _string_value(value: Any) -> str | None:
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    return None
+
+
+def _resolve_trellis_root(hook_input: dict[str, Any]) -> Path | None:
+    """Locate the project root, trying the payload cwd and then our own.
+
+    Hosts disagree about what `cwd` means. CodeBuddy IDE 4.10.4 sends `"/"` for
+    every PreToolUse event, so trusting the payload alone finds no `.trellis`
+    and the bridge silently does nothing — the hook is invoked, writes no
+    ticket, and `task.py start` degrades. Observed with a wildcard probe:
+
+        {"cwd": "/", "tool_name": "Bash", "tool_input": {"command": "ls …"}}
+
+    The hook's own cwd is reliable where the payload is not: hosts launch it
+    from the project root, which is why a relative `command` in settings.json
+    resolves at all. Try the payload first (it is right on hosts that set it,
+    and survives a host that runs hooks from elsewhere), then fall back.
+    """
+    candidates: list[Path] = []
+    payload_cwd = _string_value(hook_input.get("cwd"))
+    if payload_cwd:
+        candidates.append(Path(payload_cwd))
+    try:
+        candidates.append(Path(os.getcwd()))
+    except OSError:
+        pass
+
+    for candidate in candidates:
+        root = _find_trellis_root(candidate)
+        if root is not None:
+            return root
+    return None
+
+
+def _find_trellis_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while True:
+        if (current / DIR_WORKFLOW).is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def _runtime_ticket_dir(root: Path) -> Path:
+    return root / DIR_WORKFLOW / DIR_RUNTIME / DIR_SHELL_TICKETS
+
+
+def _pending_shell_command(hook_input: dict[str, Any]) -> tuple[str, dict[str, Any] | None]:
+    """Read the pending shell command out of either hook payload shape.
+
+    Returns the command plus the response envelope that shape expects:
+
+    - shell-execution event (Cursor `beforeShellExecution`) — the command sits
+      at the top level and the host wants a permission decision back;
+    - tool-call event (`PreToolUse`, `BeforeTool`) — the command sits under
+      `tool_input`, and the host reads a schema this hook has no opinion on.
+
+    An ordered fallback, not a platform switch: a third payload shape extends
+    the same function. Anything else yields ("", None) so main() no-ops.
+    """
+    command = _string_value(hook_input.get("command"))
+    if command:
+        return command, SHELL_EVENT_RESPONSE
+
+    for key in TOOL_INPUT_KEYS:
+        tool_input = hook_input.get(key)
+        if not isinstance(tool_input, dict):
+            continue
+        command = _string_value(tool_input.get("command"))
+        if command:
+            return command, None
+
+    return "", None
+
+
+def _host_platform_name() -> str | None:
+    """Name the host from the config directory this hook was installed into.
+
+    Every platform puts its hooks under its own dotted directory
+    (`.cursor/hooks/`, `.factory/hooks/`, …), so the deepest dotted path
+    segment identifies the host without a table of platform names here. It
+    matters because the context key must agree with the one the platform's
+    other hooks compute — a ticket keyed differently would write a session
+    file no later hook ever reads.
+    """
+    for part in reversed(Path(sys.argv[0]).parts):
+        if part.startswith(".") and part not in (".", "..") and len(part) > 1:
+            return part[1:]
+    return None
+
+
+def _load_active_task_resolver(root: Path):
+    scripts_dir = root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    from common.active_task import resolve_context_key  # type: ignore[import-not-found]
+
+    return resolve_context_key
+
+
+def _extract_task_subcommands(command: str) -> list[dict[str, str]]:
+    try:
+        tokens = shlex.split(command, posix=os.name != "nt")
+    except ValueError:
+        return []
+
+    subcommands: list[dict[str, str]] = []
+    for index, token in enumerate(tokens[:-1]):
+        if Path(token.strip("\"'")).name != "task.py":
+            continue
+        name = tokens[index + 1]
+        if name not in SESSION_SUBCOMMANDS:
+            continue
+        item = {"name": name}
+        if name == "start" and index + 2 < len(tokens):
+            item["task_ref"] = tokens[index + 2]
+        subcommands.append(item)
+    return subcommands
+
+
+def _cleanup_expired_tickets(ticket_dir: Path, now: float) -> None:
+    if not ticket_dir.is_dir():
+        return
+    for ticket_path in ticket_dir.glob("*.json"):
+        try:
+            data = json.loads(ticket_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        expires_at = data.get("expires_at_epoch")
+        if isinstance(expires_at, (int, float)) and expires_at < now:
+            try:
+                ticket_path.unlink()
+            except OSError:
+                pass
+
+
+def _has_context_identity(hook_input: dict[str, Any]) -> bool:
+    return any(_string_value(hook_input.get(key)) for key in CONTEXT_IDENTITY_KEYS)
+
+
+def _write_ticket(
+    root: Path,
+    hook_input: dict[str, Any],
+    context_key: str,
+    command: str,
+    platform_name: str | None,
+    subcommands: list[dict[str, str]],
+) -> None:
+    now = time.time()
+    ticket_dir = _runtime_ticket_dir(root)
+    ticket_dir.mkdir(parents=True, exist_ok=True)
+    _cleanup_expired_tickets(ticket_dir, now)
+
+    digest = hashlib.sha256(
+        f"{context_key}\0{command}\0{now}".encode("utf-8"),
+    ).hexdigest()[:16]
+    ticket_path = ticket_dir / f"{int(now * 1000)}-{digest}.json"
+
+    payload = {
+        # Debugging metadata. The consumer accepts a ticket on freshness, repo
+        # and subcommand — never on this field.
+        "platform": platform_name,
+        "context_key": context_key,
+        "conversation_id": _string_value(hook_input.get("conversation_id")),
+        "session_id": _string_value(hook_input.get("session_id")),
+        "generation_id": _string_value(hook_input.get("generation_id")),
+        # The resolved project root, not the payload's cwd. The consumer
+        # rejects a ticket whose cwd is outside the repo, and CodeBuddy IDE
+        # 4.10.4 reports "/" for every PreToolUse event — a ticket carrying
+        # that is written correctly and then discarded on arrival. Recording
+        # the root we actually resolved keeps the containment check meaningful
+        # without trusting a field the host may not populate.
+        "cwd": str(root),
+        # Kept separately so a wrong host cwd stays visible when debugging.
+        "host_cwd": _string_value(hook_input.get("cwd")),
+        "command": command,
+        "subcommands": subcommands,
+        "created_at_epoch": now,
+        "expires_at_epoch": now + TICKET_TTL_SECONDS,
+    }
+    ticket_path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def main() -> int:
+    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
+        return 0
+
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        hook_input = {}
+    if not isinstance(hook_input, dict):
+        hook_input = {}
+
+    command, response = _pending_shell_command(hook_input)
+    subcommands = _extract_task_subcommands(command)
+    if not subcommands:
+        return 0
+
+    root = _resolve_trellis_root(hook_input)
+    if root is None:
+        return 0
+
+    if not _has_context_identity(hook_input):
+        return 0
+
+    platform_name = _host_platform_name()
+    resolve_context_key = _load_active_task_resolver(root)
+    context_key = resolve_context_key(hook_input, platform=platform_name)
+    if not context_key:
+        return 0
+
+    try:
+        _write_ticket(root, hook_input, context_key, command, platform_name, subcommands)
+    except OSError:
+        return 0
+
+    if response is not None:
+        print(json.dumps(response, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())