vibe-coding-master 0.0.14 → 0.0.15

package/README.md

@@ -23,7 +23,7 @@ Each role runs as a real Claude Code process inside an embedded terminal. The GU
   - `default`
   - `bypassPermissions`
   - `--dangerously-skip-permissions`
-- PM-mediated role messaging through `vcmctl`.
+- PM-mediated role messaging through VCM-dispatched route files.
 - Manual and automatic orchestration modes.
 - VCM harness installer for `CLAUDE.md`, `.claude/agents/*.md`, and the VCM-managed `.gitignore` block.
 - Translation panel powered by an OpenAI-compatible low-cost model.
@@ -50,8 +50,6 @@ npm install -g vibe-coding-master
 vcm
 ```
 
-The package also installs `vcmctl`, which Claude Code role sessions use internally to send VCM messages.
-
 From source:
 
 ```bash
@@ -260,7 +258,7 @@ For `.gitignore`, VCM uses a gitignore-native managed block:
 
 `.ai/vcm/` is the active VCM local control area, and `.claude/worktrees/` is the Claude-compatible task worktree area. The base repo keeps the task index; each task runtime repo keeps its own session, message, orchestration, and translation state.
 
-VCM also JSON-merges `.claude/settings.json` to install Claude Code `UserPromptSubmit` and `Stop` hooks. Those hooks call `vcmctl hook-event` through the session-provided `VCM_CTL_COMMAND`, so users do not need to configure hook commands manually.
+VCM also JSON-merges `.claude/settings.json` to install a Claude Code `Stop` hook. The hook posts directly to the local VCM backend, so roles do not need a VCM CLI command to report turn completion.
 
 After applying harness changes, VCM reports the exact files changed and reminds the user to review and commit them before starting long-running work.
 
@@ -268,25 +266,25 @@ Role sessions learn VCM rules from `CLAUDE.md` and `.claude/agents/*.md`. VCM do
 
 ## Message Bus
 
-The message bus is API-driven. VCM does not watch files to trigger role messages.
+The message bus is file-driven and dispatched by VCM after Claude Code turn completion. Roles do not call a VCM CLI to send messages.
 
 Role communication works like this:
 
 ```text
 Claude Code role
-  -> runs vcmctl send / vcmctl reply / vcmctl result
-  -> vcmctl calls VCM backend API
-  -> backend validates message policy and persists the message
-  -> backend writes to the target embedded terminal when allowed
+  -> writes or updates .ai/vcm/handoffs/messages/<from-role>-<to-role>.md
+  -> ends the Claude Code turn
+  -> Stop hook calls VCM backend directly
+  -> VCM scans pending route files
+  -> VCM validates, snapshots, and dispatches pending messages
 ```
 
-Examples that roles can run inside their terminal:
+Examples:
 
-```bash
-vcmctl send --to coder --type task --body-file /tmp/message.md
-vcmctl reply --type blocked --body "Need clarification."
-vcmctl result --body-file /tmp/result.md --artifact .ai/vcm/handoffs/implementation-log.md
-vcmctl inbox
+```text
+.ai/vcm/handoffs/messages/project-manager-coder.md
+.ai/vcm/handoffs/messages/coder-project-manager.md
+.ai/vcm/handoffs/messages/project-manager-reviewer.md
 ```
 
 Runtime message and handoff files:
@@ -294,12 +292,12 @@ Runtime message and handoff files:
 ```text
 .ai/vcm/messages/<task>.jsonl                 # under the task runtime repo
 .ai/vcm/orchestration/<task>.json             # under the task runtime repo
-.ai/vcm/handoffs/messages/<message-id>.md
+.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 .ai/vcm/handoffs/role-commands/
 .ai/vcm/handoffs/logs/
 ```
 
-The backend also keeps a compatibility role-command dispatch endpoint, but the primary workflow is PM-mediated `vcmctl` messaging.
+Each directed role route has exactly one message file. If a role changes its mind during one turn, it edits the same route file instead of creating another message. A blank file means no pending message; a non-empty file means pending work for VCM to submit.
 
 ## Orchestration Modes
 
@@ -307,7 +305,7 @@ VCM has a task-level `Auto orchestration` switch in the active role toolbar, imm
 
 When it is off, VCM is in manual mode:
 
-- Roles may send messages through `vcmctl`.
+- Roles may write pending route files under `.ai/vcm/handoffs/messages/`.
 - Messages appear in the `Messages` modal.
 - The user can inspect them.
 - The current GUI shows sequence, timestamp, status, body preview, path, `Copy`, and `Mark All Done`.
@@ -318,25 +316,23 @@ When it is off, VCM is in manual mode:
 When it is on, VCM is in auto mode:
 
 - Backend policy still applies.
-- PM can send work to `architect`, `coder`, or `reviewer`.
-- Non-PM roles can reply only to `project-manager`.
-- If the target role session is running and has no active message, VCM writes a `[VCM MESSAGE]` envelope to the target terminal and submits it as `delivering`.
-- Claude Code `UserPromptSubmit` confirms the prompt really entered the target role session; VCM then marks the message `submitted`.
+- Roles write pending route files under `.ai/vcm/handoffs/messages/`.
+- On Claude Code `Stop`, VCM scans pending route files.
+- If the target role session is running, idle, and has no active message, VCM writes a `[VCM MESSAGE]` envelope to the target terminal and submits it.
+- After successful terminal submission, VCM snapshots the body in message history and clears the source route file.
 - When the GUI observes a newly submitted auto message, it switches the active role tab to that message's target role so the user can watch the next step.
-- VCM enforces per-role turn-taking: each target role can have at most one in-flight `delivering`, `submitted`, `delivered`, or `staged` message.
-- Additional messages to a busy target role are kept as `queued` and are not written to that terminal.
-- When a role sends `vcmctl reply` or `vcmctl result`, VCM acknowledges that role's active message and delivers the next queued message for that role.
-- If auto orchestration gets stuck after a manual copy/paste recovery, `Mark All Done` clears open `pending_approval`, `queued`, `staged`, `delivering`, `submitted`, `delivered`, and failed message records to `acknowledged`.
-
-VCM Harness injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`. Role tabs show `running` after `UserPromptSubmit` and `idle` after `Stop`; the terminal process status is still tracked separately. The injected role rules also require a role to end its turn after any successful `vcmctl send`, `vcmctl reply`, or `vcmctl result`, rather than running `vcmctl inbox`, looping, polling, or waiting for another role inside the same Claude Code turn.
+- VCM enforces per-role turn-taking: each target role can have at most one in-flight `submitted` message.
+- Additional pending files to a busy target role remain non-empty and are not written to that terminal.
+- When the target role later reaches `Stop`, VCM scans again and may deliver the next pending route file.
+- If auto orchestration gets stuck after a manual copy/paste recovery, `Mark All Done` clears open `pending_approval`, `queued`, `submitted`, and failed message records to `acknowledged`, and clears pending route files.
 
-The backend state model still contains a `paused` field for compatibility with existing API routes, but the current GUI exposes only a single on/off orchestration toggle.
+VCM Harness injects a Claude Code `Stop` hook into `.claude/settings.json`. Role tabs become `running` when VCM submits user input or a message to that embedded terminal, and `idle` after `Stop`; the terminal process status is still tracked separately. The injected role rules require a role to end its turn after writing or updating a message route file, rather than polling, looping, or waiting for another role inside the same Claude Code turn.
 
-The backend still exposes stage/approve/reject compatibility APIs for automation and future UI work. They are not primary controls in the current Messages modal.
+The implementation keeps only the active manual/auto orchestration mode. It does not expose pause/resume, stage/approve/reject, or a separate agent-facing message CLI.
 
 ## Round Completion Alerts
 
-VCM detects conversation completion from the hook-driven role activity state, not PTY silence. `UserPromptSubmit` marks a role `running`, and `Stop` marks that role `idle` with a stop timestamp.
+VCM detects conversation completion from hook-driven role activity state, not PTY silence. VCM terminal submission marks a role `running`, and `Stop` marks that role `idle` with a stop timestamp.
 
 For role chains, VCM waits for the latest active message's target role to reach hook `Stop`. For example, if PM sends work to Coder and Coder sends a result back to PM, the round is not complete when Coder finishes; it is complete only after PM reaches `Stop` for the final response. If no VCM role message is involved, the latest direct role `Stop` can complete the round.
 
@@ -374,6 +370,7 @@ For a connected repository, VCM uses:
 <taskRepoRoot>/.ai/vcm/handoffs/validation-log.md
 <taskRepoRoot>/.ai/vcm/handoffs/review-report.md
 <taskRepoRoot>/.ai/vcm/handoffs/docs-sync-report.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 <taskRepoRoot>/.ai/vcm/handoffs/role-commands/{architect,coder,reviewer}.md
 <taskRepoRoot>/.ai/vcm/handoffs/logs/{project-manager,architect,coder,reviewer}.log
 ```
@@ -387,7 +384,6 @@ Because handoffs are scoped to `taskRepoRoot` without an extra task-name directo
 The npm package publishes built output, not raw TypeScript entry files. `package.json` includes:
 
 - `bin.vcm`: `dist/main.js`
-- `bin.vcmctl`: `dist/cli/vcmctl.js`
 - `files`: `dist`, `dist-frontend`, `docs`, `scripts`, `README.md`
 - `prepack`: `npm run build && npm run verify:package`
 

package/dist/backend/api/claude-hook-routes.js

@@ -1,5 +1,5 @@
 export function registerClaudeHookRoutes(app, deps) {
-    app.post("/api/hooks/claude-code", async (request) => {
-        return deps.claudeHookService.handleHook(request.body);
+    app.post("/api/hooks/claude-code/stop", async (request) => {
+        return deps.claudeHookService.handleStopHook(request.body);
     });
 }

package/dist/backend/api/message-routes.js

@@ -5,36 +5,19 @@ export function registerMessageRoutes(app, deps) {
         const context = await getRouteContext(deps, request.params.taskSlug);
         return deps.messageService.listMessages(context);
     });
-    app.post("/api/tasks/:taskSlug/messages", async (request) => {
+    app.get("/api/tasks/:taskSlug/messages/pending-routes", async (request) => {
         const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.sendMessage({
-            ...context,
-            ...request.body
-        });
-    });
-    app.post("/api/tasks/:taskSlug/messages/mark-all-done", async (request) => {
-        const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.markAllDone(context);
+        return deps.messageService.listPendingRouteFiles(context);
     });
-    app.post("/api/tasks/:taskSlug/messages/:messageId/stage", async (request) => {
+    app.post("/api/tasks/:taskSlug/messages/scan", async (request) => {
         const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.stageMessage({
-            ...context,
-            messageId: request.params.messageId
-        });
-    });
-    app.post("/api/tasks/:taskSlug/messages/:messageId/approve", async (request) => {
-        const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.approveMessage({
-            ...context,
-            messageId: request.params.messageId
-        });
+        return deps.messageService.scanAndDispatchPendingRouteFiles(context);
     });
-    app.post("/api/tasks/:taskSlug/messages/:messageId/reject", async (request) => {
+    app.post("/api/tasks/:taskSlug/messages/mark-all-done", async (request) => {
         const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.rejectMessage({
+        return deps.messageService.markAllDone({
             ...context,
-            messageId: request.params.messageId
+            clearRouteFiles: true
         });
     });
     app.get("/api/tasks/:taskSlug/orchestration", async (request) => {
@@ -52,22 +35,7 @@ export function registerMessageRoutes(app, deps) {
         }
         return deps.messageService.updateOrchestrationState({
             ...context,
-            mode: request.body.mode,
-            paused: request.body.paused
-        });
-    });
-    app.post("/api/tasks/:taskSlug/orchestration/pause", async (request) => {
-        const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.updateOrchestrationState({
-            ...context,
-            paused: true
-        });
-    });
-    app.post("/api/tasks/:taskSlug/orchestration/resume", async (request) => {
-        const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.updateOrchestrationState({
-            ...context,
-            paused: false
+            mode: request.body.mode
         });
     });
 }

package/dist/backend/server.js

@@ -1,5 +1,4 @@
 import path from "node:path";
-import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
@@ -140,8 +139,7 @@ export function createDefaultServerDeps(options = {}) {
         artifactService,
         projectService,
         taskService,
-        apiUrl: options.apiUrl,
-        vcmctlCommand: options.vcmctlCommand ?? resolveVcmctlCommand()
+        apiUrl: options.apiUrl
     });
     const commandDispatcher = createCommandDispatcher({
         runtime,
@@ -197,26 +195,6 @@ export function createDefaultServerDeps(options = {}) {
 export function getDefaultStaticDir() {
     return path.join(getAppRoot(), "dist-frontend");
 }
-function resolveVcmctlCommand() {
-    const appRoot = getAppRoot();
-    const currentModulePath = fileURLToPath(import.meta.url);
-    const sourceCli = path.join(appRoot, "src", "cli", "vcmctl.ts");
-    const tsxCli = path.join(appRoot, "node_modules", "tsx", "dist", "cli.mjs");
-    if (currentModulePath.includes(`${path.sep}src${path.sep}`) && existsSync(tsxCli) && existsSync(sourceCli)) {
-        return `${quoteShellArg(process.execPath)} ${quoteShellArg(tsxCli)} ${quoteShellArg(sourceCli)}`;
-    }
-    const distCli = path.join(appRoot, "dist", "cli", "vcmctl.js");
-    if (existsSync(distCli)) {
-        return `${quoteShellArg(process.execPath)} ${quoteShellArg(distCli)}`;
-    }
-    if (existsSync(tsxCli) && existsSync(sourceCli)) {
-        return `${quoteShellArg(process.execPath)} ${quoteShellArg(tsxCli)} ${quoteShellArg(sourceCli)}`;
-    }
-    return "vcmctl";
-}
 function getAppRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 }
-function quoteShellArg(value) {
-    return `'${value.replace(/'/g, "'\\''")}'`;
-}

package/dist/backend/services/artifact-service.js

@@ -3,7 +3,7 @@ import { DISPATCHABLE_ROLES, ROLE_NAMES } from "../../shared/constants.js";
 import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderArchitecturePlanTemplate, renderDocsSyncReportTemplate, renderImplementationLogTemplate, renderReviewReportTemplate, renderValidationLogTemplate } from "../templates/handoff.js";
+import { renderArchitecturePlanTemplate, renderDocsSyncReportTemplate, renderImplementationLogTemplate, renderMessageRouteTemplate, renderReviewReportTemplate, renderValidationLogTemplate } from "../templates/handoff.js";
 import { renderRoleCommandTemplate } from "../templates/role-command.js";
 const ARTIFACT_PATH_KEYS = [
     ["architecture-plan", "architecturePlanPath"],
@@ -13,15 +13,25 @@ const ARTIFACT_PATH_KEYS = [
     ["docs-sync-report", "docsSyncReportPath"]
 ];
 const ROLE_COMMAND_PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|status:\s*draft)\s*(\n|$)/i;
+const DEFAULT_MESSAGE_ROUTES = [
+    ["project-manager", "architect"],
+    ["project-manager", "coder"],
+    ["project-manager", "reviewer"],
+    ["architect", "project-manager"],
+    ["coder", "project-manager"],
+    ["reviewer", "project-manager"]
+];
 export function createArtifactService(fs) {
     return {
         getHandoffPaths(_repoRoot, handoffDir) {
             const roleCommandsDir = path.posix.join(handoffDir, "role-commands");
             const logsDir = path.posix.join(handoffDir, "logs");
+            const messagesDir = path.posix.join(handoffDir, "messages");
             return {
                 handoffDir,
                 roleCommandsDir,
                 logsDir,
+                messagesDir,
                 roleCommandPaths: {
                     architect: path.posix.join(roleCommandsDir, "architect.md"),
                     coder: path.posix.join(roleCommandsDir, "coder.md"),
@@ -33,6 +43,7 @@ export function createArtifactService(fs) {
                     coder: path.posix.join(logsDir, "coder.log"),
                     reviewer: path.posix.join(logsDir, "reviewer.log")
                 },
+                messageRoutePaths: getDefaultMessageRoutePaths(messagesDir),
                 architecturePlanPath: path.posix.join(handoffDir, "architecture-plan.md"),
                 implementationLogPath: path.posix.join(handoffDir, "implementation-log.md"),
                 validationLogPath: path.posix.join(handoffDir, "validation-log.md"),
@@ -40,11 +51,15 @@ export function createArtifactService(fs) {
                 docsSyncReportPath: path.posix.join(handoffDir, "docs-sync-report.md")
             };
         },
+        getMessageRoutePath(handoffDir, fromRole, toRole) {
+            return path.posix.join(handoffDir, "messages", `${fromRole}-${toRole}.md`);
+        },
         async ensureHandoffStructure(input) {
             const paths = this.getHandoffPaths(input.repoRoot, input.handoffDir);
             await fs.ensureDir(resolveRepoPath(input.repoRoot, paths.handoffDir));
             await fs.ensureDir(resolveRepoPath(input.repoRoot, paths.roleCommandsDir));
             await fs.ensureDir(resolveRepoPath(input.repoRoot, paths.logsDir));
+            await fs.ensureDir(resolveRepoPath(input.repoRoot, paths.messagesDir));
             return paths;
         },
         async createArtifactTemplates(input) {
@@ -57,7 +72,11 @@ export function createArtifactService(fs) {
                 [paths.implementationLogPath, renderImplementationLogTemplate(input.taskSlug)],
                 [paths.validationLogPath, renderValidationLogTemplate(input.taskSlug)],
                 [paths.reviewReportPath, renderReviewReportTemplate(input.taskSlug)],
-                [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)]
+                [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)],
+                ...Object.values(paths.messageRoutePaths).map((messagePath) => [
+                    messagePath,
+                    renderMessageRouteTemplate()
+                ])
             ];
             const created = [];
             for (const [artifactPath, content] of files) {
@@ -165,6 +184,12 @@ export function createArtifactService(fs) {
 function getLegacyRoleCommandPath(roleCommandsDir, role) {
     return path.posix.join(roleCommandsDir, `${role}-command.md`);
 }
+function getDefaultMessageRoutePaths(messagesDir) {
+    return Object.fromEntries(DEFAULT_MESSAGE_ROUTES.map(([fromRole, toRole]) => [
+        `${fromRole}-${toRole}`,
+        path.posix.join(messagesDir, `${fromRole}-${toRole}.md`)
+    ]));
+}
 async function readTextOrNull(fs, absolutePath) {
     if (!(await fs.pathExists(absolutePath))) {
         return null;

package/dist/backend/services/claude-hook-service.js

@@ -3,7 +3,7 @@ import { VcmError } from "../errors.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
 export function createClaudeHookService(deps) {
     return {
-        async handleHook(input) {
+        async handleStopHook(input) {
             if (!isRoleName(input.role)) {
                 throw new VcmError({
                     code: "HOOK_ROLE_INVALID",
@@ -11,7 +11,7 @@ export function createClaudeHookService(deps) {
                     statusCode: 400
                 });
             }
-            const eventName = parseHookEventName(input.event.hook_event_name);
+            const eventName = parseStopEvent(input.event.hook_event_name);
             const project = await deps.projectService.getCurrentProject();
             if (!project) {
                 throw new VcmError({
@@ -28,41 +28,38 @@ export function createClaudeHookService(deps) {
                 transcriptPath: stringOrUndefined(input.event.transcript_path),
                 cwd: stringOrUndefined(input.event.cwd)
             });
-            let submittedMessageId;
-            if (eventName === "UserPromptSubmit" && typeof input.event.prompt === "string") {
-                const config = await deps.projectService.loadConfig(project.repoRoot);
-                const task = await deps.taskService.loadTask(project.repoRoot, input.taskSlug);
-                const taskRepoRoot = getTaskRuntimeRepoRoot(task);
-                const submitted = await deps.messageService.confirmPromptSubmitted({
-                    repoRoot: project.repoRoot,
-                    stateRepoRoot: taskRepoRoot,
-                    stateRoot: config.stateRoot,
-                    taskSlug: input.taskSlug,
-                    role: input.role,
-                    prompt: input.event.prompt
-                });
-                submittedMessageId = submitted?.id;
-            }
+            const config = await deps.projectService.loadConfig(project.repoRoot);
+            const task = await deps.taskService.loadTask(project.repoRoot, input.taskSlug);
+            const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+            const dispatched = await deps.messageService.scanAndDispatchPendingRouteFiles({
+                repoRoot: project.repoRoot,
+                taskRepoRoot,
+                stateRepoRoot: taskRepoRoot,
+                stateRoot: config.stateRoot,
+                handoffDir: task.handoffDir,
+                taskSlug: input.taskSlug,
+                stoppedRole: input.role
+            });
             return {
                 ok: true,
                 eventName,
                 taskSlug: input.taskSlug,
                 role: input.role,
                 sessionUpdated: Boolean(session),
-                submittedMessageId
+                dispatchedCount: dispatched.filter((result) => result.delivered).length
             };
         }
     };
 }
-function parseHookEventName(value) {
-    if (value === "UserPromptSubmit" || value === "Stop") {
-        return value;
+function parseStopEvent(value) {
+    if (value === undefined || value === "Stop") {
+        return "Stop";
     }
     throw new VcmError({
         code: "HOOK_EVENT_UNSUPPORTED",
         message: `Unsupported Claude Code hook event: ${String(value)}`,
         statusCode: 400,
-        hint: "VCM currently accepts UserPromptSubmit and Stop hooks only."
+        hint: "VCM accepts Stop hooks only."
     });
 }
 function stringOrUndefined(value) {

package/dist/backend/services/harness-service.js

@@ -9,8 +9,8 @@ export const VCM_HARNESS_VERSION = 1;
 const MANAGED_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=(\d+))? -->[\s\S]*?<!-- VCM:END -->/m;
 const HASH_MANAGED_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=(\d+))?\n[\s\S]*?# VCM:END/m;
 const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
-const VCM_HOOK_COMMAND = "sh -c 'if [ -n \"${VCM_CTL_COMMAND:-}\" ]; then eval \"$VCM_CTL_COMMAND hook-event\"; else vcmctl hook-event; fi'";
-const VCM_HOOK_EVENTS = ["UserPromptSubmit", "Stop"];
+const VCM_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code/stop" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
+const VCM_HOOK_EVENTS = ["Stop"];
 const HARNESS_FILES = [
     {
         kind: "root-claude",
@@ -227,7 +227,7 @@ async function analyzeClaudeSettingsFile(fs, repoRoot) {
                 path: CLAUDE_SETTINGS_PATH,
                 action,
                 reason: exists
-                    ? "Claude Code hook settings do not contain the VCM UserPromptSubmit/Stop hook bridge."
+                    ? "Claude Code hook settings do not contain the VCM Stop hook bridge."
                     : "Claude Code hook settings are missing; VCM will create them."
             },
         nextContent: action === "ok" ? undefined : nextContent
@@ -244,6 +244,18 @@ function withVcmClaudeHooks(settings) {
     const hooks = isPlainObject(settings.hooks)
         ? { ...settings.hooks }
         : {};
+    for (const [eventName, value] of Object.entries(hooks)) {
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        const cleaned = value.filter((entry) => !isVcmHookMatcher(entry));
+        if (cleaned.length > 0) {
+            hooks[eventName] = cleaned;
+        }
+        else {
+            delete hooks[eventName];
+        }
+    }
     for (const eventName of VCM_HOOK_EVENTS) {
         const existingMatchers = Array.isArray(hooks[eventName])
             ? hooks[eventName]
@@ -278,6 +290,11 @@ function isVcmHookMatcher(value) {
             return false;
         }
         return typeof hook.command === "string" && hook.command.includes("hook-event");
+    }) || value.hooks.some((hook) => {
+        if (!isPlainObject(hook)) {
+            return false;
+        }
+        return typeof hook.command === "string" && hook.command.includes("/api/hooks/claude-code/stop");
     });
 }
 function isPlainObject(value) {