vibe-coding-master 0.0.12 → 0.0.14

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.
@@ -156,8 +156,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:
@@ -170,7 +168,7 @@ The `Create worktree and branch` option is selected by default when creating a t
 
 - task name: `<task>`
 - branch: `feature/<task>`
-- worktree path: `.ai/vcm/worktrees/<task>` inside the connected base repository
+- worktree path: `.claude/worktrees/<task>` inside the connected base repository
 - role session cwd: that task worktree
 
 VCM will not create worktrees per role. `project-manager`, `architect`, `coder`, and `reviewer` for the same task share the same task worktree.
@@ -179,7 +177,7 @@ The user can turn this option off. In that mode, VCM creates the task metadata a
 
 VCM will not offer a separate `Create task worktree` button after a task exists, and a task should not be switched to another branch/worktree mode after creation.
 
-Because worktrees live under `.ai/vcm/worktrees/`, the connected repository must ignore `.ai/vcm/`. Apply the VCM Harness before creating tasks so `.gitignore` contains the managed ignore block. The base repository must also be clean because the task branch/worktree is created from the connected repo's current `HEAD`.
+Because worktrees live under `.claude/worktrees/`, the connected repository must ignore both `.ai/vcm/` and `.claude/worktrees/`. Apply the VCM Harness before creating tasks so `.gitignore` contains the managed ignore block. The base repository must also be clean because the task branch/worktree is created from the connected repo's current `HEAD`.
 
 When a task is complete, VCM provides a red `Close Task` action. Closing a task shows a destructive confirmation, stops VCM-managed running role sessions for that task, then deletes the task worktree, deletes the task branch by default, removes the base task index entry, and removes task runtime metadata. VCM does not preflight running sessions or uncommitted changes before closing. Tasks created without a worktree only remove VCM metadata because they do not own a separate branch/worktree.
 
@@ -189,8 +187,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`, `Messages`, `Events`, and the `Auto orchestration` on/off toggle.
+- `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.
@@ -199,7 +196,7 @@ All sidebar sections are collapsed by default. When no task is selected, `Reposi
 
 ## Translation
 
-The `Translate` button in the role toolbar opens a translation panel beside the embedded terminal. The terminal and translation panel split the available width evenly.
+The role toolbar has an `Auto orchestration` on/off button immediately to the left of the `Translate` button. The `Translate` button opens a translation panel beside the embedded terminal. The terminal and translation panel split the available width evenly.
 
 Translation settings are local and stored in:
 
@@ -211,6 +208,8 @@ 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 `Try alert` button triggers the same local prompt and sound for testing.
+
 Translation behavior:
 
 - Provider type is OpenAI-compatible chat completions.
@@ -255,10 +254,13 @@ For `.gitignore`, VCM uses a gitignore-native managed block:
 ```gitignore
 # VCM:BEGIN version=1
 .ai/vcm/
+.claude/worktrees/
 # VCM:END
 ```
 
-`.ai/vcm/` is the active VCM local control area. The base repo keeps the task index and nested worktrees; each task runtime repo keeps its own session, message, orchestration, and translation state.
+`.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.
 
 After applying harness changes, VCM reports the exact files changed and reminds the user to review and commit them before starting long-running work.
 
@@ -301,14 +303,15 @@ The backend also keeps a compatibility role-command dispatch endpoint, but the p
 
 ## Orchestration Modes
 
-VCM has a task-level `Auto orchestration` switch in the sidebar `Settings` section.
+VCM has a task-level `Auto orchestration` switch in the active role toolbar, immediately to the left of `Translate`.
 
 When it is off, VCM is in manual mode:
 
 - Roles may send messages through `vcmctl`.
 - 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.
 
@@ -317,12 +320,28 @@ 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, VCM writes a `[VCM MESSAGE]` envelope to the target terminal and submits it.
+- 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`.
+- 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.
 
 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.
 
 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.
 
+## 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.
+
+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.
+
 ## Resume Behavior
 
 Each role session stores its Claude session id and transcript path under:
@@ -345,7 +364,7 @@ For a connected repository, VCM uses:
 ```text
 ~/.vcm/projects/<project-id>/config.json
 <baseRepoRoot>/.ai/vcm/tasks/<task>.json
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/
+<baseRepoRoot>/.claude/worktrees/<task>/
 <taskRepoRoot>/.ai/vcm/sessions/<task>.json
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
@@ -359,7 +378,7 @@ For a connected repository, VCM uses:
 <taskRepoRoot>/.ai/vcm/handoffs/logs/{project-manager,architect,coder,reviewer}.log
 ```
 
-The project config is stored under `~/.vcm` so it is durable local app state and is not hidden inside a Git-ignored repository directory. For worktree-backed tasks, `taskRepoRoot` is `<baseRepoRoot>/.ai/vcm/worktrees/<task>`; for inline tasks, `taskRepoRoot` is the connected base repo.
+The project config is stored under `~/.vcm` so it is durable local app state and is not hidden inside a Git-ignored repository directory. For worktree-backed tasks, `taskRepoRoot` is `<baseRepoRoot>/.claude/worktrees/<task>`; for inline tasks, `taskRepoRoot` is the connected base repo.
 
 Because handoffs are scoped to `taskRepoRoot` without an extra task-name directory, VCM allows only one active inline task per connected repository. Use the default worktree mode for parallel tasks.
 

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

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

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

@@ -12,6 +12,10 @@ export function registerMessageRoutes(app, deps) {
             ...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);
+    });
     app.post("/api/tasks/:taskSlug/messages/:messageId/stage", async (request) => {
         const context = await getRouteContext(deps, request.params.taskSlug);
         return deps.messageService.stageMessage({

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

@@ -0,0 +1,33 @@
+import { VcmError } from "../errors.js";
+import { getTaskRuntimeRepoRoot } from "../services/task-service.js";
+export function registerRoundRoutes(app, deps) {
+    app.get("/api/tasks/:taskSlug/round", async (request) => {
+        const project = await requireCurrentProject(deps.projectService);
+        const config = await deps.projectService.loadConfig(project.repoRoot);
+        const task = await deps.taskService.loadTask(project.repoRoot, request.params.taskSlug);
+        const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+        const sessions = await deps.sessionService.listRoleSessions(project.repoRoot, request.params.taskSlug);
+        const messages = await deps.messageService.listMessages({
+            repoRoot: project.repoRoot,
+            stateRepoRoot: taskRepoRoot,
+            stateRoot: config.stateRoot,
+            taskSlug: request.params.taskSlug
+        });
+        return deps.roundService.getTaskRoundState({
+            taskSlug: request.params.taskSlug,
+            sessions,
+            messages
+        });
+    });
+}
+async function requireCurrentProject(projectService) {
+    const project = await projectService.getCurrentProject();
+    if (!project) {
+        throw new VcmError({
+            code: "PROJECT_NOT_CONNECTED",
+            message: "Connect a repository first.",
+            statusCode: 409
+        });
+    }
+    return project;
+}

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

@@ -15,6 +15,7 @@ export function registerSessionRoutes(app, deps) {
         const role = parseRole(request.params.role);
         const session = await deps.sessionService.stopRoleSession(project.repoRoot, request.params.taskSlug, role);
         await deps.translationService.stopSession(session.id);
+        deps.roundService.stopSession(session.id);
         return session;
     });
     app.post("/api/tasks/:taskSlug/sessions/:role/restart", async (request) => {
@@ -23,6 +24,7 @@ export function registerSessionRoutes(app, deps) {
         const existing = await deps.sessionService.getRoleSession(project.repoRoot, request.params.taskSlug, role);
         if (existing) {
             await deps.translationService.stopSession(existing.id, { clearCache: true });
+            deps.roundService.stopSession(existing.id);
         }
         return deps.sessionService.restartRoleSession(project.repoRoot, request.params.taskSlug, role, request.body);
     });

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

@@ -22,6 +22,7 @@ export function registerTaskRoutes(app, deps) {
         const task = await deps.taskService.loadTask(project.repoRoot, request.params.taskSlug);
         await stopRunningRoleSessions(deps, project.repoRoot, request.params.taskSlug);
         await deps.translationService.stopTask(getTaskRuntimeRepoRoot(task), request.params.taskSlug, { clearCache: true });
+        deps.roundService.stopTask(request.params.taskSlug);
         return deps.taskService.cleanupTask(project.repoRoot, request.params.taskSlug, request.body ?? {});
     });
 }

package/dist/backend/server.js

@@ -7,6 +7,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";
@@ -18,14 +19,17 @@ import { createProjectService } from "./services/project-service.js";
 import { createSessionRegistry } from "./runtime/session-registry.js";
 import { createSessionService } from "./services/session-service.js";
 import { createMessageService } from "./services/message-service.js";
+import { createRoundService } from "./services/round-service.js";
 import { createStatusService } from "./services/status-service.js";
 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";
+import { registerRoundRoutes } from "./api/round-routes.js";
 import { registerSessionRoutes } from "./api/session-routes.js";
 import { registerTaskRoutes } from "./api/task-routes.js";
 import { registerTranslationRoutes } from "./api/translation-routes.js";
@@ -46,6 +50,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,
@@ -56,13 +61,15 @@ export async function createServer(deps, options = {}) {
         taskService: deps.taskService,
         sessionService: deps.sessionService,
         statusService: deps.statusService,
-        translationService: deps.translationService
+        translationService: deps.translationService,
+        roundService: deps.roundService
     });
     registerSessionRoutes(app, {
         projectService: deps.projectService,
         sessionService: deps.sessionService,
         commandDispatcher: deps.commandDispatcher,
-        translationService: deps.translationService
+        translationService: deps.translationService,
+        roundService: deps.roundService
     });
     registerArtifactRoutes(app, {
         projectService: deps.projectService,
@@ -74,6 +81,13 @@ export async function createServer(deps, options = {}) {
         taskService: deps.taskService,
         messageService: deps.messageService
     });
+    registerRoundRoutes(app, {
+        projectService: deps.projectService,
+        taskService: deps.taskService,
+        sessionService: deps.sessionService,
+        messageService: deps.messageService,
+        roundService: deps.roundService
+    });
     registerTranslationRoutes(app, {
         projectService: deps.projectService,
         taskService: deps.taskService,
@@ -146,10 +160,18 @@ export function createDefaultServerDeps(options = {}) {
         sessionService,
         taskService
     });
+    const claudeHookService = createClaudeHookService({
+        projectService,
+        taskService,
+        sessionService,
+        messageService
+    });
+    const transcripts = createClaudeTranscriptService();
+    const roundService = createRoundService();
     const translationService = createTranslationService({
         runtime,
         sessionRegistry: registry,
-        transcripts: createClaudeTranscriptService(),
+        transcripts,
         sessionService,
         fs,
         projectService,
@@ -164,7 +186,9 @@ export function createDefaultServerDeps(options = {}) {
         artifactService,
         harnessService,
         commandDispatcher,
+        claudeHookService,
         messageService,
+        roundService,
         statusService,
         translationService,
         runtime

package/dist/backend/services/app-settings-service.js

@@ -180,7 +180,8 @@ function normalizeSettingsFile(input) {
 function normalizePreferences(input) {
     const candidate = isObject(input) ? input : {};
     return {
-        themeMode: normalizeThemeMode(candidate.themeMode)
+        themeMode: normalizeThemeMode(candidate.themeMode),
+        roundCompletionAlerts: candidate.roundCompletionAlerts !== false
     };
 }
 function normalizeThemeMode(input) {

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

@@ -0,0 +1,70 @@
+import { isRoleName } from "../../shared/constants.js";
+import { VcmError } from "../errors.js";
+import { getTaskRuntimeRepoRoot } from "./task-service.js";
+export function createClaudeHookService(deps) {
+    return {
+        async handleHook(input) {
+            if (!isRoleName(input.role)) {
+                throw new VcmError({
+                    code: "HOOK_ROLE_INVALID",
+                    message: `Unknown hook role: ${input.role}`,
+                    statusCode: 400
+                });
+            }
+            const eventName = parseHookEventName(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)
+            });
+            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;
+            }
+            return {
+                ok: true,
+                eventName,
+                taskSlug: input.taskSlug,
+                role: input.role,
+                sessionUpdated: Boolean(session),
+                submittedMessageId
+            };
+        }
+    };
+}
+function parseHookEventName(value) {
+    if (value === "UserPromptSubmit" || value === "Stop") {
+        return value;
+    }
+    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."
+    });
+}
+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 [ -n \"${VCM_CTL_COMMAND:-}\" ]; then eval \"$VCM_CTL_COMMAND hook-event\"; else vcmctl hook-event; fi'";
+const VCM_HOOK_EVENTS = ["UserPromptSubmit", "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,97 @@ 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 UserPromptSubmit/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 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");
+    });
+}
+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---`;
 }