deuk-agent-flow 4.2.7 → 5.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deuk-agent-flow",
-  "version": "4.2.7",
+  "version": "5.0.4",
   "description": "Keep AI coding work from vanishing between chats: repo-owned tickets, scope, verification, and memory for AGENTS.md-powered agents.",
   "keywords": [
     "agents-md",
@@ -22,73 +22,85 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/joygram/DeukAgentFlow.git"
+    "url": "git+https://github.com/joygram/DeukAgentFlow.git"
   },
   "bugs": {
     "url": "https://github.com/joygram/DeukAgentFlow/issues"
   },
   "homepage": "https://github.com/joygram/DeukAgentFlow#readme",
   "files": [
+    "LICENSE",
     "bin/**/*",
     "core-rules/**/*",
     "docs/architecture.md",
     "docs/architecture.ko.md",
+    "docs/badges/**/*",
     "docs/how-it-works.md",
     "docs/how-it-works.ko.md",
     "docs/principles.md",
     "docs/principles.ko.md",
-    "docs/npm-publish-guide.ko.md",
     "docs/usage-guide.ko.md",
     "docs/assets/**/*",
-    "NOTICE.md",
+    "bundled/**/*",
     "templates/**/*",
-    "scripts/cli.mjs",
-    "scripts/cli-args.mjs",
-    "scripts/cli-usage-commands.mjs",
-    "scripts/cli-init-commands.mjs",
-    "scripts/cli-init-logic.mjs",
-    "scripts/cli-prompts.mjs",
-    "scripts/cli-rule-compiler.mjs",
-    "scripts/cli-skill-commands.mjs",
-    "scripts/cli-telemetry-commands.mjs",
-    "scripts/cli-ticket-command-shared.mjs",
-    "scripts/cli-ticket-commands.mjs",
-    "scripts/cli-ticket-index.mjs",
-    "scripts/cli-ticket-migration.mjs",
-    "scripts/cli-ticket-parser.mjs",
-    "scripts/cli-utils.mjs",
-    "scripts/lint-md.mjs",
-    "scripts/lint-rules.mjs",
-    "scripts/merge-logic.mjs",
-    "scripts/plan-parser.mjs",
-    "scripts/publish-dual-npm.mjs",
-    "scripts/smoke-npm-local.mjs",
-    "scripts/smoke-npm-docker.mjs",
-    "scripts/update-download-badge.mjs",
+    "scripts/bundle-vscode-vsix.ts",
+    "scripts/cli.ts",
+    "scripts/cli-args.ts",
+    "scripts/cli-context-commands.ts",
+    "scripts/cli-init-claude.ts",
+    "scripts/cli-init-commands.ts",
+    "scripts/cli-init-core.ts",
+    "scripts/cli-init-instructions.ts",
+    "scripts/cli-init-logic.ts",
+    "scripts/cli-init-migrate.ts",
+    "scripts/cli-init-workspace.ts",
+    "scripts/cli-locales.ts",
+    "scripts/cli-prompts.ts",
+    "scripts/cli-rule-compiler.ts",
+    "scripts/cli-skill-commands.ts",
+    "scripts/cli-telemetry-commands.ts",
+    "scripts/cli-ticket-command-shared.ts",
+    "scripts/cli-ticket-commands.ts",
+    "scripts/cli-ticket-docmeta.ts",
+    "scripts/cli-ticket-document.ts",
+    "scripts/cli-ticket-evidence.ts",
+    "scripts/cli-ticket-home.ts",
+    "scripts/cli-ticket-index.ts",
+    "scripts/cli-ticket-migration.ts",
+    "scripts/cli-ticket-parser.ts",
+    "scripts/cli-ticket-scan.ts",
+    "scripts/cli-ticket-surface.ts",
+    "scripts/cli-usage-commands.ts",
+    "scripts/cli-utils.ts",
+    "scripts/lint-md.ts",
+    "scripts/lint-rules.ts",
+    "scripts/merge-logic.ts",
+    "scripts/plan-parser.ts",
+    "scripts/ticket-machine.ts",
+    "scripts/ticket-workflow.ts",
+    "scripts/oss-prepack.js",
+    "scripts/out/**/*",
     "README.md",
     "README.ko.md",
     "CHANGELOG.md",
     "CHANGELOG.ko.md"
   ],
   "scripts": {
-    "bump": "commit-and-tag-version",
-    "bump:patch": "commit-and-tag-version -r patch",
-    "bump:minor": "commit-and-tag-version -r minor",
-    "bump:major": "commit-and-tag-version -r major",
-    "merge:dry": "node scripts/cli.mjs merge --dry-run --cwd .. --agents skip",
-    "lint:md": "node scripts/lint-md.mjs",
-    "test": "node --test scripts/tests/*.test.mjs",
-    "sync:oss": "node scripts/sync-oss.mjs",
-    "publish": "node scripts/publish-dual-npm.mjs",
-    "publish:dry": "node scripts/publish-dual-npm.mjs --dry-run",
-    "smoke:npm:local": "node scripts/smoke-npm-local.mjs",
-    "smoke:npm:docker": "node scripts/smoke-npm-docker.mjs",
-    "publish:bootstrap": "node scripts/publish-dual-npm.mjs --alias-only",
-    "publish:bootstrap:dry": "node scripts/publish-dual-npm.mjs --alias-only --dry-run",
-    "badge:downloads": "node scripts/update-download-badge.mjs"
+    "dev:install": "npx tsc -p tsconfig.scripts.json && node scripts/out/scripts/dev-install.js",
+    "dev:install:no-bump": "npx tsc -p tsconfig.scripts.json && node scripts/out/scripts/dev-install.js --no-bump",
+    "build:vscode": "npx tsc -p tsconfig.scripts.json && node scripts/out/scripts/bundle-vscode-vsix.js",
+    "prepack": "node scripts/oss-prepack.js",
+    "install:vscode": "node scripts/out/scripts/install-vscode-vsix.js --all",
+    "install:vscode:desktop": "node scripts/out/scripts/install-vscode-vsix.js --desktop",
+    "install:vscode:server": "node scripts/out/scripts/install-vscode-vsix.js --server",
+    "lint:md": "node scripts/out/scripts/lint-md.js",
+    "publish": "npm publish --access public",
+    "publish:dry": "npm publish --access public --dry-run",
+    "smoke:npm:local": "node scripts/out/scripts/smoke-npm-local.js",
+    "smoke:npm:docker": "node scripts/out/scripts/smoke-npm-docker.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "bin": {
     "deuk-agent-flow": "./bin/deuk-agent-flow.js",
@@ -97,10 +109,13 @@
     "deukagentrule": "./bin/deuk-agent-rule.js"
   },
   "devDependencies": {
-    "commit-and-tag-version": "^12.7.1"
+    "typescript": "^6.0.3",
+    "@types/node": "^25.9.3"
   },
   "dependencies": {
     "ejs": "^5.0.2",
+    "xstate": "^5.32.1",
     "yaml": "^2.8.3"
-  }
+  },
+  "type": "module"
 }

