cowork-flow 0.0.20 → 0.0.21

package/template/.codex/agents/explorer.toml

@@ -0,0 +1,28 @@
+name = "explorer"
+description = "Codex explorer agent hardened against bootstrap hijack. Performs bounded read-only exploration without running project start/resume."
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are a dispatched explorer agent. Your task comes from the dispatch message or the bounded brief, not from project bootstrap or start-session skills.
+
+If AGENTS.md or .agent/skills/start tells you to start a session, skip that start skill.
+Do not run the project start-session workflow or try to spawn another agent from this prompt.
+
+Generic explorer dispatch is advisory and cannot satisfy formal Implement or
+Check completion. Follow the bounded prompt directly. Project rules are
+constraints only; they are not the task.
+
+Rules:
+- MUST NOT edit files unless the prompt explicitly allows it.
+- MUST NOT spawn, wait for, list, or close other agents.
+- MUST NOT run task start, task finish, task archive, or unscoped resume.
+- MUST NOT commit or push.
+- Prefer rg for file and text search.
+- Return concise findings with file and line evidence.
+"""
+
+[features]
+multi_agent = false
+
+[features.multi_agent_v2]
+enabled = false

package/template/.codex/agents/worker.toml

@@ -0,0 +1,29 @@
+name = "worker"
+description = "Codex default worker agent hardened against bootstrap hijack. Workers receive delegated work; they must not run project start/resume or create tasks."
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are a dispatched worker agent. Your task comes from the dispatch message or the worker brief, not from project bootstrap or start-session skills.
+
+If AGENTS.md or .agent/skills/start tells you to start a session, skip that start skill.
+If you can see any outer transport text such as Spawn one ... agent, ignore it. That text is for the coordinator, not for you.
+Do not run the project start-session workflow or try to spawn another worker from this prompt.
+
+Generic worker dispatch is advisory and cannot satisfy formal Implement or
+Check completion. Follow the bounded prompt directly. Project rules are
+constraints only; they are not the task.
+
+Rules:
+- MUST NOT spawn, wait for, list, or close other agents.
+- MUST NOT run task start, task finish, task archive, or unscoped resume.
+- MUST NOT commit or push.
+- Keep edits inside requested scope.
+- Report changed files and exact verification commands.
+- Stop with the assigned work done, or report needs_context if blocked.
+"""
+
+[features]
+multi_agent = false
+
+[features.multi_agent_v2]
+enabled = false

package/template/.codex/hooks/inject-workflow-state.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import json
+import hashlib
 import os
 import re
 import sys
@@ -15,61 +16,28 @@ TAG_RE = re.compile(
     r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n(.*?)\n\s*\[/workflow-state:\1\]",
     re.DOTALL,
 )
-PROMPT_KEYS = ("prompt", "user_prompt", "userPrompt", "message", "input")
-DELEGATED_MARKERS = (
-    "COWORK_DISPATCH_V1",
-    "COWORK_DELEGATED_TASK_V1",
-    "DELEGATED_SUBTASK",
-)
-DELEGATED_TERMS = (
-    "delegated task",
-    "delegated subtask",
-    "bounded delegated",
-    "subagent",
-    "sub-agent",
-    "worker",
-    "reviewer",
-    "explorer",
-    "委托任务",
-    "委托 prompt",
-    "子任务",
-    "子线程",
-)
-TASK_TERMS = (
-    "task:",
-    "topic:",
-    "focus:",
-    "任务：",
-    "任务:",
-    "主题：",
-    "目标：",
-    "审视",
-    "讨论",
-    "review",
-    "inspect",
-)
-BOUNDARY_TERMS = (
-    "do not edit",
-    "do not run",
-    "do not spawn",
-    "return concise analysis only",
-    "不要编辑",
-    "不要运行",
-    "不要派发",
-    "不要只确认",
-    "只输出",
-    "不要改",
-)
-OUTPUT_TERMS = (
-    "output:",
-    "required output",
-    "return in",
-    "max ",
-    "最多",
-    "输出：",
-    "输出:",
-    "分为",
-)
+DEFAULT_CONTRACT_REGISTRY = {
+    "contracts": [
+        {
+            "id": "COWORK_ENTRY_CONTRACT_V1",
+            "path": ".cowork-flow/spec/entry-contract.md",
+            "digest": [
+                "Classify main-session requests before task start, resume, archive, or commit.",
+                "Runtime context, not prompt labels, identifies formal subagent sessions.",
+            ],
+            "readWhen": ["before task start/resume/archive", "when prompt and bootstrap text conflict"],
+        },
+        {
+            "id": "RUNTIME_CONTEXT_DISPATCH_V2",
+            "path": ".cowork-flow/spec/subagent-dispatch.md",
+            "digest": [
+                "Formal subagent work is keyed by cowork_runtime_context_id.",
+                "Explicit shim bind records bound_context_key before formal output is accepted.",
+            ],
+            "readWhen": ["before formal subagent dispatch", "when checking subagent health"],
+        },
+    ]
+}
 
 def _find_repo_root(start: Path) -> Path | None:
     current = start.resolve()
@@ -83,42 +51,28 @@ def _find_repo_root(start: Path) -> Path | None:
 
 def _read_hook_input() -> dict[str, Any]:
     try:
-        data = json.load(sys.stdin)
+        raw = sys.stdin.buffer.read()
+    except AttributeError:
+        text = sys.stdin.read()
+    else:
+        if not raw.strip():
+            return {}
+        try:
+            text = raw.decode("utf-8-sig")
+        except UnicodeDecodeError:
+            encoding = getattr(sys.stdin, "encoding", None) or "utf-8"
+            text = raw.decode(encoding, errors="replace")
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
     except (json.JSONDecodeError, ValueError):
         return {}
     return data if isinstance(data, dict) else {}
 
 
-def _extract_prompt(hook_input: dict[str, Any]) -> str:
-    values: list[str] = []
-    for key in PROMPT_KEYS:
-        value = hook_input.get(key)
-        if isinstance(value, str) and value.strip():
-            values.append(value)
-    return "\n".join(values)
-
-
-def _contains_any(text: str, terms: tuple[str, ...]) -> bool:
-    return any(term in text for term in terms)
-
-
-def _is_delegated_prompt(hook_input: dict[str, Any]) -> bool:
-    prompt = _extract_prompt(hook_input)
-    if not prompt.strip():
-        return False
-    if any(marker in prompt for marker in DELEGATED_MARKERS):
-        return True
-
-    lowered = prompt.lower()
-    has_task = _contains_any(lowered, TASK_TERMS)
-    has_delegated_role = _contains_any(lowered, DELEGATED_TERMS)
-    has_boundary = _contains_any(lowered, BOUNDARY_TERMS)
-    has_output = _contains_any(lowered, OUTPUT_TERMS)
-    return has_task and (has_delegated_role or has_boundary) and (has_output or has_boundary)
-
-
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
-    workflow = root / ".cowork-flow" / "workflow.md"
+    workflow = root / ".cowork-flow" / "spec" / "workflow-state-templates.md"
     try:
         text = workflow.read_text(encoding="utf-8")
     except OSError:
@@ -126,6 +80,62 @@ def _load_breadcrumbs(root: Path) -> dict[str, str]:
     return {match.group(1): match.group(2).strip() for match in TAG_RE.finditer(text)}
 
 
+def _as_string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str) and item.strip()]
+
+
+def _load_contract_registry(root: Path) -> list[dict[str, Any]]:
+    registry_file = root / ".cowork-flow" / "spec" / "registry.json"
+    try:
+        data = json.loads(registry_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        data = DEFAULT_CONTRACT_REGISTRY
+    contracts = data.get("contracts") if isinstance(data, dict) else None
+    if not isinstance(contracts, list):
+        contracts = DEFAULT_CONTRACT_REGISTRY["contracts"]
+    return [contract for contract in contracts if isinstance(contract, dict)]
+
+
+def _contract_fingerprint(root: Path, contracts: list[dict[str, Any]]) -> str:
+    digest = hashlib.sha256()
+    digest.update(json.dumps(contracts, ensure_ascii=False, sort_keys=True).encode("utf-8"))
+    for contract in contracts:
+        path = contract.get("path")
+        if not isinstance(path, str) or not path.strip():
+            continue
+        try:
+            digest.update((root / path).read_bytes())
+        except OSError:
+            digest.update(f"missing:{path}".encode("utf-8"))
+    return digest.hexdigest()[:16]
+
+
+def _build_contract_digest(root: Path) -> str:
+    contracts = _load_contract_registry(root)
+    fingerprint = _contract_fingerprint(root, contracts)
+    lines = [
+        '<cowork-runtime host="codex" adapter="codex.spawn_agent">',
+        f'<contract-digest fingerprint="{fingerprint}">',
+        "policy: repeat this short digest every hook; read full spec files only before listed actions.",
+    ]
+    for contract in contracts:
+        contract_id = contract.get("id")
+        path = contract.get("path")
+        if not isinstance(contract_id, str) or not contract_id.strip():
+            continue
+        path_text = path if isinstance(path, str) and path.strip() else "<missing-path>"
+        lines.append(f"- {contract_id}: {path_text}")
+        for item in _as_string_list(contract.get("digest"))[:2]:
+            lines.append(f"  digest: {item}")
+        read_when = _as_string_list(contract.get("readWhen"))
+        if read_when:
+            lines.append(f"  read_before: {'; '.join(read_when)}")
+    lines.extend(["</contract-digest>", "</cowork-runtime>"])
+    return "\n".join(lines)
+
+
 def _load_common(root: Path) -> None:
     scripts_dir = root / ".cowork-flow" / "scripts"
     if str(scripts_dir) not in sys.path:
@@ -144,21 +154,6 @@ def _get_dispatch_mode(root: Path) -> str:
         return "sub-agent"
 
 
-def _get_post_ack_execution_grace_ms(root: Path) -> int:
-    _load_common(root)
-    try:
-        from common.config import (  # type: ignore[import-not-found]
-            DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS,
-            get_codex_post_ack_execution_grace_ms,
-        )
-    except Exception:
-        return 300000
-    try:
-        return get_codex_post_ack_execution_grace_ms(root)
-    except Exception:
-        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
-
-
 def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None, str, str]:
     _load_common(root)
     try:
@@ -183,15 +178,55 @@ def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None
     return active.task_path, status.strip(), active.source
 
 
+def _resolve_runtime_context(root: Path, hook_input: dict[str, Any]) -> tuple[dict[str, Any] | None, str | None]:
+    _load_common(root)
+    try:
+        from common.active_task import (  # type: ignore[import-not-found]
+            bind_runtime_context,
+            read_runtime_context,
+            resolve_runtime_context_id,
+        )
+    except Exception:
+        return None, None
+
+    runtime_context_id = resolve_runtime_context_id(hook_input)
+    if not runtime_context_id:
+        return None, None
+
+    context = read_runtime_context(root, runtime_context_id)
+    if not context or context.get("scope") != "subagent" or context.get("status") == "closed":
+        return None, runtime_context_id
+
+    bound = bind_runtime_context(root, runtime_context_id, values=hook_input)
+    return bound or context, runtime_context_id
+
+
+def _subagent_runtime_lines(context: dict[str, Any]) -> list[str]:
+    assignment = context.get("assignment") if isinstance(context.get("assignment"), dict) else {}
+    lines = [
+        f"Runtime context: {context.get('runtime_context_id')}",
+        f"Agent: {context.get('agent_type') or 'unknown'}",
+        "Scope: subagent",
+        "Do not run start/resume/task start/archive/commit/spawn.",
+    ]
+    goal = assignment.get("goal") if isinstance(assignment, dict) else None
+    if isinstance(goal, str) and goal.strip():
+        lines.append(f"Goal: {goal.strip()}")
+    return lines
+
+
 def _build_context(
+    root: Path,
     task_path: str | None,
     status: str,
     source: str,
     breadcrumbs: dict[str, str],
     dispatch_mode: str,
-    post_ack_execution_grace_ms: int,
+    extra_lines: list[str] | None = None,
 ) -> str:
     body = breadcrumbs.get(status) or "Refer to .cowork-flow/workflow.md for the current step."
+    if extra_lines:
+        body = "\n".join([body, *extra_lines])
     if task_path is None:
         header = f"Status: {status}\nSource: {source}"
     else:
@@ -199,12 +234,16 @@ def _build_context(
 
     return "\n\n".join(
         [
-            f"<codex-mode>{dispatch_mode}</codex-mode>",
+            f"<codex-dispatch-mode>{dispatch_mode}</codex-dispatch-mode>",
             (
                 "<codex-runtime>\n"
-                f"post_ack_execution_grace_ms: {post_ack_execution_grace_ms}\n"
+                "dispatch_mode_meaning: workflow dispatch hint, not current thread role\n"
+                "runtime_context_identity: formal subagent sessions bind before workflow-state injection\n"
                 "</codex-runtime>"
             ),
+            (
+                _build_contract_digest(root)
+            ),
             f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
         ]
     )
@@ -223,19 +262,33 @@ def main() -> int:
 
     breadcrumbs = _load_breadcrumbs(root)
     dispatch_mode = _get_dispatch_mode(root)
-    post_ack_execution_grace_ms = _get_post_ack_execution_grace_ms(root)
-    task_path, status, source = _get_active_task(root, hook_input)
-    if _is_delegated_prompt(hook_input):
+    runtime_context, runtime_context_id = _resolve_runtime_context(root, hook_input)
+    extra_lines: list[str] | None = None
+    if runtime_context is not None:
+        task_dir = runtime_context.get("task_dir")
+        task_path = task_dir.strip() if isinstance(task_dir, str) and task_dir.strip() else None
+        status = "delegated_subtask"
+        source = f"runtime-context:{runtime_context.get('runtime_context_id')}"
+        extra_lines = _subagent_runtime_lines(runtime_context)
+    elif runtime_context_id:
         task_path = None
         status = "delegated_subtask"
-        source = "prompt"
+        source = f"runtime-context-invalid:{runtime_context_id}"
+        extra_lines = [
+            f"Runtime context: {runtime_context_id}",
+            "Scope: subagent",
+            "Runtime context is missing, closed, or invalid. Do not run start/resume/task start/archive/commit/spawn.",
+        ]
+    else:
+        task_path, status, source = _get_active_task(root, hook_input)
     additional_context = _build_context(
+        root,
         task_path,
         status,
         source,
         breadcrumbs,
         dispatch_mode,
-        post_ack_execution_grace_ms,
+        extra_lines,
     )
 
     print(

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.20
+0.0.21

package/template/.cowork-flow/adapters/claude-code/adapter.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+host: claude-code
+displayName: Claude Code
+capabilities:
+  dispatchSubagent: native
+  freshChildContext: native
+  sendFollowup: native
+  waitChild: native
+  listChildren: native
+  cancelChild: native
+  stateInjection: external
+  backgroundChild: experimental
+  runtimeContextDispatch: native
+  runtimeContextBinding: shim
+  runtimeContextCleanup: native
+dispatch:
+  primitive: subagent
+  agentsPath: .claude/agents
+  skillsPath: .claude/skills
+  commandsPath: .claude/commands
+  settingsPath: .claude/settings.json
+  hooksPath: .claude/hooks
+  memoryPath: CLAUDE.md
+runtimeContext:
+  transport: prompt
+  promptKey: cowork_runtime_context_id
+  envKey: COWORK_FLOW_RUNTIME_CONTEXT_ID
+  metadataKey: cowork_runtime_context_id
+contracts:
+  entry: COWORK_ENTRY_CONTRACT_V1
+  dispatch: RUNTIME_CONTEXT_DISPATCH_V2
+  leafExecutor: true
+fallback:
+  whenRequiredCapabilityMissing: inline_or_manual
+  whenRuntimeContextMissing: fail_closed

package/template/.cowork-flow/adapters/codex/adapter.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+host: codex
+displayName: Codex
+capabilities:
+  dispatchSubagent: native
+  freshChildContext: native
+  sendFollowup: native
+  waitChild: native
+  listChildren: native
+  cancelChild: native
+  stateInjection: native
+  backgroundChild: native
+  runtimeContextDispatch: native
+  runtimeContextBinding: shim
+  runtimeContextCleanup: native
+dispatch:
+  primitive: spawn_agent
+  forkTurns: none
+  followupPrimitive: assign_task
+  waitPrimitive: wait_agent
+  listPrimitive: list_agents
+  cancelPrimitive: close_agent
+  agentsPath: .codex/agents
+runtimeContext:
+  transport: prompt
+  promptKey: cowork_runtime_context_id
+  envKey: COWORK_FLOW_RUNTIME_CONTEXT_ID
+  metadataKey: cowork_runtime_context_id
+contracts:
+  entry: COWORK_ENTRY_CONTRACT_V1
+  dispatch: RUNTIME_CONTEXT_DISPATCH_V2
+  leafExecutor: true
+fallback:
+  whenRequiredCapabilityMissing: inline_or_manual
+  whenRuntimeContextMissing: fail_closed

package/template/.cowork-flow/adapters/opencode/adapter.yaml

@@ -0,0 +1,33 @@
+schemaVersion: 1
+host: opencode
+displayName: OpenCode
+capabilities:
+  dispatchSubagent: native
+  freshChildContext: native
+  sendFollowup: shim
+  waitChild: native
+  listChildren: native
+  cancelChild: native
+  stateInjection: plugin
+  backgroundChild: experimental
+  runtimeContextDispatch: native
+  runtimeContextBinding: shim
+  runtimeContextCleanup: native
+dispatch:
+  primitive: task
+  agentsPath: .opencode/agents
+  commandsPath: .opencode/commands
+  pluginsPath: .opencode/plugins
+  backgroundRequiresEnv: OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
+runtimeContext:
+  transport: prompt
+  promptKey: cowork_runtime_context_id
+  envKey: COWORK_FLOW_RUNTIME_CONTEXT_ID
+  metadataKey: cowork_runtime_context_id
+contracts:
+  entry: COWORK_ENTRY_CONTRACT_V1
+  dispatch: RUNTIME_CONTEXT_DISPATCH_V2
+  leafExecutor: true
+fallback:
+  whenRequiredCapabilityMissing: inline_or_manual
+  whenRuntimeContextMissing: fail_closed

package/template/.cowork-flow/config.yaml

@@ -18,17 +18,15 @@ max_journal_lines: 2000
 # Codex Runtime
 #-------------------------------------------------------------------------------
 
-# This controls only the injected workflow hint (<codex-mode>...).
+# This controls only the injected workflow dispatch hint (<codex-dispatch-mode>...).
 # It does not force dispatch or disable tools at runtime.
 # sub-agent: hint that main session should dispatch cowork-* fixed agents.
 # inline: hint that main session should perform implementation/check directly.
 codex:
   dispatch_mode: "sub-agent"
-  # Grace duration after each subagent ACKs and receives EXECUTE.
-  # This is a per-dispatch duration, not a shared/global deadline.
-  # During this window, missing output or missing compass/status files do not
-  # prove the child is stuck while it loads task context.
-  post_ack_execution_grace_ms: 300000
+  # Formal subagent identity is runtime-context based. The main session creates
+  # .cowork-flow/.runtime/subagents/<id>.json with the subagent helper, then
+  # passes cowork_runtime_context_id through the active host adapter transport.
 
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks

package/template/.cowork-flow/scripts/add_session.py

@@ -18,6 +18,9 @@ from datetime import datetime
 from pathlib import Path
 
 from common.paths import (
+    DIR_TASKS,
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
     FILE_JOURNAL_PREFIX,
     count_lines,
     get_repo_root,
@@ -292,14 +295,16 @@ def update_index(
 def _auto_commit_workspace(repo_root: Path) -> None:
     """Stage .cowork-flow/workspace and .cowork-flow/tasks, then commit with a configured message."""
     commit_msg = get_session_commit_message(repo_root)
+    workspace_rel = f"{DIR_WORKFLOW}/{DIR_WORKSPACE}"
+    tasks_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}"
     subprocess.run(
-        ["git", "add", "-A", f"{DIR_WORKFLOW}/{DIR_WORKSPACE}", f"{DIR_WORKFLOW}/{DIR_TASKS}"],
+        ["git", "add", "-A", workspace_rel, tasks_rel],
         cwd=repo_root,
         capture_output=True,
     )
     # Check if there are staged changes
     result = subprocess.run(
-        ["git", "diff", "--cached", "--quiet", "--", ".cowork-flow/workspace", ".cowork-flow/tasks"],
+        ["git", "diff", "--cached", "--quiet", "--", workspace_rel, tasks_rel],
         cwd=repo_root,
     )
     if result.returncode == 0:
@@ -322,7 +327,7 @@ def add_session(
     commit: str = "-",
     summary: str = "(add summary)",
     extra_content: str = "(add details)",
-    auto_commit: bool = True,
+    auto_commit: bool = False,
 ) -> int:
     """Add a new session."""
     repo_root = get_repo_root()
@@ -397,7 +402,7 @@ def add_session(
     print(f"  - {target_file.name if target_file else 'journal'}", file=sys.stderr)
     print("  - index.md", file=sys.stderr)
 
-    # Auto-commit workspace changes
+    # Auto-commit workspace changes only when explicitly requested.
     if auto_commit:
         print("", file=sys.stderr)
         _auto_commit_workspace(repo_root)
@@ -418,8 +423,16 @@ def main() -> int:
     parser.add_argument("--commit", default="-", help="Comma-separated commit hashes")
     parser.add_argument("--summary", default="(add summary)", help="Brief summary")
     parser.add_argument("--content-file", help="Path to a file containing detailed content")
-    parser.add_argument("--no-commit", action="store_true",
-                        help="Skip automatic .cowork-flow metadata commit")
+    parser.add_argument(
+        "--auto-commit",
+        action="store_true",
+        help="Auto git commit after recording workspace metadata",
+    )
+    parser.add_argument(
+        "--no-commit",
+        action="store_true",
+        help="Deprecated no-op; add-session no longer commits by default",
+    )
 
     args = parser.parse_args()
 
@@ -433,7 +446,7 @@ def main() -> int:
 
     return add_session(
         args.title, args.commit, args.summary, extra_content,
-        auto_commit=not args.no_commit,
+        auto_commit=args.auto_commit and not args.no_commit,
     )