cowork-flow 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.4.0 - 2026-09-14
+
+### Hook 会话身份绑定（fix(runtime)）
+
+实弹暴露的多窗口交叉读取问题：zcode hook 会话携带对话自身的 session id，而任务激活发生在 Bash CLI 的显式身份下，导致未绑定的 hook 会话回退到 newest-session 时可能**读到另一个窗口的任务**。本版把绑定与回退语义一起收紧：
+
+- **激活即认领**：PostToolUse 在激活类命令（`task start` / `task next <dir> --run` / `resume <dir>`）之后，把 hook 会话自己的 `zcode_<sessionId>` 绑定认领下来（`session_state.claim_active_task`）；查询类命令与不可信身份（process-fallback/缺失）永不认领。
+- **回退语义收紧**：`fallback_for_unbound` 仅在**恰好存在一个** main-session 绑定时跟随最新的那个；存在多个绑定时，未绑定 hook 会话渲染 no_task + rebind 提示，绝不交叉读取其他窗口。
+- **会话身份显式化**：workflow-state 头部新增 `session=<contextKey>` 属性，模型可将其作为 `COWORK_FLOW_CONTEXT_ID` 传给后续 CLI 调用，打通 hook 会话与 CLI 身份。
+- **MCP 拒绝隐式冒认**：`task_state` / `task_scope` / `task_list` 在不可信身份下拒绝隐式解析（`identity-untrusted`），不再冒认 process-fallback 任务；CLI `FALLBACK_BINDING_BLOCKER` 语义不变（回归护栏锁定）。
+- 契约文档 context-injection.md 同步记录 session 属性与回退语义；新增 pytest 396 行覆盖（active_task_runtime / inject_entry / mcp_state_server / workflow_state_hook）。
+
 ## 1.3.0 - 2026-09-09
 
 ### 跨宿主适配通用化（注入单源化 + MCP 重定位）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.cowork-flow/.version

@@ -1 +1 @@
-1.3.0
+1.4.0

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

@@ -239,7 +239,7 @@ 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>"
     )
     context = "\n\n".join(blocks)
@@ -279,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)
 
 
@@ -422,11 +446,12 @@ def spec_edit_warning(
     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.
+    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_with_fallback(
@@ -605,16 +630,18 @@ def _get_active_task_with_fallback(
     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."""
+    """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
@@ -622,9 +649,10 @@ def _get_active_task_with_fallback(
         or source not in {"missing-context", "empty-session"}
     ):
         return task_path, status, source
-    fallback = _newest_session_task(root)
-    if fallback is None:
+    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"))
@@ -636,19 +664,22 @@ def _get_active_task_with_fallback(
     return fallback, status.strip(), "session-fallback"
 
 
-def _newest_session_task(root: Path) -> str | None:
+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 None
+        return []
     sessions = sessions_dir(root)
     if not sessions.is_dir():
-        return None
+        return []
     entries: list[tuple[str, str]] = []
     try:
         paths = sorted(sessions.glob("*.json"))
     except OSError:
-        return None
+        return []
     for path in paths:
         try:
             data = json.loads(path.read_text(encoding="utf-8"))
@@ -665,11 +696,12 @@ def _newest_session_task(root: Path) -> str | None:
             (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():
-            return task_path
-    return None
+            candidates.append(task_path)
+    return candidates
 
 
 def _session_scope(root: Path, hook_input: dict[str, Any]) -> str:

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

@@ -55,6 +55,60 @@ def is_lifecycle_bash(hook_input: dict[str, Any]) -> bool:
     )
 
 
+# Activation intent inside a lifecycle Bash command: `task next <dir> --run`,
+# `task start <dir>`, `resume <dir>` (the run prefix is optional). Query
+# forms (`task next --json`, `task next --run` without a dir) match nothing
+# claimable — the captured token must be a task dir whose task.json exists.
+ACTIVATION_COMMAND_RE = re.compile(
+    r"\btask\s+next\s+(?P<next>\S+)\s+--run\b"
+    r"|\btask\s+start\s+(?P<start>\S+?)(?=\s|$)"
+    r"|(?<![\w./-])resume\s+(?P<resume>\S+?)(?=\s|$)"
+)
+
+
+def _resolvable_task_path(root: Path, token: str) -> str | None:
+    candidates = [token]
+    if not token.startswith(".cowork-flow/"):
+        candidates.append(f".cowork-flow/tasks/{token}")
+    for candidate in candidates:
+        normalized = candidate.replace("\\", "/").strip("/")
+        if (root / normalized / "task.json").is_file():
+            return normalized
+    return None
+
+
+def claim_after_lifecycle_bash(root: Path, hook_input: dict[str, Any]) -> None:
+    """Bind the activated task to this hook session's own identity.
+
+    The lifecycle Bash CLI resolves a process-fallback identity, so the
+    binding it writes is shared across windows; PostToolUse re-binds with the
+    hook input's session id via session_state.claim_active_task (explicit /
+    host_session provenance only). Commands without an activation intent or
+    with an unresolvable task dir claim nothing, and claim failure stays
+    silent — the refresh path below still renders the state."""
+    tool_input = hook_input.get("tool_input")
+    command = (
+        tool_input.get("command") if isinstance(tool_input, dict) else None
+    )
+    if not isinstance(command, str):
+        return
+    match = ACTIVATION_COMMAND_RE.search(command.replace("\\", "/"))
+    if match is None:
+        return
+    token = next(value for value in match.groupdict().values() if value)
+    if token.startswith("-"):
+        return
+    task_path = _resolvable_task_path(root, token)
+    if task_path is None:
+        return
+    try:
+        from runtime.session_state import claim_active_task
+
+        claim_active_task(root, task_path, hook_input)
+    except Exception:
+        pass
+
+
 def zcode_session_alias(data: dict[str, Any]) -> dict[str, Any]:
     # Ported from the zcode hook's resolveSessionKey candidate order
     # (env wins inside session_state; input aliases only fill the gap).
@@ -202,6 +256,7 @@ def post_tool_use(root: Path, hook_input: dict[str, Any]) -> tuple[str, int]:
         return merged_edit_warning(root, hook_input), 0
     if not is_lifecycle_bash(hook_input):
         return "", 0
+    claim_after_lifecycle_bash(root, hook_input)
     from adapters.host.workflow_state_hook import build_hook_context
 
     context = build_hook_context(

package/template/.cowork-flow/scripts/adapters/mcp/state_server.py

@@ -99,16 +99,36 @@ TOOLS = [
 ]
 
 
-def _tool_task_state(root: Path, arguments: dict) -> dict:
+TRUSTED_PROVENANCE = ("explicit", "host_session")
+
+
+def _implicit_active_task(root: Path) -> tuple[str | None, str]:
+    """Implicit resolution (no explicit `task` argument): the caller's own
+    session-bound active task. A process-fallback identity is shared across
+    every window on the host and a missing identity is no identity at all —
+    neither may impersonate "the current task", so both return no task with
+    an identity-untrusted reason. Returns (task_path, no_task_reason)."""
     from runtime.session_state import get_active_task
+
+    active = get_active_task(root)
+    if active.provenance not in TRUSTED_PROVENANCE:
+        return None, (
+            f"no-active-task (identity-untrusted: {active.provenance})"
+        )
+    if not active.task_path:
+        return None, "no-active-task"
+    return active.task_path, "no-active-task"
+
+
+def _tool_task_state(root: Path, arguments: dict) -> dict:
     from services.fact_view import build_fact_view
     from services.task_repository import TaskRepository, TaskRepositoryError
 
     target = arguments.get("task")
     if not target:
-        target = get_active_task(root).task_path
+        target, reason = _implicit_active_task(root)
         if not target:
-            return {"schemaVersion": 1, "task": None, "reason": "no-active-task"}
+            return {"schemaVersion": 1, "task": None, "reason": reason}
     try:
         task_dir = TaskRepository(root).resolve(target)
     except TaskRepositoryError as error:
@@ -124,17 +144,23 @@ def _tool_task_list(root: Path, _arguments: dict) -> dict:
     records, error = _list_task_records(root, mine=False, status=None)
     if error:
         return {"tasks": [], "count": 0, "error": error}
+    # records[].active is a per-session fact: only a trusted caller identity
+    # whose bound path matches the record may carry it.
+    trusted_active = _implicit_active_task(root)[0]
+    for record in records:
+        record["active"] = (
+            bool(trusted_active) and record.get("path") == trusted_active
+        )
     return {"tasks": records, "count": len(records)}
 
 
 def _resolve_task_dir(root: Path, target: str | None) -> Path:
-    from runtime.session_state import get_active_task
     from services.task_repository import TaskRepository, TaskRepositoryError
 
     if not target:
-        target = get_active_task(root).task_path
+        target, reason = _implicit_active_task(root)
         if not target:
-            raise ValueError("no-active-task")
+            raise ValueError(reason)
     try:
         task_dir = TaskRepository(root).resolve(target)
     except TaskRepositoryError as error:

package/template/.cowork-flow/scripts/runtime/session_state.py

@@ -330,6 +330,41 @@ def set_active_task(repo_root: Path, task_path: str) -> ActiveTask | None:
     return active
 
 
+def claim_active_task(
+    repo_root: Path,
+    task_path: str,
+    values: Mapping[str, object] | None = None,
+) -> ActiveTask | None:
+    """Bind the task to the caller's own resolved session identity.
+
+    Used by host PostToolUse hooks after a lifecycle Bash activation: the CLI
+    process often only carries a shared process-fallback identity, so the hook
+    re-binds with the session id parsed from the hook input. Only explicit /
+    host_session provenance may claim — process_fallback and missing
+    identities are shared or absent, and a main binding written with them
+    would hijack the binding for every other window. Claim failures return
+    None and write nothing.
+    """
+    context_key, provenance = resolve_context_key_with_provenance(values)
+    if not context_key or provenance not in (
+        PROVENANCE_EXPLICIT,
+        PROVENANCE_HOST_SESSION,
+    ):
+        return None
+    normalized = task_path.replace("\\", "/")
+    target = repo_root / normalized
+    if not target.is_dir():
+        return None
+    data: dict[str, object] = {
+        FIELD_ACTIVE_TASK_PATH: normalized,
+        FIELD_SCOPE: SCOPE_MAIN,
+        "platform": platform_from_context_key(context_key),
+        "last_seen_at": _now(),
+    }
+    _write_json(_session_path(repo_root, context_key), data)
+    return ActiveTask(normalized, context_key, "session", provenance=provenance)
+
+
 def get_active_task(repo_root: Path, values: Mapping[str, object] | None = None) -> ActiveTask:
     context_key, provenance = resolve_context_key_with_provenance(values)
     if not context_key:

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -85,8 +85,13 @@ The `<workflow-state>` open tag carries the machine-readable fact header as
 XML attributes; the body keeps the human-readable breadcrumb prose.
 
 - Attributes: `status` and `source` are always present; `task` (repo-relative
-  task path) appears whenever a task is bound. Attribute values are XML-escaped
-  (`& < > "`).
+  task path) appears whenever a task is bound; `session` (the caller's
+  resolved context key) appears whenever a session identity is resolvable
+  from the hook input or environment and is omitted otherwise (hosts that
+  cannot resolve an identity never guess one — the attribute is the machine
+  handle for re-binding with `COWORK_FLOW_CONTEXT_ID`). Attribute values are
+  XML-escaped (`& < > "`). The opencode JS mirror does not emit `session`
+  (delegated-only transport; documented behavioral difference, not drift).
 - The legacy `Task:` / `Status:` / `Source:` label lines are gone — machines
   parse the attributes, humans read the body. There is no bare `Scope:`
   line in the body: the stage-contract block owns the scope declaration
@@ -94,11 +99,19 @@ XML attributes; the body keeps the human-readable breadcrumb prose.
   as a read-only `[read-only]` reference of the parent task).
 
 ```text
-<workflow-state task=".cowork-flow/tasks/08-28-demo" status="in_progress" source="runtime-session">
+<workflow-state task=".cowork-flow/tasks/08-28-demo" status="in_progress" source="runtime-session" session="zcode_probe">
 活动任务正在执行。...
 </workflow-state>
 ```
 
+- Unbound-session fallback (zcode only, display/warning-only): a hook
+  session with no binding follows another main session's binding only while
+  **exactly one** main-session binding exists (`source="session-fallback"`).
+  With two or more main-session bindings the newest one belongs to some
+  other window, so the fallback refuses: the injection renders
+  `status="no_task"` plus the rebind hints list. The CLI lifecycle commands
+  keep their strict identity semantics regardless (FALLBACK_BINDING_BLOCKER).
+
 ## Decision-anchor injection (stage 1)
 
 For tasks whose status is `planning`, `in_progress`, or `review` (a delegated

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"