@blxzer/pactile 0.5.0

package/dist/templates/shared-hooks/event-bridge.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Thin Cursor Event Bridge hook.
+
+Records one standard hook event. Unsubscribed modules must never fail the hook.
+Does not write Kernel store primitives; optional Kernel patch is best-effort.
+
+Context events (sessionStart / stop / beforeSubmitPrompt) must not emit
+preToolUse ``permission`` — Cursor only honors fields the event supports, and
+a leading ``{"permission":"allow"}`` on sessionStart can discard the following
+session-start additional_context payload.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+DIR_WORKFLOW = ".pactile"
+# Host context-injection events. ``permission`` belongs to preToolUse /
+# beforeShellExecution, not these.
+_CONTEXT_EVENTS = frozenset(
+    {"sessionstart", "stop", "beforesubmitprompt"},
+)
+
+
+def _event_name(argv: list[str], hook_input: dict) -> str:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--event", default="")
+    args, _unknown = parser.parse_known_args(argv)
+    if args.event.strip():
+        return args.event.strip()
+    for key in ("hook_event_name", "event", "eventName"):
+        value = hook_input.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return "sessionStart"
+
+
+def _safe_payload() -> dict:
+    raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+    if not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def find_repo_root(start_path: str) -> str | None:
+    current = Path(start_path).resolve()
+    while current != current.parent:
+        if (current / DIR_WORKFLOW).is_dir():
+            return str(current)
+        if (current / ".git").exists():
+            return str(current)
+        current = current.parent
+    return None
+
+
+def _load_extras(hook_input: dict) -> dict:
+    try:
+        repo = find_repo_root(os.getcwd())
+        if not repo:
+            repo = find_repo_root(str(Path(__file__).resolve().parents[2]))
+        if not repo:
+            return {}
+        scripts_dir = Path(repo) / DIR_WORKFLOW / "scripts"
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+        from common.ondemand_topology import extras_from_task_dir  # type: ignore[import-not-found]
+
+        selected = resolve_selected_task(Path(repo), hook_input, platform="cursor")
+        path = getattr(selected, "task_path", None)
+        if not path:
+            return {}
+        candidate = Path(path)
+        task_dir = candidate if candidate.is_absolute() else Path(repo) / candidate
+        extras = extras_from_task_dir(task_dir)
+        return extras if isinstance(extras, dict) else {}
+    except Exception:
+        return {}
+
+
+def _print_host_result(event: str) -> None:
+    if (event or "").strip().lower() in _CONTEXT_EVENTS:
+        print("{}", flush=True)
+        return
+    print(json.dumps({"permission": "allow"}), flush=True)
+
+
+def main() -> int:
+    # Fail-closed for the Agent session: never break the hook.
+    event = "sessionStart"
+    try:
+        hook_input = _safe_payload()
+        event = _event_name(sys.argv[1:], hook_input)
+        sys.path.insert(0, str(Path(__file__).resolve().parents[2] / ".pactile" / "scripts"))
+        try:
+            from common.adapter_middleware import (  # type: ignore[import-not-found]
+                dispatch_hook_event,
+                event_bridge_for_dispatch,
+            )
+        except Exception:
+            _print_host_result(event)
+            return 0
+        extras = _load_extras(hook_input)
+        bridge = event_bridge_for_dispatch(extras)
+        _ = dispatch_hook_event(bridge, event, source="cursor-hooks")
+    except Exception:
+        pass
+    _print_host_result(event)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,50 @@
+/**
+ * Shared hook templates — platform-independent Python hook scripts.
+ *
+ * These scripts read only from .pactile/ 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" | "event-bridge.py" | "inject-shell-session-context.py" | "rename-session-for-task.py" | "inject-retrieval-plan.py" | "inject-workflow-state.py" | "inject-subagent-context.py" | "research-end-retrieval-pack.py" | "spec-write-audit.py";
+export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qoder" | "copilot" | "codebuddy" | "droid" | "kiro";
+/**
+ * Which shared hooks each platform actually invokes. Single source of truth
+ * for shared-hook distribution — both `writeSharedHooks` (runtime install)
+ * and `collectSharedHooks` (`pactile update` diff) read from this table.
+ *
+ * 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` — class-1 (push-based) platforms only.
+ *   Class-2 (pull-based) platforms (codex, copilot, gemini, qoder) can't
+ *   have hooks mutate sub-agent prompts — their sub-agents load context
+ *   via a prelude instead.
+ * - Kiro supports only `agentSpawn` (no SessionStart / UserPromptSubmit
+ *   event), so it takes just `inject-subagent-context.py`.
+ * - Claude Code `statusLine` is intentionally not installed by default.
+ *   Users can add their own statusLine command in `.claude/settings.json`
+ *   without Pactile owning a generated hook file.
+ */
+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 both `writeSharedHooks` and `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,iBAAiB,GACjB,iCAAiC,GACjC,4BAA4B,GAC5B,0BAA0B,GAC1B,0BAA0B,GAC1B,4BAA4B,GAC5B,gCAAgC,GAChC,qBAAqB,CAAC;AAE1B,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CAmC1B,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,96 @@
+/**
+ * Shared hook templates — platform-independent Python hook scripts.
+ *
+ * These scripts read only from .pactile/ 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 — both `writeSharedHooks` (runtime install)
+ * and `collectSharedHooks` (`pactile update` diff) read from this table.
+ *
+ * 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` — class-1 (push-based) platforms only.
+ *   Class-2 (pull-based) platforms (codex, copilot, gemini, qoder) can't
+ *   have hooks mutate sub-agent prompts — their sub-agents load context
+ *   via a prelude instead.
+ * - Kiro supports only `agentSpawn` (no SessionStart / UserPromptSubmit
+ *   event), so it takes just `inject-subagent-context.py`.
+ * - Claude Code `statusLine` is intentionally not installed by default.
+ *   Users can add their own statusLine command in `.claude/settings.json`
+ *   without Pactile owning a generated hook file.
+ */
+export const SHARED_HOOKS_BY_PLATFORM = {
+    claude: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+        "research-end-retrieval-pack.py",
+    ],
+    cursor: [
+        "session-start.py",
+        "event-bridge.py",
+        "inject-shell-session-context.py",
+        "rename-session-for-task.py",
+        "inject-retrieval-plan.py",
+        "inject-subagent-context.py",
+        "research-end-retrieval-pack.py",
+        "spec-write-audit.py",
+    ],
+    codex: ["inject-workflow-state.py"],
+    gemini: ["session-start.py", "inject-workflow-state.py"],
+    qoder: ["session-start.py", "inject-workflow-state.py"],
+    copilot: ["inject-workflow-state.py"],
+    codebuddy: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+        "research-end-retrieval-pack.py",
+    ],
+    droid: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+        "research-end-retrieval-pack.py",
+    ],
+    kiro: ["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 both `writeSharedHooks` and `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;AA+BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iBAAiB;QACjB,iCAAiC;QACjC,4BAA4B;QAC5B,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;QAChC,qBAAqB;KACtB;IACD,KAAK,EAAE,CAAC,0BAA0B,CAAC;IACnC,MAAM,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACxD,KAAK,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACvD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;QAC5B,gCAAgC;KACjC;IACD,IAAI,EAAE,CAAC,4BAA4B,CAAC;CACrC,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-retrieval-plan.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""Cursor beforeSubmitPrompt: quality-layer telemetry-only retrieval routing.
+
+Three-layer retrieval ABI (frozen; do not merge back into workflow.md):
+
+| Layer    | Owner                 | This hook                                      |
+| -------- | --------------------- | ---------------------------------------------- |
+| Intent   | context-progressive   | logs intent ids; does not own the four intents |
+| Provider | Middleware            | does not take smart-search as Kernel         |
+| Quality  | retrieval-extended    | subscriber: local telemetry only               |
+
+DEGRADED MODE (2026-06-24): beforeSubmitPrompt ``additional_context`` does
+not reach the model in current Cursor versions (L1: event often not fired;
+L2: additional_context not delivered). This hook is telemetry-only: it logs
+routing decisions to ``.pactile/.runtime/retrieval-plan-events.log`` and MUST
+NOT inject plan blocks, MUST NOT print ``additional_context`` to stdout, and
+MUST NOT claim the plan was delivered into the Prompt.
+
+Silent exit 0 (no stdout) when:
+  - PACTILE_HOOKS=0 / not a Pactile repo
+  - prompt is meta-only (continue, slash commands, etc.)
+  - gate says retrieval plan is not needed
+  - quality layer has nothing to score (still must not fail)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+if sys.platform.startswith("win"):
+    import io as _io
+
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(
+                    sys,
+                    _stream_name,
+                    _io.TextIOWrapper(
+                        _stream.detach(), encoding="utf-8", errors="replace"
+                    ),
+                )
+            except Exception:
+                pass
+
+DIR_WORKFLOW = ".pactile"
+# Markers of the plan block this hook deliberately does NOT emit.
+PLAN_MARKER_ZH = "## 代码库检索计划"
+PLAN_MARKER_EN = "## Codebase retrieval plan"
+TELEMETRY_LOG = ".runtime/retrieval-plan-events.log"
+
+ABI_INTENT_OWNER = "context-progressive"
+ABI_PROVIDER_OWNER = "middleware"
+ABI_QUALITY_OWNER = "retrieval-extended"
+ABI_LAYER = "quality"
+
+
+def _find_pactile_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while True:
+        if (current / DIR_WORKFLOW / "scripts").is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def _detect_platform(input_data: dict[str, Any]) -> str | None:
+    if isinstance(input_data.get("cursor_version"), str):
+        return "cursor"
+    if os.environ.get("CURSOR_PROJECT_DIR"):
+        return "cursor"
+    script_parts = set(Path(sys.argv[0]).parts)
+    if ".cursor" in script_parts:
+        return "cursor"
+    return None
+
+
+def _retrieval_extended_active(root: Path, input_data: dict[str, Any]) -> bool:
+    """Unactivated retrieval-extended → no telemetry and no plan injection."""
+    scripts_dir = root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+        from common.ondemand_topology import is_ondemand_module_active  # type: ignore[import-not-found]
+    except Exception:
+        return False
+    try:
+        selected = resolve_selected_task(
+            root,
+            input_data,
+            platform=_detect_platform(input_data),
+        )
+        task_path = selected.task_path if selected else None
+    except Exception:
+        task_path = None
+    if not task_path:
+        return False
+    candidate = Path(task_path)
+    task_dir = candidate if candidate.is_absolute() else root / task_path
+    return bool(is_ondemand_module_active(task_dir, "retrieval-extended"))
+
+
+def _write_telemetry_log(
+    root: Path,
+    query_preview: str,
+    plan_fingerprint: str,
+    intents: list[str],
+    minimum_assurance: str,
+) -> None:
+    """Write local telemetry / assurance. Never claims model delivery."""
+    log_path = root / DIR_WORKFLOW / TELEMETRY_LOG
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    event = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "event": "beforeSubmitPrompt",
+        "query_preview": query_preview[:120],
+        "planFingerprint": plan_fingerprint,
+        "intents": intents,
+        "minimumAssurance": minimum_assurance,
+        "action": "telemetry-only",
+        "assurance": "local-telemetry-only",
+        "promptInjected": False,
+        "additionalContextDelivered": False,
+        "abiLayer": ABI_LAYER,
+        "abiOwner": ABI_QUALITY_OWNER,
+        "abiIntentOwner": ABI_INTENT_OWNER,
+        "abiProviderOwner": ABI_PROVIDER_OWNER,
+        "note": (
+            "additional_context channel unreliable; promptInjected=false; "
+            "do not treat local telemetry as model delivery"
+        ),
+    }
+
+    try:
+        with log_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def main() -> int:
+    if os.environ.get("PACTILE_HOOKS") == "0" or os.environ.get(
+        "PACTILE_DISABLE_HOOKS"
+    ) == "1":
+        return 0
+
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        data = {}
+
+    if not isinstance(data, dict):
+        data = {}
+
+    cwd_str = data.get("cwd") or os.getcwd()
+    root = _find_pactile_root(Path(str(cwd_str)))
+    if root is None:
+        return 0
+
+    scripts_dir = root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        if not _retrieval_extended_active(root, data):
+            return 0
+    except Exception:
+        return 0
+
+    try:
+        from common.codebase_retrieval_router import (  # type: ignore[import-not-found]
+            route_codebase_retrieval,
+        )
+        from common.retrieval_plan_gate import (  # type: ignore[import-not-found]
+            extract_user_prompt,
+            should_inject_retrieval_plan,
+        )
+    except Exception:
+        return 0
+
+    query = extract_user_prompt(data)
+    if not should_inject_retrieval_plan(query):
+        return 0
+
+    plan = route_codebase_retrieval(query)
+    intent_ids = [str(intent) for intent in plan.get("intents", [])]
+    _write_telemetry_log(
+        root,
+        query,
+        str(plan.get("fingerprint", "")),
+        intent_ids,
+        str(plan.get("minimumAssurance", "best-effort")),
+    )
+
+    # Channel unavailable: local telemetry only. No stdout. Never claim
+    # additional_context reached the model. Do not emit PLAN_MARKER_*.
+    _ = _detect_platform(data)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Cursor beforeShellExecution hook: bridge conversation identity to task.py.
+
+Cursor's shell command environment does not inherit SessionStart data. This
+hook writes a short-lived runtime ticket before Cursor runs a shell command
+that calls `task.py select/selected/exit`. The task script then consumes the
+ticket only when it has no native session environment.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shlex
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+DIR_WORKFLOW = ".pactile"
+DIR_RUNTIME = ".runtime"
+DIR_CURSOR_SHELL = "cursor-shell"
+SESSION_SUBCOMMANDS = {"select", "selected", "exit"}
+TICKET_TTL_SECONDS = 30
+CONTEXT_IDENTITY_KEYS = (
+    "session_id",
+    "sessionId",
+    "sessionID",
+    "conversation_id",
+    "conversationId",
+    "conversationID",
+    "transcript_path",
+    "transcriptPath",
+    "transcript",
+)
+
+
+def _string_value(value: Any) -> str | None:
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    return None
+
+
+def _find_pactile_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_CURSOR_SHELL
+
+
+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 == "select" 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,
+    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)
+
+    command = _string_value(hook_input.get("command")) or ""
+    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 = {
+        "platform": "cursor",
+        "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")),
+        "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("PACTILE_HOOKS") == "0" or os.environ.get("PACTILE_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 = _string_value(hook_input.get("command")) or ""
+    subcommands = _extract_task_subcommands(command)
+    if not subcommands:
+        return 0
+
+    cwd = Path(_string_value(hook_input.get("cwd")) or os.getcwd())
+    root = _find_pactile_root(cwd)
+    if root is None:
+        return 0
+
+    if not _has_context_identity(hook_input):
+        return 0
+
+    resolve_context_key = _load_active_task_resolver(root)
+    context_key = resolve_context_key(hook_input, platform="cursor")
+    if not context_key:
+        return 0
+
+    try:
+        _write_ticket(root, hook_input, context_key, subcommands)
+    except OSError:
+        return 0
+
+    print(json.dumps({"permission": "allow"}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())