code-workspace-zhuiyi 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -34,10 +34,11 @@ code-workspace init . \
 ```
 
 Use `--tools claude`, `--tools codex`, or `--tools none` to override the default tool selection. Codex monitoring is enabled by default when Codex is selected; use `--no-monitor` to disable it.
+Pass `--coordination` to install the provider-neutral write-coordination Hook artifacts for the selected tools.
 
 Initialization writes only Workspace-owned state and integrations:
 
-- `.code-workspace/config.yaml` and `.code-workspace/state.json`
+- `.code-workspace/config.yaml`, its referenced project configuration file (default: `.code-workspace/config-projects.yaml`), and `.code-workspace/state.json`
 - `USER_GUIDE.md`
 - `CLAUDE.md` and/or `AGENTS.md`
 - Workspace-specific commands and skills whose names start with `code-workspace-` or use the `/code-workspace` namespace
@@ -50,24 +51,29 @@ It does not create `openspec/`, install native `/opsx` commands, or install nati
 `init` can install integrations from the versioned `extensions/` repository shipped inside this npm package. Select extension names interactively, or pass a comma-separated name list non-interactively. The dedicated install command accepts one or more names; without names it opens the built-in extension multiselect, where ESC exits without changes:
 
 ```bash
-code-w init . --extensions openspec-workspace --yes
+code-w init . --extensions zhuiyi-jira-mcp --yes
 code-w init . --extensions none --yes
 code-w extension install
-code-w extension install openspec-workspace --yes
-code-w extension uninstall openspec-workspace --yes
+code-w extension install zhuiyi-jira-mcp --yes
+code-w extension uninstall zhuiyi-jira-mcp --yes
 ```
 
 The Workspace operation lock shared by init, extension install, and extension uninstall is configured in the Code Workspace project's `.env` (not in the target Workspace). `CODE_WORKSPACE_INIT_LOCK_UPDATE_MS` defaults to `5000`, and `CODE_WORKSPACE_INIT_LOCK_STALE_MS` defaults to `30000`; process environment variables take precedence. See `.env.example` for the project configuration names.
 
-Users select names, not versions; `openspec-workspace@1.0.0` is intentionally rejected. Code Workspace resolves the highest extension SemVer implemented against a Host-supported Extension Spec before confirmation. A new non-interactive Workspace installs no extensions unless `--extensions` is provided. Re-initializing an existing Workspace defaults to its installed extensions and upgrades them when a newer supported built-in version exists. `none` skips extension work and does not uninstall existing artifacts.
+Users select names, not versions; `zhuiyi-jira-mcp@0.1.0` is intentionally rejected. Code Workspace resolves the highest extension SemVer implemented against a Host-supported Extension Spec before confirmation. A new non-interactive Workspace installs no extensions unless `--extensions` is provided. Re-initializing an existing Workspace defaults to its installed extensions and upgrades them when a newer supported built-in version exists. `none` skips extension work and does not uninstall existing artifacts.
 
 `extension install` does not rerun core Workspace initialization. In JSON, non-TTY, or `--yes` mode, at least one extension name is required. Multiple names are installed in order with one confirmation boundary and independent transactions; any failure makes the install command fail while later extensions still run.
 
-The bundled `openspec-workspace` extension installs a namespaced `code-workspace-openspec-propose` skill for the selected Agent tools. It does not create an `openspec/` directory or install native OpenSpec commands.
+The bundled `zhuiyi-jira-mcp` extension configures the Jira MCP service for the selected Agent tools. It does not create an `openspec/` directory or install native OpenSpec commands.
 
 Extension entries run in separate Node processes and generate files in temporary staging directories. The host rejects undeclared, missing, symbolic-link, non-file, path-escaping, conflicting, and checksum-mismatched artifacts before transactionally installing them. Per-Workspace state is stored in `.code-workspace/ext-manifest.json`. A failed extension is reported as a warning and does not roll back successful core initialization or stop later extensions; a failed upgrade restores and retains the previous installed version.
 
-Extensions may own complete files or contribute Host-managed Codex TOML blocks and Hook fragments. Shared targets are composed and verified by Code Workspace; extensions never patch the real Workspace directly. Uninstall uses recorded installed state and does not execute extension code. Unknown changes to extension-owned files or contributions stop the operation instead of being overwritten.
+Extensions may own complete files or declare Host-managed abstract Hooks. Codex and Claude
+adaptors render those declarations into each provider's native configuration and dynamically plug
+or unplug them during extension install, upgrade, and uninstall. Shared targets are composed and
+verified by Code Workspace; extensions never patch the real Workspace directly. Uninstall uses
+recorded installed state and does not execute extension code. Unknown changes to extension-owned
+files or contributions stop the operation instead of being overwritten.
 
 This is fault isolation, not a malicious-code security sandbox. The experimental release trusts only extension code shipped with Code Workspace; network sources, external extension directories, dependencies, arbitrary patches, force uninstall, disable commands, and automatic extension updates through `code-w update` are not supported. The developer contract is in `docs/extensions.md`.
 
@@ -93,6 +99,32 @@ code-workspace project add --projects-file projects.json --yes --json
 
 The registry stores each project's name, real location, registered branch, type, and context. The registered branch is the Code Workspace expected state; the actual branch is observed from the selected Git worktree. Workspace never guesses a path from a conversation or automatically decides which branch is authoritative.
 
+Project registration is always stored in a separate file in the `.code-workspace` directory. Initialization uses `config-projects.yaml` by default, while `projects.ref` may name any safe regular filename in that directory:
+
+```yaml
+# .code-workspace/config.yaml
+projects:
+  ref: config-projects.yaml
+```
+
+The referenced file uses this format:
+
+```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
+projects:
+  - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      Service ownership and navigation context.
+```
+
+`projects.ref` is resolved relative to `config.yaml`. It must be one safe regular filename in the same `.code-workspace` directory; URLs, globs, absolute paths, path traversal, and inline `projects` arrays are not supported. All project commands keep their existing CLI semantics; they read and write the referenced project file. The `.code-workspace/` directory is ignored by default, so Git history for this local registry requires an explicit repository policy.
+
+For example, `ref: team-projects.yaml` makes the project registry `.code-workspace/team-projects.yaml`; the default remains `config-projects.yaml`.
+
 ## Daily commands
 
 ```bash
