cowork-flow 1.2.0 → 1.4.0

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 = (
@@ -123,10 +239,16 @@ def build_hook_context(
     if contract_block:
         blocks.append(contract_block)
     blocks.append(
-        f"<workflow-state{_workflow_state_attrs(task_path, status, source)}>"
+        f"<workflow-state{_workflow_state_attrs(task_path, status, source, session=_resolve_session_identity(root, hook_input))}>"
         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:
@@ -157,14 +279,38 @@ def _xml_attr(value: Any) -> str:
     return xml_attr(value)
 
 
+def _resolve_session_identity(
+    root: Path, hook_input: dict[str, Any]
+) -> str | None:
+    """The caller's resolved context key for the session attribute
+    (context-injection.md, stage 1). None when no identity is resolvable —
+    the attribute is omitted rather than guessed."""
+    _load_common(root)
+    try:
+        from runtime.session_state import resolve_context_key
+    except Exception:
+        return None
+    try:
+        return resolve_context_key(hook_input)
+    except Exception:
+        return None
+
+
 def _workflow_state_attrs(
-    task_path: str | None, status: str, source: str
+    task_path: str | None,
+    status: str,
+    source: str,
+    session: str | None = None,
 ) -> str:
     """Structured fact header (context-injection.md, stage 1): the machine
-    picks task/status/source off the attributes; humans read the body."""
+    picks task/status/source/session off the attributes; humans read the
+    body. session is appended last and only when a session identity was
+    resolvable from the hook input or environment."""
     attrs = [f'status="{_xml_attr(status)}"', f'source="{_xml_attr(source)}"']
     if task_path:
         attrs.insert(0, f'task="{_xml_attr(task_path)}"')
+    if session:
+        attrs.append(f'session="{_xml_attr(session)}"')
     return "".join(f" {attr}" for attr in attrs)
 
 
@@ -289,25 +435,33 @@ 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 another main session's binding for
+    their never-bound hook sessions only while exactly one main-session
+    binding exists (see _get_active_task_with_fallback); 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 +475,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 +565,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 +618,112 @@ 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 another
+    main session's binding — but only when exactly one main-session binding
+    exists. Two sources qualify for the fallback: 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 may not exist yet.
+    Gated by the host policy's fallback_for_unbound flag; display/warning-only
+    — the CLI lifecycle commands keep their strict identity semantics. With
+    two or more main-session bindings the newest one belongs to some other
+    window, so the fallback refuses and the caller renders no_task plus the
+    rebind hints instead."""
+    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
+    candidates = _main_session_task_candidates(root)
+    if len(candidates) != 1:
+        return task_path, status, source
+    fallback = candidates[0]
+    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 _main_session_task_candidates(root: Path) -> list[str]:
+    """All main-scope session bindings whose task directory is still valid,
+    newest first. Subagent scopes never qualify: delegated sessions follow
+    their runtime context, not another session's file."""
+    try:
+        from runtime.session_state import sessions_dir
+    except Exception:
+        return []
+    sessions = sessions_dir(root)
+    if not sessions.is_dir():
+        return []
+    entries: list[tuple[str, str]] = []
+    try:
+        paths = sorted(sessions.glob("*.json"))
+    except OSError:
+        return []
+    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)
+    candidates: list[str] = []
+    for _seen_at, task_path in entries:
+        task_dir = root / task_path
+        if task_dir.is_dir() and (task_dir / "task.json").is_file():
+            candidates.append(task_path)
+    return candidates
+
+
+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 +752,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]: