@brainervirus/workit-core 2.4.0 → 2.6.0

package/src/core/doctor.ts

@@ -33,6 +33,11 @@ import {
   isWorkitPlugin,
 } from "./registration";
 import { readWorkspacesResult, resolveWorkspaceFrom } from "./workspaces";
+import {
+  CLAUDE_MARKETPLACE_NAME,
+  claudeWorkitInstalls,
+  type ClaudeWorkitInstall,
+} from "./host-install";
 import { validateCursorSkills, WORKIT_METHOD_SKILLS } from "./skill-manifests";
 import {
   classifyHostGeneration,
@@ -53,6 +58,7 @@ export type DoctorCheckId =
   | "runtime"
   | "versions"
   | "codex_pin"
+  | "claude_plugin"
   | "assets"
   | "launcher"
   | "utility"
@@ -1737,10 +1743,65 @@ const checkWorkspaceLock = (res: Resolved): DoctorCheck => {
   };
 };
 
+const CLAUDE_PLUGIN_PACKAGE = "@brainervirus/workit-claude-code";
+
+const versionBehind = (version: string, latest: string): boolean =>
+  version !== latest && semverAtLeast(latest, version);
+
+/**
+ * Claude Code installs the marketplace plugin as a snapshot of the published
+ * package (auto-update is off by default), so an install can lag the release.
+ * It warns only when a newer plugin version is actually published: a plugin
+ * older than this CLI is normal when no plugin payload changed since (the
+ * plugin is republished only when its own or its bundled sources change).
+ * The plugin keeps working; the fix is one native update. A `--plugin-dir`
+ * local pin is per-session, never recorded, and never checked here.
+ */
+const checkClaudePlugin = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
+  // Only installs Claude loads here: user scope, plus this project's.
+  const installs = claudeWorkitInstalls(res.home, res.env, res.cwd);
+  if (installs.length === 0)
+    return {
+      id: "claude_plugin",
+      status: "pass",
+      detail: "no Workit Claude Code plugin install recorded — skipping",
+    };
+  const fix = (install: ClaudeWorkitInstall) =>
+    `claude plugin marketplace update ${CLAUDE_MARKETPLACE_NAME} && ${
+      install.projectPath ? `cd ${JSON.stringify(install.projectPath)} && ` : ""
+    }claude plugin update ${install.id}${install.scope === "user" ? "" : ` --scope ${install.scope}`}`;
+  const latest = registryLatestVersion(res, CLAUDE_PLUGIN_PACKAGE);
+  const problems: string[] = [];
+  let repair: string | undefined;
+  for (const install of installs) {
+    const label = `${install.id} ${install.version ?? "(unknown version)"}${install.scope === "user" ? "" : ` (${install.scope} scope)`}`;
+    if (latest && install.version && versionBehind(install.version, latest)) {
+      problems.push(`stale_install: ${label} is behind published ${latest}`);
+      repair ??= fix(install);
+    }
+  }
+  const registryProbed = latest !== null && !res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
+  if (problems.length === 0)
+    return {
+      id: "claude_plugin",
+      status: "pass",
+      detail: `Claude Code plugin ${installs.map((i) => `${i.id} ${i.version ?? "?"}`).join(", ")} is current`,
+      registryProbed,
+    };
+  return {
+    id: "claude_plugin",
+    status: "warn",
+    detail: problems.join("; "),
+    fix: repair,
+    registryProbed,
+  };
+};
+
 const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
   checkRuntime,
   checkVersions,
   checkCodexPin,
+  checkClaudePlugin,
   checkAssets,
   checkLauncher,
   checkUtility,

package/src/core/external-action-effects.ts

@@ -57,6 +57,7 @@ import {
 import { normalizeChainSteps } from "./authority";
 import { resolveInside, run as coreRun } from "../core";
 import { hostingApiHostMatches, vcsCliIdentity, vcsConfig } from "./vcs-config";
+import { deleteRemoteBranch } from "../git/ops";
 import { assertProductWriteAllowed, currentWriterOwnsTask } from "./workers";
 import { sameDirectoryIdentity, TaskStore } from "./task-store";
 
@@ -2128,15 +2129,9 @@ export const executeConcreteExternalAction = async (
           outcome: "not_started",
         });
       const branch = request.payload.branch;
-      const result = run(root, [
-        "push",
-        `--force-with-lease=refs/heads/${branch}:${approvedTip}`,
-        "--delete",
-        target,
-        branch,
-      ]);
-      if (result.exitCode === 0) return success(null, null, { branch, deletedTip: approvedTip });
-      return /stale info|cannot lock ref|fetch first|non-fast-forward/i.test(result.stderr)
+      const result = deleteRemoteBranch(root, target, branch, approvedTip);
+      if (result.ok) return success(null, null, { branch, deletedTip: approvedTip });
+      return result.lease
         ? failure("capability_unavailable", "remote branch tip changed before deletion", {
             outcome: "not_started",
           })

package/src/core/host-install.ts

@@ -11,7 +11,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 
-export type HostId = "opencode" | "cursor" | "codex" | "pi";
+export type HostId = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
 
 /** A reviewed argv vector. Arguments are never composed into a shell string. */
 export type HostInstallCommand = {
@@ -89,6 +89,12 @@ export type HostInstallOptions = {
 
 const MARKETPLACE = "https://github.com/BrainerVirus/workit.git";
 const CODEX_MARKETPLACE_NAME = "workflow-toolkit";
+/** Claude Code reads the git-hosted marketplace at the repo root
+ * (`.claude-plugin/marketplace.json`, name `workit`); its entry installs the
+ * published npm package. */
+export const CLAUDE_MARKETPLACE_REPO = "BrainerVirus/workit";
+export const CLAUDE_MARKETPLACE_NAME = "workit";
+export const CLAUDE_PLUGIN_ID = `workit@${CLAUDE_MARKETPLACE_NAME}`;
 const validPackageVersion = (value: string): boolean =>
   value === "latest" || /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 
@@ -224,6 +230,109 @@ export const isCodexWorkitInstalled = (
   return false;
 };
 
+/** Claude Code's config root (`CLAUDE_CONFIG_DIR`, default `~/.claude`). */
+export const claudeConfigDir = (home: string, env: NodeJS.ProcessEnv = process.env): string =>
+  env.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude");
+
+export type ClaudeInstallScope = "user" | "project" | "local";
+
+export type ClaudeWorkitInstall = {
+  id: string;
+  version: string | null;
+  installPath: string;
+  scope: ClaudeInstallScope;
+  /** The project a project/local-scope install belongs to; null for user scope. */
+  projectPath: string | null;
+};
+
+const CLAUDE_SCOPES = new Set<string>(["user", "project", "local"]);
+
+/** A project/local install applies to `cwd` when cwd is inside its project. */
+const appliesTo = (install: ClaudeWorkitInstall, cwd: string | null): boolean => {
+  if (install.scope === "user") return true;
+  if (cwd === null || install.projectPath === null) return false;
+  const relative = path.relative(path.resolve(install.projectPath), path.resolve(cwd));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+const isCanonicalClaudePlugin = (root: string): boolean => {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(path.join(root, ".claude-plugin", "plugin.json"), "utf8"),
+    ) as { name?: string; repository?: string | { url?: string } };
+    const repository =
+      typeof manifest.repository === "string" ? manifest.repository : manifest.repository?.url;
+    return (
+      manifest.name === "workit" &&
+      repository?.replace(/\.git$/, "").toLowerCase() === "https://github.com/brainervirus/workit"
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Workit installs recorded in Claude Code's plugin registry
+ * (`<config>/plugins/installed_plugins.json`, v2: `{plugins: {"name@market":
+ * [{installPath, version}]}}`). Only entries whose install directory carries
+ * the canonical Workit manifest count, whatever marketplace they came from.
+ * Only installs that apply here count: user scope always, project/local
+ * scope only when `cwd` is inside the recorded project (`cwd: null` keeps
+ * user scope only). A `--plugin-dir` pin is per-session and never recorded.
+ */
+export const claudeWorkitInstalls = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string | null = process.cwd(),
+): ClaudeWorkitInstall[] => {
+  const file = path.join(claudeConfigDir(home, env), "plugins", "installed_plugins.json");
+  let registry: unknown;
+  try {
+    registry = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const plugins =
+    registry && typeof registry === "object" && "plugins" in registry ? registry.plugins : null;
+  if (!plugins || typeof plugins !== "object") return [];
+  const found: ClaudeWorkitInstall[] = [];
+  for (const [id, entries] of Object.entries(plugins as Record<string, unknown>)) {
+    if (!id.startsWith("workit@") || !Array.isArray(entries)) continue;
+    for (const entry of entries as Array<{
+      installPath?: unknown;
+      version?: unknown;
+      scope?: unknown;
+      projectPath?: unknown;
+    }>) {
+      if (typeof entry?.installPath !== "string" || !isCanonicalClaudePlugin(entry.installPath))
+        continue;
+      // Older registries omit scope; Claude's default install scope is user.
+      const scope = entry.scope === undefined ? "user" : String(entry.scope);
+      if (!CLAUDE_SCOPES.has(scope)) continue; // e.g. managed: not ours to change
+      const install: ClaudeWorkitInstall = {
+        id,
+        installPath: entry.installPath,
+        version:
+          typeof entry.version === "string" && /^\d+\.\d+\.\d+/.test(entry.version)
+            ? entry.version
+            : null,
+        scope: scope as ClaudeInstallScope,
+        projectPath:
+          scope !== "user" && typeof entry.projectPath === "string" ? entry.projectPath : null,
+      };
+      if (appliesTo(install, cwd)) found.push(install);
+    }
+  }
+  return found;
+};
+
+/** A Workit install Claude Code loads for this user (any project). */
+export const isClaudeWorkitInstalled = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string | null = process.cwd(),
+): boolean => claudeWorkitInstalls(home, env, cwd).length > 0;
+
 export function installedHostApp(
   host: HostId,
   home: string,
@@ -297,6 +406,39 @@ export function planHostInstall(
       },
     ];
   }
+  if (host === "claude-code") {
+    if (!upgrading && isClaudeWorkitInstalled(home, env, null)) return [];
+    const base = hostCommand("claude", [], { home, cwd, env });
+    return [
+      nodePrerequisite({ home, cwd, env }),
+      {
+        ...base,
+        args: [...base.args, "plugin", "marketplace", "list", "--json"],
+        purpose: "Check whether the Workit Claude Code marketplace is already registered",
+      },
+      upgrading
+        ? {
+            ...base,
+            args: [...base.args, "plugin", "marketplace", "update", CLAUDE_MARKETPLACE_NAME],
+            purpose: "Refresh the Workit Claude Code marketplace",
+          }
+        : {
+            ...base,
+            args: [...base.args, "plugin", "marketplace", "add", CLAUDE_MARKETPLACE_REPO],
+            purpose: "Register the Workit Claude Code marketplace",
+            skipWhenOutputIncludes: `"name": "${CLAUDE_MARKETPLACE_NAME}"`,
+          },
+      {
+        ...base,
+        args: upgrading
+          ? [...base.args, "plugin", "update", CLAUDE_PLUGIN_ID]
+          : [...base.args, "plugin", "install", CLAUDE_PLUGIN_ID, "--scope", "user"],
+        purpose: upgrading
+          ? "Update the Workit Claude Code plugin"
+          : "Install the Workit Claude Code plugin",
+      },
+    ];
+  }
   if (host === "pi") {
     if (!upgrading && isPiWorkitInstalled(home, env)) return [];
     const base = hostCommand("pi", [], { home, cwd, env });
@@ -440,6 +582,7 @@ export function runHostCommand(
       const env: NodeJS.ProcessEnv = { ...process.env, ...context.env, HOME: home };
       env.CODEX_HOME = context.env?.CODEX_HOME ?? path.join(home, ".codex");
       env.PI_CODING_AGENT_DIR = context.env?.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent");
+      env.CLAUDE_CONFIG_DIR = context.env?.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude");
       env.XDG_CONFIG_HOME = context.env?.XDG_CONFIG_HOME ?? path.join(home, ".config");
       return env;
     })(),

package/src/core/pr-create.ts

@@ -5,21 +5,13 @@ import { pathToFileURL } from "node:url";
 import { hostingApiHostMatches, vcsCliIdentity, vcsConfig } from "./vcs-config";
 export { hostingApiHostMatches } from "./vcs-config";
 import { resolveBranchPolicyFor } from "./branch";
+import { buildBody, parseGhIssue, parseGhRepo } from "../forge/pr-body";
 
 // Port of scripts/pr-create.sh — build MR/PR body issue linking + create via glab/gh.
 // Hosted creation is enabled (decision ae03c569): every create path pre-binds
 // the approved source SHA through WORKIT_EXPECTED_* and the shared executor
 // post-verifies the provider PR head before reporting success. The residual
 // non-atomic source-SHA race is accepted.
-function parseGhRepo(remote: string): string | null {
-  remote = (remote || "").trim().replace(/\/+$/, "");
-  if (!remote) return null;
-  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
-  if (remote.includes(":")) remote = remote.split(":").pop() ?? ""; // drop git@host part (scp-style URL)
-  const parts = remote.split("/").filter(Boolean);
-  return parts.length >= 2 ? parts.slice(-2).join("/") : null;
-}
-
 const remoteRepoPath = (
   remote: string,
 ): { host: string; path: string; protocol: string } | null => {
@@ -63,68 +55,6 @@ const cliRepository = (
   return host === "gitlab.com" ? parsed.path : `https://${host}/${parsed.path}`;
 };
 
-function parseGhIssue(value: string): string {
-  const m = /issues\/(\d+)/.exec(value);
-  return m ? m[1] : String(value).trim().replace(/^#/, "");
-}
-
-// RL-03/CA-25/AR-08: a branch-derived numeric issue id must be a bare number at
-// a segment or dash boundary — and never part of a date segment. Year-first
-// (feature/2024-01-15/x) and day-first (feature/15-01-2024/x) dates are both
-// skipped — a complete date anywhere in a segment (release-2024-01-15,
-// v2-2024-01-15-fix) — so no date digit ever closes an issue. Deliberate
-// numeric issue branches (feature/42-title, feature/2024-fix) keep linking.
-function deriveGhIssueFromBranch(branch: string): string {
-  for (const segment of branch.split("/")) {
-    if (/^\d{4}-\d/.test(segment)) continue; // year-first date-like segment (incl. year-month)
-    if (/\d{4}-\d{1,2}-\d{1,2}/.test(segment)) continue; // complete year-first date anywhere
-    if (/\d{1,2}-\d{1,2}-\d{4}/.test(segment)) continue; // complete day-first date anywhere
-    const m = /(?:^|-)(\d+)(?:-|$)/.exec(segment);
-    if (m) return m[1];
-  }
-  return "";
-}
-
-function buildBody(
-  body: string,
-  branch: string,
-  linkIssues: boolean,
-  baseUrl: string,
-  ytIssue: string,
-  ghLinkOnPr: boolean,
-  ghIssue: string,
-  ghRelation: string,
-  ghRepo: string | null,
-): string {
-  let line: string | null = null;
-  if (linkIssues) {
-    let issue = ytIssue;
-    if (!issue && branch) {
-      // anchored prefix + \b boundary, 3+ digits so version-like tokens (POSTGRES-16, HTTP-3) never link
-      const m = /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch);
-      if (m) issue = m[1];
-    }
-    if (issue && baseUrl) line = `Related to: ${baseUrl.replace(/\/+$/, "")}/issue/${issue}`;
-  } else if (ghLinkOnPr) {
-    let issue = parseGhIssue(ghIssue);
-    if (!issue && branch) {
-      // pure-number issue id (feature/42-title -> 42); digits must be followed by a dash or end-of-string
-      // so version tokens (release/1.2.3, backport/8.0.1, lodash-4.17.21, 2024.1) never link
-      issue = deriveGhIssueFromBranch(branch);
-    }
-    if (issue) {
-      if (ghRelation === "related") {
-        line = `Related to #${issue}`;
-        if (ghRepo) line += ` — https://github.com/${ghRepo}/issues/${issue}`;
-      } else {
-        line = `Closes #${issue}`;
-      }
-    }
-  }
-  if (line === null) return body;
-  return body ? `${body}\n\n${line}` : line;
-}
-
 const truthy = (v: string | undefined): boolean =>
   ["1", "true", "yes"].includes(String(v ?? "").toLowerCase());
 
@@ -714,4 +644,5 @@ export function mergePr(
   };
 }
 
+// Moved to forge/pr-body.ts (S11); re-exported for the managed action path until S16.
 export { buildBody, parseGhRepo, parseGhIssue };

package/src/core/setup.ts

@@ -52,6 +52,8 @@ import { writeFileExclusive } from "./safe-write";
 import {
   isCodexWorkitInstalled,
   isPiWorkitInstalled,
+  isClaudeWorkitInstalled,
+  claudeConfigDir,
   planHostInstall,
   runHostInstall,
   type HostCommandRunner,
@@ -385,25 +387,27 @@ export function buildSetupPreview(
           mutations.push({ type: "install-adapter", platform, path: paths.cursorPluginDir });
           mutations.push({ type: "register-platform", platform, path: paths.cursorSettings });
           mutations.push({ type: "register-platform", platform, path: paths.cursorMcp });
-        } else if (platform === "codex" || platform === "pi") {
+        } else if (platform === "codex" || platform === "pi" || platform === "claude-code") {
           const commands = planHostInstall(platform, { home: paths.home, cwd: paths.cwd, env });
           if (commands.length > 0) {
             mutations.push({
               type: "install-host",
               platform,
               path:
-                platform === "codex"
-                  ? path.join(
-                      env.CODEX_HOME ?? path.join(paths.home, ".codex"),
-                      "plugins",
-                      "cache",
-                      "workflow-toolkit",
-                      "workit",
-                    )
-                  : path.join(
-                      env.PI_CODING_AGENT_DIR ?? path.join(paths.home, ".pi", "agent"),
-                      "settings.json",
-                    ),
+                platform === "claude-code"
+                  ? claudeInstallRecord(paths.home, env)
+                  : platform === "codex"
+                    ? path.join(
+                        env.CODEX_HOME ?? path.join(paths.home, ".codex"),
+                        "plugins",
+                        "cache",
+                        "workflow-toolkit",
+                        "workit",
+                      )
+                    : path.join(
+                        env.PI_CODING_AGENT_DIR ?? path.join(paths.home, ".pi", "agent"),
+                        "settings.json",
+                      ),
               commands,
             });
           }
@@ -446,6 +450,10 @@ export function buildSetupPreview(
 // Apply (Task 14: WZ-09, WZ-10, WZ-13-WZ-15; CA-08, CA-13, CA-14, CA-31).
 // ---------------------------------------------------------------------------
 
+/** The Claude Code plugin registry a Workit install is recorded in. */
+const claudeInstallRecord = (home: string, env: NodeJS.ProcessEnv): string =>
+  path.join(claudeConfigDir(home, env), "plugins", "installed_plugins.json");
+
 export type Platform = "opencode" | "cursor";
 
 export type SetupResultStatus = "Installed" | "Configured" | "Skipped" | "Failed";
@@ -1250,7 +1258,9 @@ export function applySetupPreview(
                   res.env.PI_CODING_AGENT_DIR ?? path.join(res.home, ".pi", "agent"),
                   "settings.json",
                 )
-              : "";
+              : mutation.platform === "claude-code"
+                ? claudeInstallRecord(res.home, res.env)
+                : "";
       if (mutation.path !== expectedPath) {
         entries.push({
           platform: mutation.platform,
@@ -1292,7 +1302,9 @@ export function applySetupPreview(
           ? isCodexWorkitInstalled(res.home, res.env)
           : mutation.platform === "pi"
             ? isPiWorkitInstalled(res.home, res.env)
-            : true;
+            : mutation.platform === "claude-code"
+              ? isClaudeWorkitInstalled(res.home, res.env, null)
+              : true;
       if (!verified) {
         entries.push({
           platform: mutation.platform,

package/src/core/support-matrix.ts

@@ -16,5 +16,9 @@ export const SUPPORT_MATRIX = {
   // an installed CLI drifts ahead so a fresh install never silently outruns
   // the qualification pin.
   codex: { cli: "0.153.4", desktopPackage: "26.901.20858", bundledCodexCli: "0.153.0-alpha.5" },
+  // Claude Code is a qualification host too: CI runs `claude plugin validate
+  // --strict` with exactly this CLI, and the hook output schema fixture
+  // (test/fixtures/claude-code-schemas) was transcribed from this binary.
+  claudeCode: { cli: "2.1.288" },
   os: ["ubuntu-latest", "macos-latest", "windows-latest"],
 } as const;

package/src/core/uninstall.ts

@@ -10,12 +10,28 @@ import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "n
 import os from "node:os";
 import path from "node:path";
 import { isWorkitPlugin } from "./registration";
+import {
+  claudeWorkitInstalls,
+  findHostExecutable,
+  runHostCommand,
+  type HostCommandRunner,
+} from "./host-install";
 
-export type UninstallHost = "opencode" | "cursor" | "codex" | "pi";
+export type UninstallHost = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
 
 export type UninstallAction =
   | { kind: "edit-json-remove"; path: string; detail: string }
-  | { kind: "remove-dir"; path: string; detail: string };
+  | { kind: "remove-dir"; path: string; detail: string }
+  /** A host-native uninstall (Claude Code owns its plugin cache and registry). */
+  | {
+      kind: "host-command";
+      path: string;
+      detail: string;
+      command: "claude";
+      args: string[];
+      /** The project a project/local-scope uninstall must run from; null for user scope. */
+      cwd: string | null;
+    };
 
 export type UninstallHostPlan = {
   host: UninstallHost;
@@ -49,6 +65,10 @@ export type UninstallPaths = {
   cursorSettings?: string;
   cursorMcp?: string;
   cursorPluginDir?: string;
+  /** Injectable host-command runner for host-native uninstall actions. */
+  runHostCommand?: HostCommandRunner;
+  /** Project directory for Claude Code project/local-scope installs (default: process cwd). */
+  cwd?: string;
 };
 
 type ResolvedUninstall = {
@@ -321,7 +341,32 @@ export function planUninstall(paths: UninstallPaths = {}): UninstallPlan {
       : [],
   };
 
-  return { hosts: [opencode, cursor, codex, pi] };
+  // Claude Code: one native `claude plugin uninstall <id> --scope <scope>`
+  // per recorded Workit install that applies here (user scope, plus this
+  // project's project/local scope, run from that project). A --plugin-dir
+  // pin is never recorded.
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const claudeInstalls = claudeWorkitInstalls(
+    home,
+    paths.env ?? process.env,
+    paths.cwd ?? process.cwd(),
+  );
+  const claude: UninstallHostPlan = {
+    host: "claude-code",
+    installed: claudeInstalls.length > 0,
+    actions: claudeInstalls.map((install) => ({
+      kind: "host-command" as const,
+      path: install.installPath,
+      detail: `claude plugin uninstall ${install.id} --scope ${install.scope}${
+        install.projectPath ? ` (in ${install.projectPath})` : ""
+      }`,
+      command: "claude" as const,
+      args: ["plugin", "uninstall", install.id, "--scope", install.scope],
+      cwd: install.projectPath,
+    })),
+  };
+
+  return { hosts: [opencode, cursor, codex, pi, claude] };
 }
 
 // CA-14 traversal guard: rm -rf is permitted ONLY on the exact resolved
@@ -390,6 +435,60 @@ const applyEditJsonRemove = (
   return { status: "removed" };
 };
 
+const CLAUDE_PLUGIN_ID = /^workit@[A-Za-z0-9._-]+$/;
+
+/** Runs a reviewed `claude plugin uninstall workit@<marketplace>`; any other
+ *  argv is refused, so a tampered plan cannot run an arbitrary command. */
+const applyClaudeUninstall = (
+  action: Extract<UninstallAction, { kind: "host-command" }>,
+  paths: UninstallPaths,
+): { status: UninstallResultStatus; detail?: string } => {
+  const [verb, sub, id, flag, scope, ...rest] = action.args;
+  const projectScoped = scope === "project" || scope === "local";
+  if (
+    action.command !== "claude" ||
+    verb !== "plugin" ||
+    sub !== "uninstall" ||
+    !CLAUDE_PLUGIN_ID.test(id ?? "") ||
+    flag !== "--scope" ||
+    !(scope === "user" || projectScoped) ||
+    rest.length > 0 ||
+    // user scope runs anywhere; project/local only from their project.
+    (projectScoped ? typeof action.cwd !== "string" : action.cwd !== null)
+  )
+    return {
+      status: "failed",
+      detail: `refusing unreviewed host command: ${action.args.join(" ")}`,
+    };
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const env = paths.env ?? process.env;
+  const recorded = claudeWorkitInstalls(home, env, action.cwd).some(
+    (install) =>
+      install.id === id &&
+      install.scope === scope &&
+      (install.projectPath === null
+        ? action.cwd === null
+        : path.resolve(install.projectPath) === path.resolve(action.cwd ?? "")),
+  );
+  if (!recorded)
+    return { status: "skipped", detail: `${id} (${scope} scope) is no longer installed` };
+  const executable = findHostExecutable("claude", { home, env });
+  if (!executable && !paths.runHostCommand)
+    return { status: "failed", detail: "claude executable was not found on PATH" };
+  const step = {
+    command: executable ?? "claude",
+    args: action.args,
+    ...(action.cwd === null ? {} : { cwd: action.cwd }),
+    purpose: `Uninstall the Workit Claude Code plugin ${id} (${scope} scope)`,
+  };
+  const result = paths.runHostCommand
+    ? paths.runHostCommand(step)
+    : runHostCommand(step, { home, env });
+  return result.exitCode === 0
+    ? { status: "removed", detail: action.detail }
+    : { status: "failed", detail: result.stderr || `exit ${result.exitCode}` };
+};
+
 /** Applies ONLY the reviewed plan actions with the given path options. Each
  *  planned action yields exactly one result entry; malformed host JSON fails
  *  its own action untouched while the remaining actions proceed (CA-13). */
@@ -400,7 +499,11 @@ export function applyUninstall(plan: UninstallPlan, paths: UninstallPaths = {}):
     for (const action of hostPlan.actions) {
       let status: UninstallResultStatus;
       let detail: string | undefined;
-      if (action.kind === "remove-dir") {
+      if (action.kind === "host-command") {
+        const outcome = applyClaudeUninstall(action, paths);
+        status = outcome.status;
+        detail = outcome.detail;
+      } else if (action.kind === "remove-dir") {
         // Resolve before comparing so ".."/symlink tricks can never widen the rm.
         const resolved = path.resolve(action.path);
         const allowed =

package/src/forge/exec.ts

@@ -179,3 +179,43 @@ export function apiText(
   if (run.status !== 0) return cliFailure(bin, apiHost, run, what, timeoutMs);
   return { ok: true, data: run.stdout };
 }
+
+/**
+ * A forge write (create, merge, retarget). Like apiJson, plus: an HTTP 409 or
+ * a head-moved/SHA-mismatch message is `blocked` (`head_moved`), and 405/406/
+ * 422 refusals are `blocked` with the forge's own reason, so a refused
+ * mutation never reads as a transient failure.
+ */
+export function apiWrite<T>(
+  runner: ForgeRunner,
+  bin: CliBin,
+  apiHost: string,
+  args: readonly string[],
+  what: string,
+  timeoutMs: number = FORGE_TIMEOUTS.api,
+): ForgeResult<T> {
+  const run = runner(bin, args, { timeoutMs });
+  if (run.status !== 0) {
+    const text = redactText(`${run.stderr}\n${run.stdout}`).trim();
+    const reason = (text.split(/\r?\n/u).find((value) => value.trim()) ?? "").slice(0, 200);
+    if (
+      !run.missing &&
+      !run.timedOut &&
+      /\b409\b|head branch was modified|sha does not match|sha.*mismatch/iu.test(text)
+    )
+      return failure(
+        "blocked",
+        `head_moved: ${what} refused because the head changed (${reason})`,
+        "workit pr status  # re-check the new head, then verify it again",
+      );
+    if (!run.missing && !run.timedOut && /\b(405|406|422)\b/u.test(text))
+      return failure("blocked", `${what} refused by the forge: ${reason}`);
+    return cliFailure(bin, apiHost, run, what, timeoutMs);
+  }
+  if (!run.stdout.trim()) return { ok: true, data: {} as T };
+  try {
+    return { ok: true, data: JSON.parse(run.stdout) as T };
+  } catch {
+    return failure("failed", `${bin} api ${what} returned invalid JSON`);
+  }
+}