@@ -117,11 +149,18 @@ The two reconciliation directions are deliberately separate:
 
 Both commands detect plan drift and verify postconditions. `project branch update-latest` is the separate, opt-in path for projects with `updateLatest: true`; it only fetches the configured upstream and fast-forwards a clean matching branch. Code Workspace never creates or downloads a branch and never performs stash, reset, rebase, non-fast-forward merge, production-code edits, or conflict resolution.
 
-Users may manually set the optional project policy in `.code-workspace/config.yaml`:
+Users may manually set the optional project policy in the file named by `projects.ref` (default: `.code-workspace/config-projects.yaml`):
 
 ```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
 projects:
   - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      Service ownership and navigation context.
     updateLatest: true
 ```
 
@@ -129,11 +168,45 @@ AI/Agent must not directly edit this file. They may read the policy and invoke t
 
 `permissions apply` shows the complete authorization plan for the selected Agent tools, requires confirmation when changes are needed, applies and verifies the requested grants, and reports the result per tool. Agent directory access remains a user authorization. The command adds missing registered-project access but does not revoke additional directories; use `project remove` or edit the Agent settings explicitly to revoke access.
 
+## Coordinate concurrent Agent writes
+
+When trusted Codex or Claude Hooks are installed, Code Workspace keeps the coordination ledger outside the Workspace and reserves write ranges before a supported tool runs. Different files in one project can proceed after an explicit project-parallel approval; overlapping files are denied without a force override.
+
+Inspect tasks, claims, and pending recovery decisions:
+
+```bash
+code-workspace task list --json
+code-workspace task show <task-id> --json
+code-workspace task lock list --json
+code-workspace task decision show <request-id> --json
+```
+
+Resolve a pending decision only after reviewing its evidence. Planned-write commands require confirmation; automation must pass `--yes` and always retry the original Agent operation after a successful decision:
+
+```bash
+code-workspace task decision keep <request-id> --yes --json
+code-workspace task decision approve <request-id> --yes --json
+code-workspace task decision release <request-id> --yes --json
+code-workspace task decision abandon <request-id> --yes --json
+```
+
+`ACTIVE` file conflicts cannot be overridden. `UNKNOWN` reservations remain protected until the user keeps them or abandons the entire generation; a known live process blocks abandon. The mechanism covers only trusted, enabled, supported Agent Hooks and is not an OS-level sandbox for editors, shells, or external processes.
+
+Hook support matrix (schema v1):
+
+| Provider | Lifecycle events | Write events | Target handling |
+| --- | --- | --- | --- |
+| Codex | `SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SessionEnd` | `PreToolUse`, `PostToolUse` and available failure events | Known Edit/Write-style tools use exact files; unknown shell/tools use `PROJECT_WIDE` |
+| Claude | `SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `StopFailure`, `SessionEnd` | `PreToolUse`, `PostToolUse`, `PostToolUseFailure` | Same normalized core decisions and scope rules as Codex |
+
+The adapters are versioned fixtures rather than a promise that future Agent releases keep identical native fields. New or unrecognized tools fail closed as possible writes; Hook enforcement does not cover bypassed or disabled Hooks, external editors, or arbitrary OS processes.
+
 ## Update and language
 
 ```bash
 code-workspace update --json
 code-workspace update --language zh-CN --json