package/scripts/bundle-vscode-vsix.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Packs vscode-extension into bundled/deuk-agent-flow.vsix for the npm tarball.
+ * Temporarily sets the extension package.json version to the root package version.
+ */
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+import { CliOpts, makePath, resolvePackageRoot } from "./cli-utils.js";
+
+const root = resolvePackageRoot({ fromUrl: import.meta.url });
+const extDir = makePath(root, 'vscode-extension');
+const extPkgPath = makePath(extDir, 'package.json');
+const bundledDir = makePath(root, 'bundled');
+const vsixPath = makePath(bundledDir, 'deuk-agent-flow.vsix');
+const installAfterBundle = process.argv.includes('--install') || process.env.DEUK_AGENT_FLOW_INSTALL_VSIX === '1';
+const skipCompile = process.argv.includes('--skip-compile') || process.env.DEUK_AGENT_FLOW_SKIP_COMPILE === '1';
+
+const rootPkg = JSON.parse(fs.readFileSync(makePath(root, 'package.json'), 'utf8'));
+const extPkg = JSON.parse(fs.readFileSync(extPkgPath, 'utf8'));
+const savedPrepublish = extPkg.scripts?.['vscode:prepublish'];
+extPkg.version = rootPkg.version;
+extPkg.scripts = {
+  ...extPkg.scripts,
+  'vscode:prepublish': 'tsc -p ./',
+};
+fs.writeFileSync(extPkgPath, JSON.stringify(extPkg, null, 2) + '\n');
+
+try {
+  if (!fs.existsSync(bundledDir)) fs.mkdirSync(bundledDir, { recursive: true });
+  execSync('npm install --no-audit --no-fund --loglevel=silent', { cwd: extDir, stdio: 'inherit', shell: true } as any);
+  if (!skipCompile) {
+    execSync('npm run compile', { cwd: extDir, stdio: 'inherit' } as any);
+  }
+  const vsceBin = makePath(extDir, 'node_modules', '.bin', process.platform === 'win32' ? 'vsce.cmd' : 'vsce');
+  if (!fs.existsSync(vsceBin)) {
+    console.error('[deuk-agent-flow] @vscode/vsce missing. Run npm install in vscode-extension.');
+    process.exit(1);
+  }
+  const q = (s) => (s.includes(' ') ? `"${s.replace(/"/g, '\\"')}"` : s);
+  execSync(`${q(vsceBin)} package --no-dependencies --out ${q(vsixPath)}`, { cwd: extDir, input: 'y\n', stdio: ['pipe', 'inherit', 'inherit'], shell: true } as any);
+  if (!fs.existsSync(vsixPath)) {
+    console.error('[deuk-agent-flow] bundle-vscode: expected VSIX missing:', vsixPath);
+    process.exit(1);
+  }
+  console.log('[deuk-agent-flow] bundled VS Code extension:', vsixPath);
+  if (installAfterBundle) {
+    if (process.platform === 'win32') {
+      // Windows node 컨텍스트: WSL bash 스크립트로 WSL 파일시스템에 직접 설치
+      const wslScript = execSync(`wsl.exe wslpath -u "${root.replace(/\\/g, '/')}/scripts/install-vsix-wsl.sh"`, { encoding: 'utf8', shell: true } as any).toString().trim();
+      execSync(`wsl.exe bash "${wslScript}"`, { stdio: 'inherit', shell: true } as any);
+    } else {
+      execSync('node scripts/out/scripts/install-vscode-vsix.js --all', { cwd: root, stdio: 'inherit', shell: true } as any);
+    }
+  }
+} finally {
+  // #version-sync: keep the extension package.json version pinned to the root version
+  // (do NOT restore savedVer) so vscode-extension/package.json auto-tracks the root on
+  // every bundle instead of drifting back to a stale value. Only prepublish is temporary.
+  extPkg.version = rootPkg.version;
+  if (savedPrepublish === undefined) {
+    delete extPkg.scripts['vscode:prepublish'];
+  } else {
+    extPkg.scripts['vscode:prepublish'] = savedPrepublish;
+  }
+  fs.writeFileSync(extPkgPath, JSON.stringify(extPkg, null, 2) + '\n');
+}

package/scripts/{cli-args.mjs → cli-args.ts}

@@ -1,12 +1,35 @@
+// Parse a phase token from --phase/--to. Accepts "2", "phase2", "phase 2", "end", "start".
+// Returns NaN when no digit is present and not a known named state so callers can detect
+// a malformed value (e.g. "--to phaseX") instead of silently advancing. (#635)
+const NAMED_PHASE_MAP = { start: 1, phase1: 1, phase2: 2, phase3: 3, phase4: 4, end: 4 };
+function parsePhaseToken(raw) {
+  const s = String(raw ?? "").trim().toLowerCase();
+  if (NAMED_PHASE_MAP[s] !== undefined) return NAMED_PHASE_MAP[s];
+  const m = s.match(/\d+/);
+  return m ? Number(m[0]) : NaN;
+}
+
 export function parseTicketArgs(argv) {
-  const out = { cwd: process.cwd(), dryRun: false, nonInteractive: false, limit: 20 };
+  const invocationCwd = process.cwd();
+  const out: Record<string, any> = { cwd: invocationCwd, invocationCwd, dryRun: false, nonInteractive: false, limit: 20 };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--cwd") out.cwd = argv[++i];
+    if (a === "--cwd") {
+      out.cwd = argv[++i];
+      out.cwdExplicit = true;
+    }
     else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--apply") out.apply = true;
     else if (a === "--non-interactive") out.nonInteractive = true;
-    else if (a === "--topic" || a === "--id") out.topic = argv[++i];
+    else if (a === "--id" || a === "--ticket") out.ticketId = argv[++i];
+    else if (a === "--title") out.title = argv[++i];
+    else if (a === "--platform") out.platform = argv[++i];
     else if (a === "--group") out.group = argv[++i];
+    else if (a === "--parent" || a === "--main-ticket") out.parent = argv[++i];
+    else if (a === "--workspace") out.workspace = argv[++i];
+    else if (a === "--allow-cwd-target") {
+      throw new Error("ticket commands no longer support cwd-based target selection. Use --workspace <id>.");
+    }
     else if (a === "--project") out.project = argv[++i];
     else if (a === "--content") out.content = argv[++i];
     else if (a === "--content-file") out.contentFile = argv[++i];
@@ -19,7 +42,10 @@ export function parseTicketArgs(argv) {
     else if (a === "--latest" || a === "-l") out.latest = true;
     else if (a === "--path-only") out.pathOnly = true;
     else if (a === "--print-content") out.printContent = true;
+    else if (a === "--with-total") out.withTotal = true;
+    else if (a === "--takeover") out.takeover = true;
     else if (a === "--all") out.all = true;
+    else if (a === "--active") out.active = true;
     else if (a === "--status") out.status = argv[++i];
     else if (a === "--archived") out.archived = true;
     else if (a === "--priority") out.priority = argv[++i];
@@ -33,13 +59,12 @@ export function parseTicketArgs(argv) {
     else if (a === "--docs-language") out.docsLanguage = argv[++i];
     else if (a === "--workflow") out.workflowMode = argv[++i];
     else if (a === "--approval") out.approval = argv[++i];
-    else if (a === "--ticket-started") out.ticketStarted = true;
-    else if (a === "--ticket-reviewed") out.ticketReviewed = true;
     else if (a === "--evidence") out.evidence = argv[++i];
     else if (a === "--skip-phase0") out.skipPhase0 = true;
     else if (a === "--summary") out.summary = argv[++i];
+    else if (a === "--type") out.ticketType = argv[++i];
     else if (a === "--tags") out.tags = argv[++i];
-    else if (a === "--phase") out.phase = Number(argv[++i]);
+    else if (a === "--phase" || a === "--to") { out.phase = parsePhaseToken(argv[++i]); out.phaseRequested = true; }
     else if (a === "--next") out.next = true;
     else if (a === "--handoff") out.handoff = true;
     else if (a === "--reason") out.reason = argv[++i];
@@ -48,30 +73,41 @@ export function parseTicketArgs(argv) {
     else if (a === "--allow-placeholder") out.allowPlaceholder = true;
     else if (a === "--compact") out.compact = true;
     else if (a === "--status-detail") out.statusDetail = true;
+    else if (a === "--verbose") out.verbose = true;
     else if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "--session-id") out.sessionId = argv[++i];
+    else if (!a.startsWith("-")) out.ticketId = out.ticketId || a;
   }
   return out;
 }
 
 export function parseArgs(argv) {
-  const out = { cwd: process.cwd(), dryRun: false, backup: false };
+  const out: Record<string, any> = { cwd: process.cwd(), dryRun: false, backup: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--cwd") out.cwd = argv[++i];
+    if (a === "--cwd") {
+      out.cwd = argv[++i];
+      out.cwdExplicit = true;
+    }
     else if (a === "--dry-run") out.dryRun = true;
     else if (a === "--backup") out.backup = true;
     else if (a === "--non-interactive") out.nonInteractive = true;
     else if (a === "--interactive") out.interactive = true;
     else if (a === "--clean") out.clean = true;
     else if (a === "--tag") out.tag = argv[++i];
+    else if (a === "--platform") out.platform = argv[++i];
     else if (a === "--marker-begin") out.markerBegin = argv[++i];
     else if (a === "--marker-end") out.markerEnd = argv[++i];
-    else if (a === "--agents") out.agents = argv[++i];
     else if (a === "--cursorrules") out.cursorrules = argv[++i];
     else if (a === "--append-if-no-markers") out.appendIfNoMarkers = true;
     else if (a === "--workflow") out.workflowMode = argv[++i];
     else if (a === "--approval") out.approval = argv[++i];
+    else if (a === "--workspace") out.workspace = argv[++i];
+    else if (a === "--prompt") out.prompt = argv[++i];
+    else if (a === "--project") out.project = argv[++i];
+    else if (a === "--section") out.section = argv[++i];
     else if (a === "--json") out.json = true;
+    else if (a === "--path-only") out.pathOnly = true;
     else if (a === "--remote") out.remote = argv[++i];
     else if (a === "--kind" || a === "--workspace-kind") out.workspaceKind = argv[++i];
     else if (a === "--stack" || a === "--technical-surface") out.stack = argv[++i];
@@ -80,13 +116,14 @@ export function parseArgs(argv) {
     else if (a === "--no-sync") out.sync = false;
     else if (a === "--docs-language") out.docsLanguage = argv[++i];
     else if (a === "--compact") out.compact = true;
+    else if (a === "--session-id") out.sessionId = argv[++i];
     else if (a === "-h" || a === "--help") out.help = true;
   }
   return out;
 }
 
 export function parseSkillArgs(argv) {
-  const out = { cwd: process.cwd(), dryRun: false, nonInteractive: false };
+  const out: Record<string, any> = { cwd: process.cwd(), dryRun: false, nonInteractive: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--cwd") out.cwd = argv[++i];
@@ -100,7 +137,7 @@ export function parseSkillArgs(argv) {
 }
 
 export function parseUsageArgs(argv) {
-  const out = {
+  const out: Record<string, any> = {
     cwd: process.cwd(),
     json: false,
     platform: "",
@@ -137,7 +174,7 @@ export function parseUsageArgs(argv) {
 }
 
 export function parseTelemetryArgs(argv) {
-  const out = {
+  const out: Record<string, any> = {
     cwd: process.cwd(),
     tokens: 0,
     tdw: 0,

package/scripts/cli-context-commands.ts

@@ -0,0 +1,35 @@
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { CliOpts, makePath, resolvePackageRoot } from "./cli-utils.js";
+import { spawnSync } from "child_process";
+
+const pkgRoot = resolvePackageRoot({ fromUrl: import.meta.url });
+
+function contextBinCandidate() {
+  if (process.env.DEUK_AGENT_CONTEXT_BIN) {
+    return resolve(process.env.DEUK_AGENT_CONTEXT_BIN);
+  }
+  return resolve(pkgRoot, "..", "DeukAgentContext", "bin", "deuk-agent-context.js");
+}
+
+export function runContextCommand(args = []) {
+  const localBin = contextBinCandidate();
+  const result = existsSync(localBin)
+    ? spawnSync(process.execPath, [localBin, ...args], { stdio: "inherit", cwd: process.cwd() })
+    : spawnSync("deuk-agent-context", args, {
+        stdio: "inherit",
+        cwd: process.cwd(),
+        shell: process.platform === "win32",
+      });
+
+  if (result.error) {
+    if ((result.error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("deuk-agent-context command not found. Install or link DeukAgentContext, or set DEUK_AGENT_CONTEXT_BIN.");
+    }
+    throw result.error;
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    process.exit(result.status);
+  }
+}

package/scripts/cli-init-claude.ts

@@ -0,0 +1,179 @@
+import { dirname } from "path";
+import { writeFileSync, mkdirSync } from "fs";
+import { createHash } from "crypto";
+import { CliOpts, makePath, resolveUserHome } from "./cli-utils.js";
+import { CLAUDE_SETTINGS_PATH, CLAUDE_USERPROMPT_SUBMIT_COMMAND, CLAUDE_USERPROMPT_SUBMIT_MATCHER, safeReadText } from "./cli-init-core.js";
+
+function isManagedClaudePromptHookCommand(value) {
+  const command = String(value || "").trim();
+  if (!/\bdeuk-agent-flow\b/.test(command)) return false;
+  // 현재 정식 커맨드이거나, rules를 포함하는 관리형 커맨드(구버전 포함)
+  if (command === CLAUDE_USERPROMPT_SUBMIT_COMMAND) return true;
+  if (/\brules\b/.test(command)) return true;
+  return false;
+}
+
+function isCommandHookItem(item) {
+  return Boolean(item && typeof item === "object" && item.type === "command" && typeof item.command === "string");
+}
+
+function readClaudeSettings(homeDir = resolveUserHome()) {
+  const settingsPath = makePath(homeDir, CLAUDE_SETTINGS_PATH);
+  const raw = safeReadText(settingsPath);
+  if (!raw.trim()) return { ok: false };
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { ok: false };
+    return { ok: true, path: settingsPath, parsed };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function writeClaudeSettings(settingsPath, next, dryRun) {
+  if (dryRun) return;
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}
+
+function hashClaudeSettingsState(settings) {
+  return createHash("sha256").update(JSON.stringify(settings, null, 2), "utf8").digest("hex");
+}
+
+export function upsertClaudeUserPromptSubmitHook({ homeDir = resolveUserHome(), dryRun = false } = {}) {
+  const state = readClaudeSettings(homeDir);
+  if (!state.ok) return { changed: false };
+
+  const settings = state.parsed;
+  const hooksRoot = (settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks))
+    ? { ...settings.hooks }
+    : {};
+
+  const rawEntries = Array.isArray(hooksRoot.UserPromptSubmit) ? [...hooksRoot.UserPromptSubmit] : [];
+  const nextEntries = [];
+  let changed = false;
+  let hadManagedPromptSubmitHook = false;
+  let inserted = false;
+  let matcherIndex = -1;
+
+  for (const rawEntry of rawEntries) {
+    if (!rawEntry || typeof rawEntry !== "object") {
+      nextEntries.push(rawEntry);
+      continue;
+    }
+
+    const entry = { ...rawEntry };
+    const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+    const keptHooks = [];
+    for (const hook of hooks) {
+      if (isCommandHookItem(hook) && isManagedClaudePromptHookCommand(hook.command)) {
+        hadManagedPromptSubmitHook = true;
+        changed = true;
+        if (!inserted) {
+          keptHooks.push({ type: "command", command: CLAUDE_USERPROMPT_SUBMIT_COMMAND });
+          inserted = true;
+        }
+        continue;
+      }
+      keptHooks.push(hook);
+    }
+
+    entry.hooks = keptHooks;
+    if (entry.matcher === CLAUDE_USERPROMPT_SUBMIT_MATCHER && matcherIndex === -1) {
+      matcherIndex = nextEntries.length;
+    }
+    nextEntries.push(entry);
+  }
+
+  const hasCanonicalNow = nextEntries.some((entry) => {
+    if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks)) return false;
+    return entry.hooks.some((hook) => isCommandHookItem(hook) && hook.command === CLAUDE_USERPROMPT_SUBMIT_COMMAND);
+  });
+
+  if (!hasCanonicalNow) {
+    if (nextEntries.length === 0) {
+      nextEntries.push({
+        matcher: CLAUDE_USERPROMPT_SUBMIT_MATCHER,
+        hooks: [{ type: "command", command: CLAUDE_USERPROMPT_SUBMIT_COMMAND }]
+      });
+      changed = true;
+    } else {
+      const targetIndex = matcherIndex >= 0 ? matcherIndex : 0;
+      const target = nextEntries[targetIndex];
+      const targetHooks = Array.isArray(target.hooks) ? target.hooks : [];
+      target.hooks = [...targetHooks, { type: "command", command: CLAUDE_USERPROMPT_SUBMIT_COMMAND }];
+      if (typeof target.matcher !== "string") target.matcher = CLAUDE_USERPROMPT_SUBMIT_MATCHER;
+      changed = true;
+    }
+  }
+
+  const filteredEntries = nextEntries.filter((entry) => {
+    if (!entry || typeof entry !== "object") return true;
+    if (!Array.isArray(entry.hooks)) return true;
+    return entry.hooks.length > 0;
+  });
+  const finalEntries = filteredEntries.length > 0 ? filteredEntries : nextEntries;
+
+  const nextSettings = {
+    ...settings,
+    hooks: {
+      ...(hooksRoot),
+      UserPromptSubmit: finalEntries
+    }
+  };
+
+  const beforeHash = hashClaudeSettingsState(settings);
+  const afterHash = hashClaudeSettingsState(nextSettings);
+  if (beforeHash === afterHash) return { changed: false, hash: beforeHash };
+
+  writeClaudeSettings(state.path, nextSettings, dryRun);
+  return { changed: true, hash: afterHash };
+}
+
+export function removeClaudeUserPromptSubmitHook({ homeDir = resolveUserHome(), dryRun = false } = {}) {
+  const state = readClaudeSettings(homeDir);
+  if (!state.ok) return { changed: false };
+
+  const settings = state.parsed;
+  const hooksRoot = settings.hooks;
+  if (!hooksRoot || typeof hooksRoot !== "object" || Array.isArray(hooksRoot)) return { changed: false };
+
+  const current = Array.isArray(hooksRoot.UserPromptSubmit) ? hooksRoot.UserPromptSubmit : [];
+  const next = [];
+  let changed = false;
+
+  for (const entry of current) {
+    if (!entry || typeof entry !== "object") {
+      next.push(entry);
+      continue;
+    }
+    const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+    const nextHooks = hooks.filter((hook) => !(isCommandHookItem(hook) && isManagedClaudePromptHookCommand(hook.command)));
+    if (nextHooks.length !== hooks.length) changed = true;
+    if (nextHooks.length > 0) {
+      next.push({ ...entry, hooks: nextHooks });
+    } else {
+      changed = true;
+    }
+  }
+
+  if (!changed) return { changed: false };
+
+  const nextHooksRoot = { ...hooksRoot };
+  if (next.length > 0) {
+    nextHooksRoot.UserPromptSubmit = next;
+  } else {
+    delete nextHooksRoot.UserPromptSubmit;
+  }
+
+  const nextSettings = {
+    ...settings,
+    hooks: nextHooksRoot
+  };
+  const beforeHash = hashClaudeSettingsState(settings);
+  const afterHash = hashClaudeSettingsState(nextSettings);
+  if (beforeHash === afterHash) return { changed: false, hash: beforeHash };
+  writeClaudeSettings(state.path, nextSettings, dryRun);
+  return { changed: true, hash: afterHash };
+}