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

package/README.md

@@ -34,7 +34,7 @@ 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.
+Pass `--coordination` to install the write-coordination Hooks into the selected providers' native configuration.
 
 Initialization writes only Workspace-owned state and integrations:
 
@@ -42,7 +42,7 @@ Initialization writes only Workspace-owned state and integrations:
 - `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
-- `.codex/hooks.json` when monitoring is enabled
+- `.codex/hooks.json` when monitoring or Codex coordination is enabled, and `.claude/settings.json` when Claude coordination is enabled
 
 It does not create `openspec/`, install native `/opsx` commands, or install native `openspec-*` skills.
 

package/README.zh-CN.md

@@ -34,7 +34,7 @@ code-workspace init . \
 ```
 
 可用 `--tools claude`、`--tools codex` 或 `--tools none` 覆盖默认工具选择。选择 Codex 时默认启用监控；可传 `--no-monitor` 关闭。
-传入 `--coordination` 可为选中的工具安装与 Monitor 独立的写入协调 Hook 制品。
+传入 `--coordination` 可把与 Monitor 独立的写入协调 Hook 安装到选中工具的原生配置中。
 
 初始化只写入 Workspace 自有状态和集成：
 
@@ -42,7 +42,7 @@ code-workspace init . \
 - `USER_GUIDE.md`
 - `CLAUDE.md` 和/或 `AGENTS.md`
 - 名称以 `code-workspace-` 开头或使用 `/code-workspace` 命名空间的 Workspace 专用命令与 Skill
-- 启用监控时的 `.codex/hooks.json`
+- 启用监控或 Codex 协调时的 `.codex/hooks.json`，以及启用 Claude 协调时的 `.claude/settings.json`
 
 它不会创建 `openspec/`，不会安装原生 `/opsx` 命令，也不会安装原生 `openspec-*` Skill。
 

package/artifacts/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "releaseVersion": "0.1.0-beta.4",
+  "releaseVersion": "0.1.0-beta.6",
   "requirements": {
     "node": ">=20.19.0"
   },

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

@@ -2,16 +2,53 @@
 "use strict";
 
 const { runHookStdin } = require("../src/core/task-coordination-protocol");
+const { getAdapter } = require("../src/hooks/adapters");
 
 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");
+let adapter = null;
+try {
+  adapter = getAdapter(provider);
+} catch {
+  // Keep the provider error below provider-neutral because no native renderer
+  // is available for an unknown provider.
+}
+
+function writeFailure(reason) {
+  const output = adapter?.renderFailure
+    ? adapter.renderFailure({ remediation: reason })
+    : { decision: "block", reason };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+let workspaceRoot = process.cwd();
+for (let index = 3; index < process.argv.length; index += 1) {
+  const argument = process.argv[index];
+  if (argument === "--workspace-root-b64") {
+    const encoded = process.argv[++index];
+    try {
+      workspaceRoot = Buffer.from(String(encoded || ""), "base64url").toString("utf8");
+      if (!workspaceRoot) throw new Error("empty path");
+    } catch {
+      writeFailure("Invalid task coordination Hook workspace root.");
+      process.exitCode = 2;
+      break;
+    }
+  } else if (argument === "--workspace-root") {
+    workspaceRoot = String(process.argv[++index] || "");
+  } else {
+    writeFailure(`Unsupported task coordination Hook option: ${argument}`);
+    process.exitCode = 2;
+    break;
+  }
+}
+if (!adapter) {
+  writeFailure("Unsupported task coordination Hook provider.");
   process.exitCode = 2;
-} else {
-  runHookStdin(provider, { workspaceRoot: process.cwd() })
+} else if (process.exitCode !== 2) {
+  runHookStdin(provider, { workspaceRoot })
     .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`);
+      writeFailure(`Task coordination Hook failed closed: ${error.message}`);
       process.exitCode = 1;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-workspace-zhuiyi",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Local multi-project registry and safety layer for AI coding workspaces",
   "author": "icebearx-ai",
   "license": "MIT",
@@ -13,7 +13,8 @@
   },
   "bin": {
     "code-workspace": "bin/code-workspace.js",
-    "code-w": "bin/code-workspace.js"
+    "code-w": "bin/code-workspace.js",
+    "code-workspace-task-hook": "bin/code-workspace-task-hook.js"
   },
   "files": [
     "assets",

package/src/cli/commands/init.js

@@ -111,6 +111,7 @@ async function executeInitUnlocked(invocation, root) {
   const extensionPreparation = prepareExtensionPlans(extensionCatalogResult, requestedExtensions, { tools, state: extensionState, stateError: extensionStateInspection.error });
   const extensionPlans = extensionPreparation.plans;
   const toolSelection = { tools, source: plan ? (options.tools !== undefined ? "cli" : "interactive") : resolvedTools.source };
+  const coordination = options.coordination === true || existingState?.coordination === true;
   const result = await initializeWorkspace(root, {
     run,
     tools,
@@ -120,7 +121,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,
+    coordination,
     language: plan?.language || options.language,
     interactive: false,
     initPlan: plan,
@@ -173,7 +174,7 @@ async function executeInitUnlocked(invocation, root) {
     monitor: result.workspaceConfig.monitor,
     language: result.language,
     tools: toolSelection,
-    coordination: options.coordination === true,
+    coordination,
     migration: migrationData(result.migration),
     permissions: result.permissions,
     verification: result.verification,

package/src/cli/commands/update.js

@@ -13,7 +13,7 @@ const { WorkspaceError } = require("../../core/errors");
 const { commitUpdateState, loadInitManifest } = require("../../core/init");
 const { workspaceGuide } = require("../../core/language");
 const { inspectManagedFiles, installManagedFiles, planManagedFiles } = require("../../core/managed-files");
-const { installCoordinationArtifacts } = require("../../core/task-coordination-managed");
+const { coordinationHookTargets, installCoordinationHooks, removeCoordinationHooks } = require("../../core/task-coordination-managed");
 const { planWorkspaceMaintenance } = require("../../core/migration");
 const { inspectProjectPermissions } = require("../../core/permissions");
 const { resolveWorkspaceTools } = require("../../core/tools");
@@ -21,8 +21,8 @@ const { createFileTransaction } = require("../../core/transaction");
 const { success } = require("../result");
 const { migrationData } = require("./init");
 
-function verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables) {
-  const inspection = inspectManagedFiles(root, manifest, tools, capabilities, variables);
+function verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables, options = {}) {
+  const inspection = inspectManagedFiles(root, manifest, tools, capabilities, variables, options);
   const incomplete = [
     ...inspection.managedOld.map((target) => ({ target, state: "managed-old" })),
     ...inspection.replaceable.map((target) => ({ target, state: "replaceable" })),
@@ -55,6 +55,10 @@ function updateWorkspace(root, options = {}) {
     manifestTools: manifest.tools,
   });
   const tools = toolSelection.tools;
+  const previousCoordination = initialState.coordination === true;
+  const previousTools = Array.isArray(initialState.tools) ? initialState.tools : [];
+  const removedCoordinationTools = previousCoordination ? previousTools.filter((tool) => !tools.includes(tool)) : [];
+  const coordination = options.coordination === true || initialState.coordination === true;
   const migration = planWorkspaceMaintenance(root, {
     language: options.language,
     allowLegacy: true,
@@ -64,7 +68,7 @@ function updateWorkspace(root, options = {}) {
   const config = loadConfig(root, { defaultLanguage: language });
   const nextConfig = { ...config, workspace: { ...config.workspace, language } };
   const capabilities = nextConfig.monitor.enable ? ["monitor"] : [];
-  if (options.coordination === true) capabilities.push("coordination");
+  if (coordination) capabilities.push("coordination");
   const variables = { WORKSPACE_LANGUAGE: language, WORKSPACE_USER_GUIDE: workspaceGuide(language) };
   let managedPlan;
   let obsoletePlan;
@@ -72,6 +76,7 @@ function updateWorkspace(root, options = {}) {
     managedPlan = planManagedFiles(root, manifest, tools, {
       force: options.force === true,
       capabilities,
+      coordination,
       variables,
     });
     obsoletePlan = planObsoleteAssets(root, tools, { force: options.force === true });
@@ -88,7 +93,9 @@ function updateWorkspace(root, options = {}) {
     resolveProjectConfigPath(root),
     statePath(root),
     ...managedPlan.plans.map((plan) => plan.target),
-    ...(options.coordination === true ? [path.join(root, ".codex", "task-coordination-hooks.json"), path.join(root, ".claude", "task-coordination-settings.json")] : []),
+    ...coordinationHookTargets(root, coordination
+      ? [...new Set([...tools, ...removedCoordinationTools])]
+      : removedCoordinationTools),
     ...obsoletePlan.map((plan) => path.join(root, plan.target)),
   ]);
   try {
@@ -97,25 +104,31 @@ function updateWorkspace(root, options = {}) {
     const managedFiles = installManagedFiles(root, manifest, tools, {
       force: options.force === true,
       capabilities,
+      coordination,
       variables,
     });
-    if (options.coordination === true) {
-      managedFiles.push(...installCoordinationArtifacts(root, tools, { force: options.force === true }).map((entry) => ({ ...entry, id: `task-coordination-${entry.tool}` })));
+    managedFiles.push(...removeCoordinationHooks(root, removedCoordinationTools).map((entry) => ({ ...entry, id: `task-coordination-remove-${entry.tool}` })));
+    if (coordination) {
+      managedFiles.push(...installCoordinationHooks(root, tools, { force: options.force === true }).map((entry) => ({ ...entry, id: `task-coordination-${entry.tool}` })));
     }
     options.injectFailure?.("after-managed-install", managedFiles);
     saveConfig(root, nextConfig);
     options.injectFailure?.("after-config-save", nextConfig);
-    verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables);
-    if (options.coordination === true) {
-      const coordinationIncomplete = installCoordinationArtifacts(root, tools, { dryRun: true }).filter((entry) => entry.action !== "skip");
+    verifyUpdatedManagedFiles(root, manifest, tools, capabilities, variables, { coordination });
+    if (coordination) {
+      const coordinationIncomplete = installCoordinationHooks(root, tools, { dryRun: true }).filter((entry) => entry.action !== "skip");
       if (coordinationIncomplete.length > 0) {
         throw new WorkspaceError("UPDATE_POSTCONDITION_FAILED", "Coordination Hook artifacts failed verification.", { files: coordinationIncomplete, remediation: "Run code-w update --coordination again after reviewing the reported files." });
       }
     }
+    const removedCoordinationIncomplete = removeCoordinationHooks(root, removedCoordinationTools, { dryRun: true }).filter((entry) => entry.action !== "skip");
+    if (removedCoordinationIncomplete.length > 0) {
+      throw new WorkspaceError("UPDATE_POSTCONDITION_FAILED", "Obsolete coordination Hook entries failed verification.", { files: removedCoordinationIncomplete, remediation: "Run code-w update again after reviewing the reported files." });
+    }
     const result = {
       language,
       tools: toolSelection,
-      coordination: options.coordination === true,
+      coordination,
       migration: migrationData(migration),
       obsoleteFiles,
       managedFiles,
@@ -141,6 +154,7 @@ function updateWorkspace(root, options = {}) {
     options.injectFailure?.("after-verify", result);
     const state = commitUpdateState(root, manifest, {
       tools,
+      coordination,
       removeLegacyWorkspaceLanguage: true,
     });
     options.injectFailure?.("after-state-save", state);

package/src/core/doctor.js

@@ -1,6 +1,7 @@
 const { CURRENT_CONFIG_VERSION, inspectConfigDomains, loadState } = require("./config");
 const { add, result } = require("./diagnostics");
 const { inspectManagedFiles } = require("./managed-files");
+const { installCoordinationHooks } = require("./task-coordination-managed");
 const { DEFAULT_WORKSPACE_LANGUAGE, workspaceGuide } = require("./language");
 const { inspectProjectPermissions } = require("./permissions");
 const { validateProjects } = require("./validation");
@@ -36,13 +37,17 @@ function doctorWorkspace(root, manifest, options = {}) {
     add(output, "error", "WORKSPACE_IDENTITY_MISSING", "Local workspace name and UUID are missing. Re-run `code-w init .` to generate them.");
   }
 
+  const state = loadState(root);
   const toolSelection = options.toolSelection || resolveWorkspaceTools({
     explicit: options.tools,
     state: loadState(root),
     manifestTools: manifest.tools,
   });
   const tools = toolSelection.tools;
-  const capabilities = options.capabilities || (inspection.monitor.valid && config.monitor?.enable ? ["monitor"] : []);
+  const capabilities = options.capabilities || [
+    ...(inspection.monitor.valid && config.monitor?.enable ? ["monitor"] : []),
+    ...(state?.coordination === true ? ["coordination"] : []),
+  ];
   if (inspection.monitor.valid && config.monitor?.enable && !tools.includes("codex")) {
     add(output, "error", "MONITOR_CODEX_REQUIRED", "Agent monitoring is enabled, but Codex is not one of the selected tools.");
   }
@@ -56,7 +61,7 @@ function doctorWorkspace(root, manifest, options = {}) {
       const managed = inspectManagedFiles(root, manifest, tools, capabilities, {
         WORKSPACE_LANGUAGE: language || DEFAULT_WORKSPACE_LANGUAGE,
         WORKSPACE_USER_GUIDE: workspaceGuide(language || DEFAULT_WORKSPACE_LANGUAGE),
-      });
+      }, { coordination: capabilities.includes("coordination") });
       for (const file of [...managed.managedOld, ...managed.replaceable]) {
         add(output, "error", "MANAGED_FILE_OUTDATED", `Managed file is not at the desired version: ${file}`);
       }
@@ -71,6 +76,21 @@ function doctorWorkspace(root, manifest, options = {}) {
   } catch (error) {
     add(output, "error", "MANAGED_FILE_MANIFEST_INVALID", error.message);
   }
+  if (capabilities.includes("coordination")) {
+    try {
+      const coordination = installCoordinationHooks(root, tools, { dryRun: true });
+      output.coordinationHooks = coordination;
+      for (const entry of coordination.filter((item) => item.action !== "skip")) {
+        add(output, "error", "TASK_HOOK_NOT_INSTALLED", `Coordination Hook is not installed for ${entry.tool}: ${entry.target}`, {
+          tool: entry.tool,
+          target: entry.target,
+          remediation: "Run code-w update --coordination and retry.",
+        });
+      }
+    } catch (error) {
+      add(output, "error", error.code || "TASK_HOOK_INSPECTION_FAILED", error.message, error.details || {});
+    }
+  }
   if (inspection.projects.valid && config.projects.length > 0) {
     try {
       output.permissionInspection = inspectProjectPermissions({ root, tools, projects: config.projects });
@@ -89,7 +109,6 @@ function doctorWorkspace(root, manifest, options = {}) {
     }
   }
 
-  const state = loadState(root);
   if (!options.allowIncompleteState) {
     if (!state || state.status !== "healthy") add(output, "error", "INIT_STATE_UNHEALTHY", "Local initialization state is missing or unhealthy.");
     else {

package/src/core/init.js

@@ -113,6 +113,7 @@ function installWorkspaceDependencies(root, options = {}) {
 
 function commitInitializationState(root, manifest, options = {}) {
   const current = loadState(root) || {};
+  const coordination = options.coordination === undefined ? current.coordination === true : options.coordination === true;
   const state = {
     ...current,
     schemaVersion: 2,
@@ -120,6 +121,7 @@ function commitInitializationState(root, manifest, options = {}) {
     appliedReleaseVersion: manifest.releaseVersion,
     appliedManifestSha256: sha256(fs.readFileSync(options.manifestFile || MANIFEST_FILE)),
     tools: options.tools || manifest.tools,
+    coordination,
   };
   delete state.workspaceLanguage;
   saveState(root, state);
@@ -140,6 +142,7 @@ function commitUpdateState(root, manifest, options = {}) {
     appliedReleaseVersion: manifest.releaseVersion,
     appliedManifestSha256: sha256(fs.readFileSync(options.manifestFile || MANIFEST_FILE)),
     ...(options.tools !== undefined ? { tools: options.tools } : {}),
+    ...(options.coordination !== undefined ? { coordination: options.coordination === true } : {}),
   };
   if (options.removeLegacyWorkspaceLanguage === true) delete state.workspaceLanguage;
   saveState(root, state);

package/src/core/initializer.js

@@ -11,6 +11,7 @@ const {
   projectConfigPath,
   ensureLocalIgnore,
   loadConfig,
+  loadState,
   normalizeConfig,
   resolveProjectConfigPath,
   saveConfig,
@@ -28,7 +29,7 @@ const {
 } = require("./init");
 const { applyPermissionPlan, permissionTargets, planPermissionChanges } = require("./permissions");
 const { installManagedFiles } = require("./managed-files");
-const { installCoordinationArtifacts } = require("./task-coordination-managed");
+const { coordinationHookTargets, installCoordinationHooks, removeCoordinationHooks } = require("./task-coordination-managed");
 const { DEFAULT_WORKSPACE_LANGUAGE, workspaceGuide } = require("./language");
 const { planWorkspaceMaintenance } = require("./migration");
 const { createFileTransaction } = require("./transaction");
@@ -144,12 +145,20 @@ async function initializeWorkspaceStages(rootInput, options = {}) {
     const core = installManagedFiles(root, manifest, options.tools, {
       force: options.force === true,
       capabilities,
+      coordination: options.coordination === true,
       variables: { WORKSPACE_LANGUAGE: language, WORKSPACE_USER_GUIDE: workspaceGuide(language) },
     });
+    const removedCoordination = options.previousCoordination === true
+      ? removeCoordinationHooks(root, (options.previousTools || []).filter((tool) => !options.tools.includes(tool)))
+      : [];
     const coordination = options.coordination === true
-      ? installCoordinationArtifacts(root, options.tools, { force: options.force === true })
+      ? installCoordinationHooks(root, options.tools, { force: options.force === true })
       : [];
-    return [...core, ...coordination.map((entry) => ({ ...entry, id: `task-coordination-${entry.tool}` }))];
+    return [
+      ...core,
+      ...removedCoordination.map((entry) => ({ ...entry, id: `task-coordination-remove-${entry.tool}` })),
+      ...coordination.map((entry) => ({ ...entry, id: `task-coordination-${entry.tool}` })),
+    ];
   });
 
   const localConfig = await stage("Prepare local workspace configuration", () => {
@@ -189,6 +198,7 @@ async function initializeWorkspaceStages(rootInput, options = {}) {
       manifestFile: options.manifestFile || MANIFEST_FILE,
       tools: options.tools,
       language,
+      coordination: options.coordination === true,
     })
   );
 
@@ -219,6 +229,15 @@ async function initializeWorkspaceStages(rootInput, options = {}) {
 
 async function initializeWorkspace(rootInput, options = {}) {
   const root = path.resolve(rootInput || ".");
+  const existingState = loadState(root);
+  const coordination = options.coordination === true || existingState?.coordination === true;
+  const previousTools = Array.isArray(existingState?.tools) ? existingState.tools : [];
+  const removedCoordinationTools = existingState?.coordination === true
+    ? previousTools.filter((tool) => !options.tools?.includes(tool))
+    : [];
+  const coordinationHookTools = coordination
+    ? [...new Set([...(options.tools || []), ...removedCoordinationTools])]
+    : removedCoordinationTools;
   const manifest = loadInitManifest(options.manifestFile || MANIFEST_FILE);
   const projectFile = fs.existsSync(configPath(root))
     ? resolveProjectConfigPath(root)
@@ -229,14 +248,20 @@ async function initializeWorkspace(rootInput, options = {}) {
     projectFile,
     path.join(root, ".gitignore"),
     path.join(root, ".codex", "config.toml"),
-    ...(options.coordination === true ? [path.join(root, ".codex", "task-coordination-hooks.json"), path.join(root, ".claude", "task-coordination-settings.json")] : []),
+    ...coordinationHookTargets(root, coordinationHookTools),
     ...permissionTargets(root, options.tools),
     ...manifest.managedFiles.map((entry) => path.join(root, entry.target)),
     ...OBSOLETE_ASSETS.map((target) => path.join(root, target)),
   ];
   const transaction = createFileTransaction(files);
   try {
-    const result = await initializeWorkspaceStages(root, { ...options, transaction });
+    const result = await initializeWorkspaceStages(root, {
+      ...options,
+      coordination,
+      previousCoordination: existingState?.coordination === true,
+      previousTools,
+      transaction,
+    });
     transaction.commit();
     return result;
   } catch (error) {

package/src/core/managed-files.js

@@ -8,6 +8,7 @@ const { atomicWrite, sha256 } = require("./fs");
 const { DEFAULT_WORKSPACE_LANGUAGE, workspaceGuide } = require("./language");
 const { CODEX_HOOKS_TARGET, composeHookContent } = require("./extension-artifacts");
 const { composeHookDocument } = require("./hooks");
+const { coordinationFragment, mergeHooks } = require("./task-coordination-managed");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 const ARTIFACTS_ROOT = path.join(PACKAGE_ROOT, "artifacts");
@@ -66,14 +67,34 @@ function hasExtensionHooks(state) {
   );
 }
 
-function desiredManagedContent(root, entry, variables, extensionState, includeCore = true) {
+function desiredManagedContent(root, entry, variables, extensionState, includeCore = true, options = {}) {
   if (entry.target !== CODEX_HOOKS_TARGET) return renderManagedContent(entry, variables);
   const target = path.join(root, entry.target);
-  if (extensionState === null && fs.existsSync(target)) return fs.readFileSync(target);
-  const base = includeCore ? renderManagedContent(entry, variables) : Buffer.from('{\n  "hooks": {}\n}\n');
-  const legacy = composeHookContent(base, extensionState || { extensions: {} });
+  if (extensionState === null && fs.existsSync(target) && options.coordination !== true) return fs.readFileSync(target);
+  let base;
+  const preserveExisting = options.coordination === true && fs.existsSync(target);
+  if (preserveExisting) {
+    let existing;
+    try { existing = JSON.parse(fs.readFileSync(target, "utf8")); }
+    catch (error) { throw new WorkspaceError("MANAGED_FILE_UNKNOWN", `Cannot parse managed Hook target: ${target}: ${error.message}`, { target }); }
+    base = includeCore
+      ? mergeHooks(existing, JSON.parse(renderManagedContent(entry, variables).toString("utf8")), "codex")
+      : existing;
+  } else {
+    base = includeCore ? renderManagedContent(entry, variables) : Buffer.from('{\n  "hooks": {}\n}\n');
+  }
+  if (preserveExisting) {
+    const withCoordination = mergeHooks(base, coordinationFragment("codex", root), "codex");
+    return Buffer.from(`${JSON.stringify(withCoordination, null, 2)}\n`);
+  }
+  const legacy = composeHookContent(
+    typeof base === "string" || Buffer.isBuffer(base) ? base : JSON.stringify(base),
+    extensionState || { extensions: {} }
+  );
   const composed = composeHookDocument(legacy, "codex", { extensions: {} }, extensionState || { extensions: {} });
-  return Buffer.from(`${JSON.stringify(composed, null, 2)}\n`);
+  if (options.coordination !== true) return Buffer.from(`${JSON.stringify(composed, null, 2)}\n`);
+  const withCoordination = mergeHooks(composed, coordinationFragment("codex", root), "codex");
+  return Buffer.from(`${JSON.stringify(withCoordination, null, 2)}\n`);
 }
 
 function resolveArtifact(relativePath) {
@@ -196,12 +217,19 @@ function previousInstalledSha(state, entry) {
   return previous?.installedSha256 || previous?.sha256 || null;
 }
 
-function classifyManagedFile(root, entry, state, variables = {}, extensionState, includeCore = true) {
+function classifyManagedFile(root, entry, state, variables = {}, extensionState, includeCore = true, options = {}) {
   const target = path.join(root, entry.target);
-  const desiredSha256 = sha256(desiredManagedContent(root, entry, variables, extensionState, includeCore));
+  const desiredSha256 = sha256(desiredManagedContent(root, entry, variables, extensionState, includeCore, options));
   if (!fs.existsSync(target)) return { state: "missing", target, sha256: null, desiredSha256 };
   const actualSha256 = sha256(fs.readFileSync(target));
   if (actualSha256 === desiredSha256) return { state: "current", target, sha256: actualSha256, desiredSha256 };
+  // Provider Hook documents are shared with the user. When coordination is
+  // enabled, the desired document is built by merging managed contributions
+  // into the current document, so arbitrary user entries must not be treated
+  // as an unknown managed-file overwrite.
+  if (entry.target === CODEX_HOOKS_TARGET && options.coordination === true) {
+    return { state: "replaceable", target, sha256: actualSha256, desiredSha256 };
+  }
   if (actualSha256 === previousInstalledSha(state, entry)) return { state: "managed-old", target, sha256: actualSha256, desiredSha256 };
   if ((entry.replaceable || []).some((accepted) => accepted.sha256 === actualSha256)) {
     return { state: "replaceable", target, sha256: actualSha256, desiredSha256 };
@@ -218,7 +246,7 @@ function inspectManagedFiles(root, manifest, tools, capabilities = [], variables
   if (hookEntry && (hasExtensionHooks(hooksState) || (hooksState === null && fs.existsSync(path.join(root, CODEX_HOOKS_TARGET))))) selected.add(hookEntry.id);
   const output = { current: [], managedOld: [], replaceable: [], missing: [], unknown: [], files: [] };
   for (const entry of manifest.managedFiles.filter((entry) => selected.has(entry.id))) {
-    const classified = classifyManagedFile(root, entry, state, variables, hooksState, coreSelected.has(entry.id));
+    const classified = classifyManagedFile(root, entry, state, variables, hooksState, coreSelected.has(entry.id), options);
     const key = classified.state === "managed-old" ? "managedOld" : classified.state;
     output[key].push(entry.target);
     output.files.push({
@@ -244,6 +272,19 @@ function planManagedFiles(root, manifest, tools, options = {}) {
   for (const entry of manifest.managedFiles) {
     if (!selected.has(entry.id)) {
       const previousSha = previousInstalledSha(state, entry);
+      if (entry.target === CODEX_HOOKS_TARGET && options.coordination === true) {
+        if (previousSha) {
+          plans.push({
+            entry,
+            target: path.join(root, entry.target),
+            action: "forget",
+            previous: null,
+            reason: "coordination-managed",
+            desiredSha256: null,
+          });
+        }
+        continue;
+      }
       if (!previousSha) continue;
       const target = path.join(root, entry.target);
       const exists = fs.existsSync(target);
@@ -261,7 +302,7 @@ function planManagedFiles(root, manifest, tools, options = {}) {
       });
       continue;
     }
-    const classified = classifyManagedFile(root, entry, state, options.variables, hooksState, coreSelected.has(entry.id));
+    const classified = classifyManagedFile(root, entry, state, options.variables, hooksState, coreSelected.has(entry.id), options);
     if (classified.state === "current") {
       plans.push({ entry, target: classified.target, action: "skip", previous: null, reason: "current", desiredSha256: classified.desiredSha256 });
       continue;
@@ -278,7 +319,7 @@ function planManagedFiles(root, manifest, tools, options = {}) {
       action: "write",
       reason: classified.state,
       previous: fs.existsSync(classified.target) ? fs.readFileSync(classified.target) : null,
-      content: desiredManagedContent(root, entry, options.variables, hooksState, coreSelected.has(entry.id)),
+      content: desiredManagedContent(root, entry, options.variables, hooksState, coreSelected.has(entry.id), options),
       desiredSha256: classified.desiredSha256,
     });
   }