+code-workspace update --coordination --json
 code-workspace language --json
 ```
 

package/README.zh-CN.md

@@ -34,10 +34,11 @@ code-workspace init . \
 ```
 
 可用 `--tools claude`、`--tools codex` 或 `--tools none` 覆盖默认工具选择。选择 Codex 时默认启用监控；可传 `--no-monitor` 关闭。
+传入 `--coordination` 可为选中的工具安装与 Monitor 独立的写入协调 Hook 制品。
 
 初始化只写入 Workspace 自有状态和集成：
 
-- `.code-workspace/config.yaml` 与 `.code-workspace/state.json`
+- `.code-workspace/config.yaml`、其引用的项目配置文件（默认：`.code-workspace/config-projects.yaml`）与 `.code-workspace/state.json`
 - `USER_GUIDE.md`
 - `CLAUDE.md` 和/或 `AGENTS.md`
 - 名称以 `code-workspace-` 开头或使用 `/code-workspace` 命名空间的 Workspace 专用命令与 Skill
@@ -50,24 +51,27 @@ code-workspace init . \
 `init` 可以从 npm 包内随附的版本化 `extensions/` 仓库安装集成。交互模式按扩展名多选；非交互模式传入逗号分隔的扩展名。独立安装命令接受一个或多个扩展名；不传名称时打开内置扩展多选，按 ESC 可无修改退出：
 
 ```bash
-code-w init . --extensions openspec-workspace --yes
+code-w init . --extensions zhuiyi-jira-mcp --yes
 code-w init . --extensions none --yes
 code-w extension install
-code-w extension install openspec-workspace --yes
-code-w extension uninstall openspec-workspace --yes
+code-w extension install zhuiyi-jira-mcp --yes
+code-w extension uninstall zhuiyi-jira-mcp --yes
 ```
 
 `init`、扩展安装和扩展卸载共享的 Workspace 操作锁配置在 Code Workspace 项目自身的 `.env` 中（不在目标 Workspace 中）。`CODE_WORKSPACE_INIT_LOCK_UPDATE_MS` 默认值为 `5000`，`CODE_WORKSPACE_INIT_LOCK_STALE_MS` 默认值为 `30000`；进程环境变量优先于 `.env`。配置项名称见 `.env.example`。
 
-用户只选择扩展名，不能选择版本；`openspec-workspace@1.0.0` 会被明确拒绝。Code Workspace 在确认前，从 Host 明确支持的 Extension Spec 实现中解析最高扩展 SemVer。新 Workspace 非交互初始化时，未传 `--extensions` 就不安装扩展；已有 Workspace 重新初始化时，默认选择已安装扩展，并在存在更高受支持内置版本时升级。`none` 只跳过本次扩展初始化，不会卸载已有制品。
+用户只选择扩展名，不能选择版本；`zhuiyi-jira-mcp@0.1.0` 会被明确拒绝。Code Workspace 在确认前，从 Host 明确支持的 Extension Spec 实现中解析最高扩展 SemVer。新 Workspace 非交互初始化时，未传 `--extensions` 就不安装扩展；已有 Workspace 重新初始化时，默认选择已安装扩展，并在存在更高受支持内置版本时升级。`none` 只跳过本次扩展初始化，不会卸载已有制品。
 
 `extension install` 不会重新执行 Workspace 核心初始化。在 JSON、非 TTY 或 `--yes` 模式下，必须至少提供一个扩展名。多个名称按顺序安装，只确认一次且各自使用独立事务；任一扩展失败会使安装命令失败，但后续扩展仍会继续执行。
 
-内置 `openspec-workspace` 扩展会为选中的 Agent 工具安装命名空间为 `code-workspace-openspec-propose` 的 Skill；它不会创建 `openspec/` 目录，也不会安装 OpenSpec 原生命令。
+当前随包提供的内置扩展是 `zhuiyi-jira-mcp`，用于为选中的 Agent 工具配置 Jira MCP 服务；它不会创建 `openspec/` 目录，也不会安装 OpenSpec 原生命令。
 
 扩展入口在独立 Node 进程中运行，只向临时 staging 目录生成文件。Host 会在事务安装前拒绝未声明、缺失、符号链接、非文件、路径逃逸、目标冲突和 hash 不匹配的制品。Workspace 状态存放在 `.code-workspace/ext-manifest.json`。扩展失败以 warning 报告，不回滚已成功的核心初始化，也不阻止后续扩展；升级失败会恢复并保留旧的已安装版本。
 
-扩展可以独占完整文件，也可以贡献由 Host 管理的 Codex TOML 配置块和 Hook 片段。共享目标由 Code Workspace 合成和验证；扩展不会直接 patch 真实 Workspace。卸载只使用已安装状态，不执行扩展代码；扩展所有的文件或贡献存在未知修改时会拒绝覆盖或删除。
+扩展可以独占完整文件，也可以声明由 Host 管理的抽象 Hook。Host 通过 Codex/Claude adaptor
+把声明转换为各自的原生配置，并在扩展安装、升级和卸载时动态插拔；共享目标由 Code
+Workspace 合成和验证，扩展不会直接 patch 真实 Workspace。卸载只使用已安装状态，不执行
+扩展代码；扩展所有的文件或贡献存在未知修改时会拒绝覆盖或删除。
 
 这是故障隔离，不是恶意代码安全沙箱。试验版本只信任随 Code Workspace 发布的扩展代码；暂不支持网络源、外部扩展目录、扩展依赖、任意 patch、强制卸载、禁用命令，也不会通过 `code-w update` 自动更新扩展。开发契约见 `docs/extensions.zh-CN.md`。
 
@@ -93,6 +97,32 @@ code-workspace project add --projects-file projects.json --yes --json
 
 注册表保存项目名称、真实路径、注册分支、类型和上下文。注册分支是 Code Workspace 的期望状态，实际分支是从选中 Git worktree 观测到的状态。Workspace 不会根据对话猜测路径，也不会自动判断哪一侧分支更权威。
 
