cowork-flow 1.2.0 → 1.3.0

package/template/.cowork-flow/scripts/adapters/host/inject.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Host-neutral workflow-context injection entry.
+
+Every process-hook host funnels through this module so the workflow facts are
+rendered by a single Python source (workflow_state_hook.py + services.fact_view).
+The entry keeps only transport duties: event routing and byte forwarding.
+Per-host behavior differences (session aliases, preamble, digest policy
+wording, edit warnings, envelope pretty-printing) ride the host policy
+modules beside this file, selected by --host, exactly as frozen by
+spec/contracts/context-injection.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+# This file lives in <scripts>/adapters/host/; running it as a script puts
+# only its own directory on sys.path. The module root is needed both for the
+# root=None fallback (no project scripts dir exists) and so a stale project
+# copy never shadows the importing module.
+SCRIPTS_DIR = Path(__file__).resolve().parents[2]
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+HOST_ADAPTERS = {
+    "zcode": "zcode.plugin",
+    "claude-code": "claude-code.hooks",
+    "codex": "codex.spawn_agent",
+    "dsh": "dsh.preset",
+}
+
+NOT_INITIALIZED_BODY = (
+    "<workflow-state>\n"
+    "Status: not_initialized\n"
+    "Source: cowork-flow-plugin\n"
+    "⚠️ 项目未初始化 cowork-flow 工作流。\n"
+    "\n"
+    "请通过显式 init/sync 安装 cowork-flow 模板后再继续；"
+    "hook 不会在注入阶段创建或复制项目文件。\n"
+    "</workflow-state>"
+)
+
+
+def _configure_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            # newline="" keeps payload bytes identical across platforms —
+            # text-mode translation would turn the pretty JSON indentation
+            # into CRLF on Windows.
+            stream.reconfigure(encoding="utf-8", errors="replace", newline="")
+
+
+def _read_input() -> dict[str, Any]:
+    raw = sys.stdin.buffer.read()
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw.decode("utf-8-sig"))
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def detect_event_name(hook_input: dict[str, Any]) -> str:
+    name = hook_input.get("hook_event_name") or hook_input.get("hookEventName")
+    if isinstance(name, str) and name.strip():
+        return name.strip()
+    if os.environ.get("CURSOR_PLUGIN_ROOT"):
+        return "SessionStart"
+    return "UserPromptSubmit"
+
+
+def output_format() -> str:
+    if os.environ.get("CURSOR_PLUGIN_ROOT"):
+        return "cursor"
+    if os.environ.get("CLAUDE_PLUGIN_ROOT") and not os.environ.get("COPILOT_CLI"):
+        return "claude"
+    return "generic"
+
+
+def find_workflow_root(start: Path | None) -> Path | None:
+    if start is None:
+        return None
+    current = start.resolve()
+    while True:
+        if (current / ".cowork-flow").is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def resolve_root(hook_input: dict[str, Any]) -> Path | None:
+    candidates = [
+        hook_input.get("cwd"),
+        os.environ.get("ZCODE_PROJECT_DIR"),
+        os.environ.get("CLAUDE_PROJECT_DIR"),
+        os.getcwd(),
+    ]
+    for candidate in candidates:
+        if isinstance(candidate, str) and candidate.strip():
+            root = find_workflow_root(Path(candidate))
+            if root is not None:
+                return root
+    return None
+
+
+def _not_initialized_context(
+    hook_input: dict[str, Any],
+    event_name: str,
+    host: str,
+    policy: Any,
+) -> str:
+    from adapters.host.workflow_state_hook import (
+        _build_contract_digest,
+        _load_contract_registry,
+        contract_fingerprint,
+    )
+
+    env_dir = (
+        os.environ.get("ZCODE_PROJECT_DIR")
+        or os.environ.get("CLAUDE_PROJECT_DIR")
+        or hook_input.get("cwd")
+        or os.getcwd()
+    )
+    digest_root = Path(env_dir)
+    if event_name == "SessionStart":
+        prefix = _build_contract_digest(digest_root, policy, HOST_ADAPTERS[host])
+    else:
+        contracts, _warning = _load_contract_registry(digest_root)
+        prefix = (
+            f'<contract-fingerprint value="{contract_fingerprint(digest_root, contracts)}"/>'
+        )
+    return f"{prefix}\n\n{NOT_INITIALIZED_BODY}"
+
+
+def _emit(
+    context: str,
+    event_name: str,
+    output_format_name: str,
+    policy: Any,
+) -> None:
+    if output_format_name == "cursor":
+        payload: dict[str, Any] = {"additional_context": context}
+    else:
+        payload = {
+            "hookSpecificOutput": {
+                "hookEventName": event_name,
+                "additionalContext": context,
+            }
+        }
+    indent = 2 if policy.emit_indent else None
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=indent))
+
+
+def _handle_post_tool_use(
+    root: Path | None,
+    hook_input: dict[str, Any],
+    policy: Any,
+    output_format_name: str,
+) -> int:
+    if root is None:
+        return 0
+    if policy.post_tool_use is None:
+        return 0
+    context, exit_code = policy.post_tool_use(root, hook_input)
+    if context:
+        _emit(context, "PostToolUse", output_format_name, policy)
+    return exit_code
+
+
+def main(argv: list[str] | None = None) -> int:
+    _configure_stdio()
+    if (
+        os.environ.get("COWORK_FLOW_HOOKS") == "0"
+        or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1"
+    ):
+        return 0
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", required=True, choices=sorted(HOST_ADAPTERS))
+    args = parser.parse_args(argv)
+    host = args.host
+
+    from adapters.host.workflow_state_hook import (
+        build_hook_context,
+        resolve_policy,
+    )
+
+    policy = resolve_policy(host)
+
+    hook_input = _read_input()
+    if policy.session_alias is not None:
+        hook_input = policy.session_alias(hook_input)
+    event_name = detect_event_name(hook_input)
+    output_format_name = output_format()
+    root = resolve_root(hook_input)
+
+    if event_name == "PostToolUse":
+        return _handle_post_tool_use(root, hook_input, policy, output_format_name)
+
+    if root is None:
+        if policy.emit_not_initialized:
+            _emit(
+                _not_initialized_context(hook_input, event_name, host, policy),
+                event_name,
+                output_format_name,
+                policy,
+            )
+            return 0
+        # Hosts without the not-initialized payload exit silently outside a
+        # project.
+        return 0
+
+    scripts_dir = root / ".cowork-flow" / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    # zcode / claude-code signal session start by event name; codex (and the
+    # default policy) register UserPromptSubmit only, so their digest shape
+    # derives from the session state file probe (session_start=None).
+    if policy.session_start_event is None:
+        session_start = None
+    else:
+        session_start = event_name == policy.session_start_event
+
+    preamble = policy.preamble(root) if policy.preamble is not None else ()
+    context = build_hook_context(
+        root,
+        hook_input,
+        host=host,
+        adapter=HOST_ADAPTERS[host],
+        preamble=preamble,
+        session_start=session_start,
+        policy=policy,
+    )
+    _emit(context, event_name, output_format_name, policy)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.cowork-flow/scripts/adapters/host/workflow_state_hook.py

