vibe-coding-master 0.0.13 → 0.0.15

package/README.md

@@ -14,7 +14,7 @@ Each role runs as a real Claude Code process inside an embedded terminal. The GU
 ## Current V1 Capabilities
 
 - GUI-first task workspace.
-- Collapsible sidebar with repository connection, workflow, settings, harness status, task creation, and task list.
+- Collapsible sidebar with repository connection, settings, harness status, task creation, and task list.
 - Recent repository path dropdown, stored locally with the five most recent paths.
 - Embedded Claude Code terminals powered by `node-pty` and `xterm.js`.
 - One Claude Code session per role, with role tabs in the task header.
@@ -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
@@ -156,8 +154,6 @@ project-manager
   -> project-manager final acceptance, commit, and PR
 ```
 
-The workflow status is shown in the sidebar `Workflow` section. It is a soft guide in V1: VCM highlights missing or incomplete handoff artifacts and suggests the next step, but it does not hard-block the user from manually starting or switching roles.
-
 ## Task Worktree Management
 
 VCM uses task-level worktree management by default:
@@ -189,8 +185,7 @@ The left sidebar is intentionally compact and collapsible:
 
 - `Repository Path`: path input on one row; `Recent` and `Connect` on the next row.
 - `Repository`: connected path, branch, and working tree state. `Working tree: uncommitted changes` means `git status --porcelain` is not empty.
-- `Workflow`: current soft gate and five workflow steps.
-- `Settings`: `Theme`, `Round alert`, `Messages`, and `Events`.
+- `Settings`: `Theme`, `Round alert`, `Try alert`, `Messages`, and `Events`.
 - `VCM Harness`: status for `CLAUDE.md`, role agent files, and `.gitignore`.
 - `New Task`: one `task name` input.
 - `Tasks`: task list and task status.
@@ -211,7 +206,7 @@ The same file stores recent repository paths. The translation API key is stored
 
 The sidebar `Settings` section also stores the UI theme preference in this file. The default is `system`, which follows the OS/browser color-scheme preference; users can cycle between `System`, `Light`, and `Dark`.
 
-The same sidebar also has a `Round alert` toggle. It is on by default and controls the in-app prompt plus short sound that fires when VCM detects that the current full conversation round is complete.
+The same sidebar also has a `Round alert` toggle. It is on by default and controls the in-app prompt plus short sound that fires when VCM detects that the current full conversation round is complete. The `Try alert` button triggers the same local prompt and sound for testing.
 
 Translation behavior:
 
@@ -263,31 +258,33 @@ 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 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.
 
 Role sessions learn VCM rules from `CLAUDE.md` and `.claude/agents/*.md`. VCM does not paste a long context block into the terminal at session start.
 
 ## 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:
@@ -295,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
 
@@ -308,33 +305,36 @@ 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, and a `Copy` button for each message.
+- The current GUI shows sequence, timestamp, status, body preview, path, `Copy`, and `Mark All Done`.
+- `Mark All Done` marks open message records as `acknowledged` after the user manually copied or handled stuck queued/in-flight messages.
 - The user decides what to do next by copying or manually acting on the message.
 - VCM does not write to the target terminal or press Enter for the user.
 
 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 delivered message, VCM writes a `[VCM MESSAGE]` envelope to the target terminal and submits it.
-- When the GUI observes a newly delivered 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 delivered 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.
+- 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 `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 Claude Code transcript JSONL events, not PTY silence. The backend watches each running role session and treats `stop_reason === "end_turn"` as a candidate end only after pending tool uses have finished and a short debounce passes.
+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 delivered message's target role. 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 finishes the final response. If no VCM role message is involved, the latest direct role answer can complete the round.
+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.
 
 When `Round alert` is enabled, the frontend polls the task round state, deduplicates each completion id, shows a small `Round complete` prompt, and plays a short local sound.
 
@@ -370,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
 ```
@@ -383,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

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

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

@@ -5,32 +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
-        });
+        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
-        });
+        return deps.messageService.scanAndDispatchPendingRouteFiles(context);
     });
-    app.post("/api/tasks/:taskSlug/messages/:messageId/approve", async (request) => {
+    app.post("/api/tasks/:taskSlug/messages/mark-all-done", async (request) => {
         const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.approveMessage({
+        return deps.messageService.markAllDone({
             ...context,
-            messageId: request.params.messageId
-        });
-    });
-    app.post("/api/tasks/:taskSlug/messages/:messageId/reject", async (request) => {
-        const context = await getRouteContext(deps, request.params.taskSlug);
-        return deps.messageService.rejectMessage({
-            ...context,
-            messageId: request.params.messageId
+            clearRouteFiles: true
         });
     });
     app.get("/api/tasks/:taskSlug/orchestration", async (request) => {
@@ -48,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";
@@ -7,6 +6,7 @@ import { createArtifactService } from "./services/artifact-service.js";
 import { createClaudeAdapter } from "./adapters/claude-adapter.js";
 import { createCommandRunner } from "./adapters/command-runner.js";
 import { createCommandDispatcher } from "./services/command-dispatcher.js";
+import { createClaudeHookService } from "./services/claude-hook-service.js";
 import { createGitAdapter } from "./adapters/git-adapter.js";
 import { createAppSettingsService } from "./services/app-settings-service.js";
 import { createClaudeTranscriptService } from "./services/claude-transcript-service.js";
@@ -24,6 +24,7 @@ import { createTaskService } from "./services/task-service.js";
 import { createTranslationService } from "./services/translation-service.js";
 import { registerAppSettingsRoutes } from "./api/app-settings-routes.js";
 import { registerArtifactRoutes } from "./api/artifact-routes.js";
+import { registerClaudeHookRoutes } from "./api/claude-hook-routes.js";
 import { registerHarnessRoutes } from "./api/harness-routes.js";
 import { registerMessageRoutes } from "./api/message-routes.js";
 import { registerProjectRoutes } from "./api/project-routes.js";
@@ -48,6 +49,7 @@ export async function createServer(deps, options = {}) {
         });
     });
     registerAppSettingsRoutes(app, { appSettings: deps.appSettings });
+    registerClaudeHookRoutes(app, { claudeHookService: deps.claudeHookService });
     registerProjectRoutes(app, { projectService: deps.projectService });
     registerHarnessRoutes(app, {
         projectService: deps.projectService,
@@ -137,8 +139,7 @@ export function createDefaultServerDeps(options = {}) {
         artifactService,
         projectService,
         taskService,
-        apiUrl: options.apiUrl,
-        vcmctlCommand: options.vcmctlCommand ?? resolveVcmctlCommand()
+        apiUrl: options.apiUrl
     });
     const commandDispatcher = createCommandDispatcher({
         runtime,
@@ -157,10 +158,14 @@ export function createDefaultServerDeps(options = {}) {
         sessionService,
         taskService
     });
-    const transcripts = createClaudeTranscriptService();
-    const roundService = createRoundService({
-        transcripts
+    const claudeHookService = createClaudeHookService({
+        projectService,
+        taskService,
+        sessionService,
+        messageService
     });
+    const transcripts = createClaudeTranscriptService();
+    const roundService = createRoundService();
     const translationService = createTranslationService({
         runtime,
         sessionRegistry: registry,
@@ -179,6 +184,7 @@ export function createDefaultServerDeps(options = {}) {
         artifactService,
         harnessService,
         commandDispatcher,
+        claudeHookService,
         messageService,
         roundService,
         statusService,
@@ -189,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

@@ -0,0 +1,67 @@
+import { isRoleName } from "../../shared/constants.js";
+import { VcmError } from "../errors.js";
+import { getTaskRuntimeRepoRoot } from "./task-service.js";
+export function createClaudeHookService(deps) {
+    return {
+        async handleStopHook(input) {
+            if (!isRoleName(input.role)) {
+                throw new VcmError({
+                    code: "HOOK_ROLE_INVALID",
+                    message: `Unknown hook role: ${input.role}`,
+                    statusCode: 400
+                });
+            }
+            const eventName = parseStopEvent(input.event.hook_event_name);
+            const project = await deps.projectService.getCurrentProject();
+            if (!project) {
+                throw new VcmError({
+                    code: "PROJECT_NOT_CONNECTED",
+                    message: "Connect a repository before accepting Claude Code hooks.",
+                    statusCode: 409
+                });
+            }
+            const session = await deps.sessionService.recordClaudeHookEvent(project.repoRoot, {
+                taskSlug: input.taskSlug,
+                role: input.role,
+                eventName,
+                claudeSessionId: stringOrUndefined(input.event.session_id),
+                transcriptPath: stringOrUndefined(input.event.transcript_path),
+                cwd: stringOrUndefined(input.event.cwd)
+            });
+            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),
+                dispatchedCount: dispatched.filter((result) => result.delivered).length
+            };
+        }
+    };
+}
+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 accepts Stop hooks only."
+    });
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}

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

@@ -8,6 +8,9 @@ import { renderReviewerHarnessRules } from "../templates/harness/reviewer-agent.
 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 [ -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",
@@ -84,6 +87,7 @@ async function analyzeHarnessFiles(fs, repoRoot) {
     for (const definition of HARNESS_FILES) {
         analyses.push(await analyzeHarnessFile(fs, repoRoot, definition));
     }
+    analyses.push(await analyzeClaudeSettingsFile(fs, repoRoot));
     return analyses;
 }
 async function analyzeHarnessFile(fs, repoRoot, definition) {
@@ -188,6 +192,114 @@ function renderNewHarnessFile(definition, block) {
         : "";
     return `${frontmatter}# ${definition.title}\n\n${block}\n`;
 }
+async function analyzeClaudeSettingsFile(fs, repoRoot) {
+    const definition = {
+        kind: "claude-settings",
+        path: CLAUDE_SETTINGS_PATH,
+        title: "Claude Code Settings",
+        renderRules: () => ""
+    };
+    const absolutePath = resolveHarnessPath(repoRoot, CLAUDE_SETTINGS_PATH);
+    const exists = await fs.pathExists(absolutePath);
+    const current = exists
+        ? parseJsonObject(await fs.readText(absolutePath))
+        : {};
+    const next = withVcmClaudeHooks(current);
+    const currentContent = exists
+        ? `${JSON.stringify(current, null, 2)}\n`
+        : "";
+    const nextContent = `${JSON.stringify(next, null, 2)}\n`;
+    const action = exists
+        ? currentContent === nextContent ? "ok" : "update"
+        : "create";
+    return {
+        definition,
+        status: {
+            kind: "claude-settings",
+            path: CLAUDE_SETTINGS_PATH,
+            exists,
+            hasManagedBlock: false,
+            action
+        },
+        plannedChange: action === "ok"
+            ? undefined
+            : {
+                path: CLAUDE_SETTINGS_PATH,
+                action,
+                reason: exists
+                    ? "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
+    };
+}
+function parseJsonObject(content) {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+    }
+    return parsed;
+}
+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]
+            : [];
+        hooks[eventName] = [
+            ...existingMatchers.filter((entry) => !isVcmHookMatcher(entry)),
+            createVcmHookMatcher()
+        ];
+    }
+    return {
+        ...settings,
+        hooks
+    };
+}
+function createVcmHookMatcher() {
+    return {
+        hooks: [
+            {
+                type: "command",
+                command: VCM_HOOK_COMMAND,
+                timeout: 5
+            }
+        ]
+    };
+}
+function isVcmHookMatcher(value) {
+    if (!isPlainObject(value) || !Array.isArray(value.hooks)) {
+        return false;
+    }
+    return value.hooks.some((hook) => {
+        if (!isPlainObject(hook)) {
+            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) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function renderAgentFrontmatter(name, description) {
     return `---\nname: ${name}\ndescription: ${description}\ntools: Read, Grep, Glob, Bash, Edit, Write\n---`;
 }