+项目注册配置始终独立保存于 `.code-workspace` 目录下的单独文件。初始化默认使用 `config-projects.yaml`，但 `projects.ref` 可以引用该目录下任意安全的普通文件名：
+
+```yaml
+# .code-workspace/config.yaml
+projects:
+  ref: config-projects.yaml
+```
+
+引用文件使用以下格式：
+
+```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
+projects:
+  - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      服务职责和代码导航上下文。
+```
+
+`projects.ref` 相对于 `config.yaml` 解析，必须是同一 `.code-workspace` 目录下的安全普通文件名。不支持 URL、glob、绝对路径、路径逃逸或内联 `projects` 数组。所有项目 CLI 的语义保持不变，只是改为读取和写入引用文件。`.code-workspace/` 默认被忽略；如需 Git 历史，需要显式制定仓库策略。
+
+例如，`ref: team-projects.yaml` 会将项目注册表放在 `.code-workspace/team-projects.yaml`；默认名称仍为 `config-projects.yaml`。
+
 ## 日常命令
 
 ```bash
@@ -117,11 +147,18 @@ code-workspace doctor --json
 
 两条命令都会检查计划漂移并验证后置条件。`project branch update-latest` 是独立的显式配置路径：仅当项目 `updateLatest: true` 时，才对干净且分支一致的 worktree fetch upstream 并 fast-forward。Code Workspace 不会创建或下载分支，也不会执行 stash、reset、rebase、非 fast-forward merge、生产代码编辑或冲突处理。
 
-用户可以手动在 `.code-workspace/config.yaml` 中设置项目策略：
+用户可以手动在 `projects.ref` 指定的文件（默认：`.code-workspace/config-projects.yaml`）中设置项目策略：
 
 ```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
 projects:
   - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      服务职责和代码导航上下文。
     updateLatest: true
 ```
 
@@ -129,11 +166,45 @@ AI/Agent 不得直接编辑该文件；可以读取策略并调用已注册的 C
 
 `permissions apply` 会展示选中 Agent 工具的完整授权计划，在需要修改时要求确认，实施并验证请求的授权，并按工具报告结果。Agent 目录访问仍属于用户授权。该命令只补齐已注册项目缺失的访问权限，不撤销额外目录；如需撤销，请使用 `project remove` 或显式编辑 Agent 设置。
 
+## 协调并行 Agent 写入
+
+安装并信任 Codex 或 Claude 协调 Hook 后，Code Workspace 会把协调台账保存在 Workspace 外部，并在受支持工具真正运行前预约写入范围。同一项目写不同文件时，经过一次明确的项目并行确认即可继续；范围重叠时强制拒绝，不提供强制覆盖。
+
+查询任务、范围 claim 和待处理裁决：
+
+```bash
+code-workspace task list --json
+code-workspace task show <task-id> --json
+code-workspace task lock list --json
+code-workspace task decision show <request-id> --json
+```
+
+查看证据后再处理裁决。写入型命令需要确认；自动化场景必须传 `--yes`，裁决成功后始终重新执行原 Agent 操作：
+
+```bash
+code-workspace task decision keep <request-id> --yes --json
+code-workspace task decision approve <request-id> --yes --json
+code-workspace task decision release <request-id> --yes --json
+code-workspace task decision abandon <request-id> --yes --json
+```
+
+`ACTIVE` 文件冲突不能覆盖。`UNKNOWN` reservation 必须由用户选择保留，或放弃整个 generation；已知旧进程仍存活时不能 abandon。该机制只覆盖已信任、已启用且受支持的 Agent Hook，不是编辑器、Shell 或外部进程的 OS 级沙箱。
+
+Hook 支持矩阵（schema v1）：
+
+| Provider | 生命周期事件 | 写入事件 | 目标处理 |
+| --- | --- | --- | --- |
+| Codex | `SessionStart`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SessionEnd` | `PreToolUse`、`PostToolUse` 及可用失败事件 | 已知 Edit/Write 类工具使用 exact 文件；未知 Shell/工具使用 `PROJECT_WIDE` |
+| Claude | `SessionStart`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`StopFailure`、`SessionEnd` | `PreToolUse`、`PostToolUse`、`PostToolUseFailure` | 与 Codex 使用相同的归一化核心决策和范围规则 |
+
+适配器通过版本化 fixture 固化输入，而不是承诺未来 Agent 版本保持相同原生字段。新增或无法识别的工具按可能写入处理并 fail closed；Hook 强制范围不包含被绕过或禁用的 Hook、外部编辑器或任意 OS 进程。
+
 ## 更新与语言
 
 ```bash
 code-workspace update --json
 code-workspace update --language en-US --json
+code-workspace update --coordination --json
 code-workspace language --json
 ```
 

package/artifacts/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "releaseVersion": "0.1.0-beta.2",
+  "releaseVersion": "0.1.0-beta.4",
   "requirements": {
     "node": ">=20.19.0"
   },
@@ -22,6 +22,17 @@
       "sha256": "4dc207305a3975ab7272addedf3bc2930054e860c2b0b2b6e0e102f4457f5cc0"
     }
   ],
+  "coordinationArtifacts": {
+    "schemaVersion": 1,
+    "sources": [
+      { "id": "task-coordination-codex-hooks", "path": "templates/codex/task-coordination-hooks.json", "sha256": "68fcefa83f75294fd270713e07eb3ea3f266e63dc9d2be4ba77fe8af7596742f" },
+      { "id": "task-coordination-claude-settings", "path": "templates/claude/task-coordination-settings.json", "sha256": "4faedcc67a78c8e7e61e44dc34571e55d0d3a2ce1ce7aa636222e1813505ca29" }
+    ],
+    "managedFiles": [
+      { "id": "task-coordination-codex-hooks", "target": ".codex/task-coordination-hooks.json", "tool": "codex" },
+      { "id": "task-coordination-claude-settings", "target": ".claude/task-coordination-settings.json", "tool": "claude" }
+    ]
+  },
   "managedFiles": [
     {
       "id": "workspace-user-guide",

package/artifacts/templates/claude/task-coordination-settings.json

@@ -0,0 +1,13 @@
+{
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "PostToolUseFailure": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "StopFailure": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }],
+    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook claude", "timeout": 2 }] }]
+  }
+}

package/artifacts/templates/codex/task-coordination-hooks.json

@@ -0,0 +1,12 @@
+{
+  "description": "Coordinate supported Codex writes before tools execute. This Hook is independent from Monitor reporting.",
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }],
+    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "code-workspace-task-hook codex", "timeout": 2 }] }]
+  }
+}

package/bin/code-workspace-task-hook.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runHookStdin } = require("../src/core/task-coordination-protocol");
+
+const provider = String(process.argv[2] || "").toLowerCase();
+if (!["codex", "claude"].includes(provider)) {
+  process.stdout.write(JSON.stringify({ decision: "block", reason: "Unsupported task coordination Hook provider." }) + "\n");
+  process.exitCode = 2;
+} else {
+  runHookStdin(provider, { workspaceRoot: process.cwd() })
+    .then((output) => process.stdout.write(`${JSON.stringify(output)}\n`))
+    .catch((error) => {
+      process.stdout.write(`${JSON.stringify({ decision: "block", reason: `Task coordination Hook failed closed: ${error.message}` })}\n`);
+      process.exitCode = 1;
+    });
+}

package/docs/extension-architecture.zh-CN.md

@@ -64,6 +64,10 @@ Host 是 Code Workspace 中负责扩展生命周期治理的核心实现。Host
 
 扩展仓库是 Code Workspace 发布包中用于保存内置扩展的目录集合。基础版不从网络发现或安装扩展定义。
 
+扩展还可以通过 manifest 的 `hooks` 声明抽象 Workspace Hook。Hook 声明由 Host 通过
+Codex/Claude adaptor 转换为原生配置，并随扩展安装、升级和卸载动态插拔；扩展不得把
+Provider 原生事件名直接写入公共合同。
+
 ### 4.3 扩展包
 
 扩展包是一个符合扩展协议的、具有明确 id 和版本的可执行目录：

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/claude/server.json

@@ -5,10 +5,12 @@
   ],
   "env": {
     "JIRA_AUTH_TYPE": "cookie",
+    "JIRA_COOKIE": "",
     "JIRA_API_VERSION": "latest",
     "JIRA_ALLOWED_HOSTS": "jira.in.wezhuiyi.com",
     "JIRA_REQUIREMENT_FIELDS": "{\"acceptanceCriteria\":\"customfield_10042\",\"storyPoints\":\"customfield_10016\"}",
     "JIRA_ATTACHMENT_DIR": ".jira-attachments",
-    "JIRA_ATTACHMENT_MAX_SIZE": "20MB"
+    "JIRA_ATTACHMENT_MAX_SIZE": "20MB",
+    "JIRA_ATTACHMENT_ALLOWED_TYPES": "pdf,png,jpg,jpeg,gif,webp,txt,md,csv,json,xml,doc,docx,xls,xlsx,ppt,pptx,html"
   }
 }

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/codex/config.toml

@@ -4,8 +4,10 @@ args = [".code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/dist/index.js"]
 
 [mcp_servers.zhuiyi-jira.env]
 JIRA_AUTH_TYPE = "cookie"
+JIRA_COOKIE = ""
 JIRA_API_VERSION = "latest"
 JIRA_ALLOWED_HOSTS = "jira.in.wezhuiyi.com"
 JIRA_REQUIREMENT_FIELDS = '{"acceptanceCriteria":"customfield_10042","storyPoints":"customfield_10016"}'
 JIRA_ATTACHMENT_DIR = ".jira-attachments"
 JIRA_ATTACHMENT_MAX_SIZE = "20MB"
+JIRA_ATTACHMENT_ALLOWED_TYPES = "pdf,png,jpg,jpeg,gif,webp,txt,md,csv,json,xml,doc,docx,xls,xlsx,ppt,pptx,html"

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/gitignore

@@ -0,0 +1,2 @@
+# Zhuiyi Jira MCP attachments
+/.jira-attachments/

package/extensions/zhuiyi-jira-mcp/0.1.0/init.js