@@ -1,14 +1,23 @@
 #!/usr/bin/env python3
-"""Shared workflow-state protocol used by host hook adapters."""
+"""Shared workflow-state protocol used by host hook adapters.
+
+This module is host-neutral: it renders the workflow facts and consumes a
+HostPolicy object for the per-host deltas (digest wording, preamble,
+edit warnings, unbound-session fallback). Host behaviors live in the
+per-host policy modules beside this file (zcode_policy.py,
+claude_code_policy.py, codex_policy.py); hosts without a module (dsh) run
+on default_policy().
+"""
 
 from __future__ import annotations
 
 import hashlib
+import importlib
 import json
 import re
 import sys
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 
 TAG_RE = re.compile(
@@ -30,6 +39,18 @@ DEFAULT_CONTRACT_REGISTRY = {
                 "when checking subagent health",
             ],
         },
+        {
+            "id": "FACT_LAYER_ACCESS_V1",
+            "path": ".cowork-flow/spec/contracts/fact-layer-access.md",
+            "digest": [
+                "Task/scope/spec facts are read-only via MCP tools or CLI; writes only flow through CLI lifecycle gates.",
+                "Prefer MCP task_state/task_scope/task_specs for fact queries when available; CLI is the fallback.",
+            ],
+            "readWhen": [
+                "when querying task facts or file scope",
+                "when registering the fact layer for a new host or external client",
+            ],
+        },
     ]
 }
 
@@ -44,16 +65,96 @@ def find_repo_root(start: Path) -> Path | None:
         current = current.parent
 
 