@@ -30,6 +30,9 @@ async function main() {
   await prepareRelease(release, runtime);
   outputs.push({ id: "runtime", source: "runtime" });
 
+  copyOutput(outputRoot, "artifacts/gitignore", "gitignore");
+  outputs.push({ id: "gitignore", source: "gitignore" });
+
   if (context.tools.includes("codex")) {
     copyOutput(outputRoot, "artifacts/codex/config.toml", "codex-config.toml");
     outputs.push({ id: "codex-config", source: "codex-config.toml" });

package/extensions/zhuiyi-jira-mcp/0.1.0/manifest.json

@@ -6,7 +6,7 @@
   "name": "Zhuiyi Jira MCP",
   "version": "0.1.0",
   "entry": "init.js",
-  "entrySha256": "af7f4a71835402235b3d763418ee1b4135da0125a85aff1153bfaa0f6c83a022",
+  "entrySha256": "53a814ffcbc5669a024f921c5c30e74385d334b749913b0212bdcc2e48a2e0bd",
   "timeoutMs": 120000,
   "capabilities": {
     "networkHosts": ["gitee.com", "raw.giteeusercontent.com"]
@@ -18,6 +18,13 @@
       "ownership": "exclusive",
       "target": ".code-workspace/extensions/zhuiyi-jira-mcp/0.1.0"
     },
+    {
+      "id": "gitignore",
+      "kind": "text-block",
+      "ownership": "shared",
+      "target": ".gitignore",
+      "format": "text"
+    },
     {
       "id": "codex-config",
       "kind": "text-block",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-workspace-zhuiyi",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Local multi-project registry and safety layer for AI coding workspaces",
   "author": "icebearx-ai",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "src/cli",
     "src/index.js",
     "src/core",
+    "src/hooks",
     "src/i18n",
     "src/init",
     "src/monitor",

package/schemas/extension-manifest-v3.json

@@ -4,7 +4,7 @@
   "title": "Code Workspace Extension Spec v1 manifest schema v3",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "extensionSpecVersion", "experimental", "id", "name", "version", "entry", "entrySha256", "timeoutMs", "outputs"],
+  "required": ["schemaVersion", "extensionSpecVersion", "experimental", "id", "name", "version", "entry", "entrySha256", "timeoutMs"],
   "properties": {
     "schemaVersion": { "const": 3 },
     "extensionSpecVersion": { "const": 1 },
@@ -69,8 +69,33 @@
           }
         ]
       }
+    },
+    "hooks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "event", "command"],
+        "properties": {
+          "id": { "$ref": "#/$defs/id" },
+          "event": { "enum": ["task.started", "task.activity", "write.before", "write.after", "task.turn-ended", "task.ended", "task.subagent-started", "task.subagent-ended", "session.start", "session.activity", "session.end", "turn.end", "subagent.start", "subagent.end", "pre-write", "post-write"] },
+          "command": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[^\\r\\n]+$" },
+          "tools": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "enum": ["claude", "codex"] }
+          },
+          "matcher": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[^\\r\\n]+$" },
+          "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 300000 }
+        }
+      }
     }
   },
+  "anyOf": [
+    { "required": ["outputs"], "properties": { "outputs": { "minItems": 1 } } },
+    { "required": ["hooks"], "properties": { "hooks": { "minItems": 1 } } }
+  ],
   "$defs": {
     "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
     "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },

package/spec/extension/v1/specification.en-US.md

@@ -134,6 +134,42 @@ Spec v1 supports four output kinds:
 
 Public output kinds MUST NOT encode private business concepts such as Jira, MCP, npm, archive formats, or individual Agent products.
 
+### 7.1 Abstract Hook declarations
+
+An extension MAY declare pluggable Workspace Hooks. Hooks are not extension output files and
+MUST NOT declare Provider-native names such as `PreToolUse` or `SessionStart`. The optional
+manifest `hooks` array contains entries with at least `id`, `event`, and `command`:
+
+```json
+{
+  "hooks": [
+    {
+      "id": "audit-task",
+      "event": "task.activity",
+      "command": "code-workspace-plugin-audit",
+      "tools": ["codex", "claude"],
+      "matcher": "*",
+      "timeoutMs": 2
+    }
+  ]
+}
+```
+
+Supported abstract events are `task.started`, `task.activity`, `write.before`, `write.after`,
+`task.turn-ended`, `task.ended`, `task.subagent-started`, and `task.subagent-ended`.
+The aliases `session.start`, `session.activity`, `session.end`, `turn.end`, `subagent.start`,
+`subagent.end`, `pre-write`, and `post-write` are accepted and normalized to those events.
+When `tools` is omitted, the declaration applies to every tool supported by the Host.
+`command` is a trusted extension Hook entry point. The Host validates the declaration, renders
+it through a Provider adaptor, and governs its lifecycle; it does not interpret arbitrary native
+configuration fragments.
+
+Codex and Claude adaptors map one abstract event to their native events and compose only the
+extension-owned entries. Install, upgrade, and uninstall use installed Workspace state;
+uninstall does not execute extension code and preserves user and other-extension Hooks. If an
+installed contribution is missing, duplicated, or modified, the Host MUST fail closed and roll
+back the transaction.
+
 ## 8. Staging Verification
 
 An extension MUST generate candidate content only inside the staging directory supplied by the Host. The Host MUST:

package/spec/extension/v1/specification.zh-CN.md

@@ -133,6 +133,40 @@ Spec v1 支持四种输出：
 
 公共输出不得包含 Jira、MCP、npm、归档或特定 Agent 产品的业务类型。
 
+### 7.1 抽象 Hook 声明
+
+扩展可以声明可插拔的 Workspace Hook。Hook 不是扩展输出文件，也不得直接声明
+`PreToolUse`、`SessionStart` 等 Provider 原生名称。manifest 的 `hooks` 是一个可选数组，
+每项至少包含 `id`、`event` 和 `command`：
+
+```json
+{
+  "hooks": [
+    {
+      "id": "audit-task",
+      "event": "task.activity",
+      "command": "code-workspace-plugin-audit",
+      "tools": ["codex", "claude"],
+      "matcher": "*",
+      "timeoutMs": 2
+    }
+  ]
+}
+```
+
+支持的抽象事件为 `task.started`、`task.activity`、`write.before`、`write.after`、
+`task.turn-ended`、`task.ended`、`task.subagent-started` 和 `task.subagent-ended`。
+`session.start`、`session.activity`、`session.end`、`turn.end`、`subagent.start`、
+`subagent.end`、`pre-write` 和 `post-write` 作为兼容别名会被规范化为上述事件。
+`tools` 缺省时表示适用于 Host 支持的全部工具。`command` 是可信扩展提供的 Hook
+执行入口；Host 只负责声明校验、适配器渲染和生命周期治理，不把它解释为任意原生
+配置片段。
+
+Codex 与 Claude 的适配器会把一个抽象事件映射到各自的原生事件，并只合成扩展拥有的
+局部 entry。安装、升级和卸载均依据 Workspace 中的 installed 状态完成；卸载不执行
+扩展代码，并保留用户及其他扩展的 Hook。扩展 Hook 被手动删除、重复或修改时，Host
+必须 fail closed 并回滚本次事务。
+
 ## 8. Staging 验证
 
 扩展只能在 Host 提供的 staging 目录生成候选内容。Host 必须：

package/src/cli/commands/extension.js

@@ -32,6 +32,7 @@ function formatInstallPlan(plans) {
       `  ${plan.id}@${plan.version} [Extension Spec ${plan.extensionSpecVersion}] (manifest ${plan.manifestSha256})`,
       ...(plan.capabilities.networkHosts || []).map((host) => `    NETWORK https://${host}`),
       ...plan.artifacts.map((artifact) => `    WRITE ${artifact.target} (${artifact.kind})`),
+      ...(plan.hooks || []).map((hook) => `    HOOK ${hook.id} (${hook.event}${hook.tools?.length ? ` · ${hook.tools.join(",")}` : ""}) -> ${hook.command}`),
     ]),
   ].join("\n");
 }
@@ -69,6 +70,7 @@ function installResultEntry(entry) {
     extensionSpecVersion: entry.extensionSpecVersion,
     ...(entry.reason ? { reason: entry.reason } : {}),
     ...(entry.artifacts ? { artifacts: entry.artifacts } : {}),
+    ...(entry.hooks ? { hooks: entry.hooks } : {}),
     ...(entry.code ? { code: entry.code } : {}),
     ...(entry.message ? { message: entry.message } : {}),
     ...(entry.statePersisted !== undefined ? { statePersisted: entry.statePersisted } : {}),
@@ -95,7 +97,7 @@ async function executeExtensionInstall(invocation) {
   let requested = invocation.args.length > 0 ? normalizeExtensionNames(invocation.args) : null;
   if (requested === null && !interactive) {
     throw new WorkspaceError("EXTENSION_SELECTION_REQUIRED", "Extension installation requires one or more extension names outside interactive mode.", {
-      remediation: "Pass one or more names, for example: code-w extension install openspec-workspace --yes",
+      remediation: "Pass one or more extension names, for example: code-w extension install <extension-name> --yes",
     });
   }
 

package/src/cli/commands/init.js

@@ -120,6 +120,7 @@ async function executeInitUnlocked(invocation, root) {
     workspaceUuid: plan?.workspace.uuid,
     monitor: plan?.monitor.enable ?? (options.monitor === true ? true : options["no-monitor"] === true ? false : undefined),
     monitorUrl: plan?.monitor.url || options["monitor-url"],
+    coordination: options.coordination === true,
     language: plan?.language || options.language,
     interactive: false,
     initPlan: plan,
@@ -172,6 +173,7 @@ async function executeInitUnlocked(invocation, root) {
     monitor: result.workspaceConfig.monitor,
     language: result.language,
     tools: toolSelection,
+    coordination: options.coordination === true,
     migration: migrationData(result.migration),
     permissions: result.permissions,
     verification: result.verification,