-def codex_dispatch_mode(root: Path) -> str:
-    _load_common(root)
-    try:
-        from infra.config import get_codex_dispatch_mode
-    except Exception:
-        return "sub-agent"
+# Digest policy wording is a per-host contract fact (context-injection.md
+# transport table); hosts carry their line in their policy module, unknown
+# hosts fall back to the default line below.
+DEFAULT_DIGEST_POLICY = (
+    "policy: repeat this short digest every hook; "
+    "read full spec files only before listed actions."
+)
+
+
+class HostPolicy:
+    """Per-host deltas consumed by the neutral renderer.
+
+    Fields left at their defaults mean "no such behavior for this host" —
+    the renderer checks callables instead of branching on host names.
+    Plain class on purpose: this file is also loaded standalone by tests
+    under ad-hoc module names, where @dataclass processing crashes on the
+    unregistered module lookup.
+    """
+
+    __slots__ = (
+        "host",
+        "digest_policy",
+        "digest_warning_silent",
+        "session_start_event",
+        "session_alias",
+        "preamble",
+        "rebind_hints",
+        "essential_files_warning",
+        "fallback_for_unbound",
+        "post_tool_use",
+        "emit_indent",
+        "emit_not_initialized",
+    )
+
+    def __init__(
+        self,
+        host: str,
+        digest_policy: str = DEFAULT_DIGEST_POLICY,
+        digest_warning_silent: bool = False,
+        session_start_event: str | None = "SessionStart",
+        session_alias: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        preamble: Callable[[Path], tuple[str, ...]] | None = None,
+        rebind_hints: Callable[[Path], str] | None = None,
+        essential_files_warning: Callable[[Path], str] | None = None,
+        fallback_for_unbound: bool = False,
+        post_tool_use: Callable[[Path, dict[str, Any]], tuple[str, int]] | None = None,
+        emit_indent: bool = False,
+        emit_not_initialized: bool = False,
+    ) -> None:
+        self.host = host
+        self.digest_policy = digest_policy
+        self.digest_warning_silent = digest_warning_silent
+        self.session_start_event = session_start_event
+        self.session_alias = session_alias
+        self.preamble = preamble
+        self.rebind_hints = rebind_hints
+        self.essential_files_warning = essential_files_warning
+        self.fallback_for_unbound = fallback_for_unbound
+        self.post_tool_use = post_tool_use
+        self.emit_indent = emit_indent
+        self.emit_not_initialized = emit_not_initialized
+
+
+def default_policy(host: str = "generic") -> HostPolicy:
+    return HostPolicy(host=host)
+
+
+# Host → policy module dispatch. Data-driven: adding a host is one row plus
+# its policy module; the neutral renderer never branches on host names.
+_HOST_POLICY_MODULES = {
+    "zcode": "adapters.host.zcode_policy",
+    "claude-code": "adapters.host.claude_code_policy",
+    "codex": "adapters.host.codex_policy",
+}
+
+
+def resolve_policy(host: str, policy: HostPolicy | None = None) -> HostPolicy:
+    if policy is not None:
+        return policy
+    module_name = _HOST_POLICY_MODULES.get(host)
+    if not module_name:
+        return default_policy(host)
     try:
-        return get_codex_dispatch_mode(root)
+        module = importlib.import_module(module_name)
     except Exception:
-        return "sub-agent"
+        # A broken host policy module degrades to the neutral default
+        # instead of killing the injection.
+        return default_policy(host)
+    policy = module.POLICY
+    return policy if isinstance(policy, HostPolicy) else default_policy(host)
 
 
 def build_hook_context(
@@ -64,7 +165,9 @@ def build_hook_context(
     adapter: str,
     preamble: tuple[str, ...],
     session_start: bool | None = None,
+    policy: HostPolicy | None = None,
 ) -> str:
+    policy = resolve_policy(host, policy)
     breadcrumbs = _load_breadcrumbs(root)
     runtime_context, runtime_context_id = _resolve_runtime_context(
         root,
@@ -95,12 +198,25 @@ def build_hook_context(
             ),
         ]
     else:
-        task_path, status, source = _get_active_task(root, hook_input)
+        task_path, status, source = _get_active_task_with_fallback(
+            root,
+            hook_input,
+            policy.fallback_for_unbound,
+        )
 
-    body = (
-        breadcrumbs.get(status)
-        or "Run ./.cowork-flow/run task next --json for the current workflow route."
-    )
+    if status == "stale" and task_path:
+        # Unified missing-task semantics (previously zcode JS-only): a bound
+        # task whose directory or task.json vanished renders the no_task
+        # family message instead of a generic fallback breadcrumb.
+        status = "no_task"
+        body = MISSING_TASK_BODY.format(task_path=task_path)
+    else:
+        body = (
+            breadcrumbs.get(status)
+            or "Run ./.cowork-flow/run task next --json for the current workflow route."
+        )
+    if policy.rebind_hints is not None:
+        body += policy.rebind_hints(root)
     if extra_lines:
         body = "\n".join([body, *extra_lines])
     if session_start is None:
@@ -109,7 +225,7 @@ def build_hook_context(
         # exists (start), so their absence keeps every injection full.
         session_start = not _session_has_started(root, hook_input)
     if session_start:
-        digest_block = _build_contract_digest(root, host, adapter)
+        digest_block = _build_contract_digest(root, policy, adapter)
     else:
         contracts, _warning = _load_contract_registry(root)
         digest_block = (
@@ -126,7 +242,13 @@ def build_hook_context(
         f"<workflow-state{_workflow_state_attrs(task_path, status, source)}>"
         f"\n{body}\n</workflow-state>"
     )
-    return "\n\n".join(blocks)
+    context = "\n\n".join(blocks)
+    if policy.essential_files_warning is not None:
+        # Appended after the whole context so a broken install is visible
+        # without a second hook pass (host policy decides whether the check
+        # exists at all).
+        context += policy.essential_files_warning(root)
+    return context
 
 
 def _session_has_started(root: Path, hook_input: dict[str, Any]) -> bool:
@@ -289,25 +411,32 @@ def _stage_contract_block(
         return None
 
 
-def spec_edit_warning(root: Path, hook_input: dict[str, Any]) -> str:
+def spec_edit_warning(
+    root: Path,
+    hook_input: dict[str, Any],
+    policy: HostPolicy,
+) -> str:
     """Editor-phase spec-check single-line warning (PostToolUse short path).
 
-    Silence rules match the zcode JS mirror (editScopeWarning family): only
-    an active in_progress/review main-session task gets advisories —
-    no_task, planning, completed, and delegated sessions stay silent. Empty
-    string means silent. Never raises — the editor path must not break
-    edits.
+    Delegated subagents are the primary coders, so spec violations must
+    reach them too: only an active in_progress/review task is required —
+    session scope is not consulted here (scope warnings stay main-only in
+    the zcode policy's edit_scope_warning). Hosts with
+    fallback_for_unbound (zcode) follow the newest main session for their
+    never-bound hook sessions; strict-identity hosts (claude-code/codex)
+    require the calling session's own binding. no_task, planning, and
+    completed stay silent. Empty string means silent. Never raises — the
+    editor path must not break edits.
     """
     try:
-        task_path, status, _source = _get_active_task(root, hook_input)
+        task_path, status, _source = _get_active_task_with_fallback(
+            root, hook_input, policy.fallback_for_unbound
+        )
     except Exception:
         return ""
     if not task_path or status not in STAGE_CONTRACT_STATES:
         return ""
-    tool_name = hook_input.get("tool_name")
     tool_input = hook_input.get("tool_input")
-    if tool_name not in {"Edit", "Write", "MultiEdit"}:
-        return ""
     file_path = (
         tool_input.get("file_path") if isinstance(tool_input, dict) else None
     )
@@ -321,6 +450,21 @@ def spec_edit_warning(root: Path, hook_input: dict[str, Any]) -> str:
         return ""
 
 
+def spec_only_post_tool_use(
+    root: Path,
+    hook_input: dict[str, Any],
+    policy: HostPolicy,
+) -> tuple[str, int]:
+    """claude-code / codex PostToolUse transport: spec-check advisory on
+    stderr only (exit 2 surfaces it to the model); the edit itself has
+    already happened. No additionalContext payload."""
+    warning = spec_edit_warning(root, hook_input, policy)
+    if warning:
+        print(warning, file=sys.stderr)
+        return "", 2
+    return "", 0
+
+
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
     path = (
         root
@@ -396,20 +540,17 @@ def _load_contract_registry(
 
 def _build_contract_digest(
     root: Path,
-    host: str,
+    policy: HostPolicy,
     adapter: str,
 ) -> str:
     contracts, warning = _load_contract_registry(root)
     fingerprint = contract_fingerprint(root, contracts)
     lines = [
-        f'<cowork-runtime host="{host}" adapter="{adapter}">',
+        f'<cowork-runtime host="{policy.host}" adapter="{adapter}">',
         f'<contract-digest fingerprint="{fingerprint}">',
-        (
-            "policy: repeat this short digest every hook; "
-            "read full spec files only before listed actions."
-        ),
+        policy.digest_policy,
     ]
-    if warning:
+    if warning and not policy.digest_warning_silent:
         lines.append(f"warning: {warning}")
     for contract in contracts:
         contract_id = contract.get("id")
@@ -452,6 +593,105 @@ def _get_active_task(
     return active.task_path, status.strip(), active.source
 
 
+MISSING_TASK_BODY = (
+    "Session 指向的任务目录不存在（{task_path}）。\n"
+    "当前项目无有效任务。请运行 ./.cowork-flow/run task next --run "
+    '--title "<title>" --slug <task-name> --assignee <name> 创建新任务。'
+)
+
+
+def _get_active_task_with_fallback(
+    root: Path,
+    hook_input: dict[str, Any],
+    fallback_for_unbound: bool,
+) -> tuple[str | None, str, str]:
+    """zcode parity: a hook session that carries no binding follows the
+    newest valid main session's binding. Two sources qualify: no session
+    identity at all (missing-context), and a session id that resolves but
+    was never bound (empty-session) — the zcode hook always carries the
+    conversation's own session id, while task activation happens in the
+    Bash CLI under a separate explicit identity, so the hook session file
+    never exists. Gated by the host policy's fallback_for_unbound flag;
+    display/warning-only — the CLI lifecycle commands keep their strict
+    identity semantics. Multi-window setups may cross-read another window's
+    binding; accepted for advisory output."""
+    task_path, status, source = _get_active_task(root, hook_input)
+    if (
+        not fallback_for_unbound
+        or task_path
+        or source not in {"missing-context", "empty-session"}
+    ):
+        return task_path, status, source
+    fallback = _newest_session_task(root)
+    if fallback is None:
+        return task_path, status, source
+    task_json = root / fallback / "task.json"
+    try:
+        data = json.loads(task_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return fallback, "stale", "session-fallback"
+    status = data.get("status")
+    if not isinstance(status, str) or not status.strip():
+        status = "unknown"
+    return fallback, status.strip(), "session-fallback"
+
+
+def _newest_session_task(root: Path) -> str | None:
+    try:
+        from runtime.session_state import sessions_dir
+    except Exception:
+        return None
+    sessions = sessions_dir(root)
+    if not sessions.is_dir():
+        return None
+    entries: list[tuple[str, str]] = []
+    try:
+        paths = sorted(sessions.glob("*.json"))
+    except OSError:
+        return None
+    for path in paths:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(data, dict):
+            continue
+        task_path = data.get("active_task_path")
+        if not isinstance(task_path, str) or not task_path.strip():
+            continue
+        if data.get("scope") == "subagent":
+            continue
+        entries.append(
+            (str(data.get("last_seen_at") or ""), task_path.strip())
+        )
+    entries.sort(reverse=True)
+    for _seen_at, task_path in entries:
+        task_dir = root / task_path
+        if task_dir.is_dir() and (task_dir / "task.json").is_file():
+            return task_path
+    return None
+
+
+def _session_scope(root: Path, hook_input: dict[str, Any]) -> str:
+    try:
+        from runtime.session_state import resolve_context_key, sessions_dir
+    except Exception:
+        return ""
+    context_key = resolve_context_key(hook_input)
+    if not context_key:
+        return ""
+    try:
+        data = json.loads(
+            (sessions_dir(root) / f"{context_key}.json").read_text(
+                encoding="utf-8"
+            )
+        )
+    except (OSError, json.JSONDecodeError, ValueError):
+        return ""
+    scope = data.get("scope")
+    return scope if isinstance(scope, str) else ""
+
+
 def _resolve_runtime_context(
     root: Path,
     hook_input: dict[str, Any],
@@ -480,7 +720,12 @@ def _resolve_runtime_context(
         runtime_context_id,
         values=hook_input,
     )
-    return bound or context, runtime_context_id
+    result = bound or context
+    if not result.get("runtime_context_id"):
+        # Legacy context files predate the id field; the detected id is the
+        # identity that opened this context, so display it.
+        result = {**result, "runtime_context_id": runtime_context_id}
+    return result, runtime_context_id
 
 
 def _subagent_runtime_lines(context: dict[str, Any]) -> list[str]: