codeep 1.3.42 → 2.0.0

package/dist/utils/context.js

@@ -113,6 +113,63 @@ export function getAllContexts() {
         return [];
     }
 }
+/**
+ * AI-powered compaction of a conversation history.
+ *
+ * Used by the `/compact` slash command. Sends the older portion of the
+ * conversation to the active provider with a summarization prompt, then
+ * replaces those messages with a single system message containing the
+ * summary. Keeps the last `keepRecent` messages verbatim so the
+ * conversation can continue without losing the most recent context.
+ *
+ * Returns the same `history` (untouched) if there isn't enough to
+ * meaningfully compact.
+ */
+export async function compactHistory(history, options = {}) {
+    const keepRecent = options.keepRecent ?? 4;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    // Need at least one full exchange to compact (user + assistant) plus the
+    // recent tail — otherwise compaction is just overhead.
+    if (history.length <= keepRecent + 2) {
+        return { compacted: history, replaced: 0, summary: '' };
+    }
+    const toCompact = history.slice(0, history.length - keepRecent);
+    const recent = history.slice(history.length - keepRecent);
+    const transcript = toCompact
+        .map(m => `[${m.role.toUpperCase()}]\n${m.content}`)
+        .join('\n\n---\n\n');
+    const prompt = 'Summarize the following conversation between a user and a coding assistant.' +
+        ' Capture concisely: (1) what the user was trying to accomplish, (2) key decisions and rationale,' +
+        ' (3) files or components touched, (4) outstanding questions or unfinished work.' +
+        ' The summary will replace these messages in the agent\'s context, so include anything needed' +
+        ' to continue the work without re-reading the originals.\n\nConversation:\n\n' +
+        transcript;
+    // Cap how long we'll wait. /compact otherwise blocks the whole session
+    // with no way to interrupt (the regular /stop targets the agent loop,
+    // not arbitrary chat calls). If the user passed their own AbortSignal,
+    // combine it with our timer so either can cancel.
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+    const onExternalAbort = () => timeoutController.abort();
+    options.abortSignal?.addEventListener('abort', onExternalAbort);
+    try {
+        const { chat } = await import('../api/index.js');
+        const summary = await chat(prompt, [], undefined, undefined, options.projectContext ?? undefined, timeoutController.signal);
+        const summaryMessage = {
+            role: 'system',
+            content: `[Conversation compacted — ${toCompact.length} earlier message${toCompact.length === 1 ? '' : 's'} summarized below]\n\n${summary}`,
+        };
+        return {
+            compacted: [summaryMessage, ...recent],
+            replaced: toCompact.length,
+            summary,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        options.abortSignal?.removeEventListener('abort', onExternalAbort);
+    }
+}
 /**
  * Summarize messages for context persistence
  * Keeps recent messages and summarizes older ones

package/dist/utils/customCommands.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Custom slash commands.
+ *
+ * Users drop `.md` files in either:
+ *   - `<workspace>/.codeep/commands/<name>.md`  (project-scoped)
+ *   - `~/.codeep/commands/<name>.md`            (global, all projects)
+ *
+ * Each file becomes a `/<name>` slash command. Project files take precedence
+ * over global files with the same name.
+ *
+ * File format (frontmatter optional):
+ *
+ *   ---
+ *   description: Detailed security review of a file
+ *   aliases: [sec, secrev]
+ *   ---
+ *
+ *   Please perform a thorough security review of: {{args}}
+ *
+ * The body is expanded with the user's arguments and sent as a user message
+ * to the agent. Placeholders supported:
+ *   - `{{args}}` and `$ARGUMENTS` — full args string (Claude Code compat)
+ *   - `{{arg1}}` … `{{argN}}`     — positional args (1-indexed)
+ *
+ * Custom commands are not invoked automatically — they only fire when the
+ * user types `/<name>`. The agent never sees them in its tool catalog.
+ */
+export interface CustomCommand {
+    /** Slash name without the leading `/` */
+    name: string;
+    /** One-line description for /help and ACP autocomplete */
+    description: string;
+    /** Body text after frontmatter, with placeholders unresolved */
+    body: string;
+    /** Filesystem path the command was loaded from */
+    source: string;
+    /** 'project' if loaded from <workspace>/.codeep/commands, else 'global' */
+    scope: 'project' | 'global';
+    /** Optional alternative names that also trigger this command */
+    aliases: string[];
+}
+/**
+ * Load all custom commands available in this workspace.
+ * Project commands shadow global commands with the same name.
+ */
+export declare function loadCustomCommands(workspaceRoot?: string): CustomCommand[];
+/**
+ * Resolve a user-typed slash name to a custom command, checking primary
+ * name first then aliases. Project scope wins over global on collisions
+ * (handled inside loadCustomCommands).
+ */
+export declare function findCustomCommand(name: string, workspaceRoot?: string): CustomCommand | null;
+/**
+ * Expand `{{args}}`, `$ARGUMENTS`, and `{{argN}}` placeholders in the
+ * command body. If the body has no placeholders, the args are appended
+ * on a new line so the agent still sees them.
+ */
+export declare function expandCommand(cmd: CustomCommand, args: string[]): string;
+/**
+ * Render the catalog as a Markdown block for `/commands`.
+ */
+export declare function formatCommandList(commands: CustomCommand[]): string;

package/dist/utils/customCommands.js

@@ -0,0 +1,201 @@
+/**
+ * Custom slash commands.
+ *
+ * Users drop `.md` files in either:
+ *   - `<workspace>/.codeep/commands/<name>.md`  (project-scoped)
+ *   - `~/.codeep/commands/<name>.md`            (global, all projects)
+ *
+ * Each file becomes a `/<name>` slash command. Project files take precedence
+ * over global files with the same name.
+ *
+ * File format (frontmatter optional):
+ *
+ *   ---
+ *   description: Detailed security review of a file
+ *   aliases: [sec, secrev]
+ *   ---
+ *
+ *   Please perform a thorough security review of: {{args}}
+ *
+ * The body is expanded with the user's arguments and sent as a user message
+ * to the agent. Placeholders supported:
+ *   - `{{args}}` and `$ARGUMENTS` — full args string (Claude Code compat)
+ *   - `{{arg1}}` … `{{argN}}`     — positional args (1-indexed)
+ *
+ * Custom commands are not invoked automatically — they only fire when the
+ * user types `/<name>`. The agent never sees them in its tool catalog.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+/**
+ * Minimal YAML frontmatter parser — handles `key: value` and
+ * `key: [a, b, c]`. We deliberately avoid a YAML dependency because the
+ * surface area we care about is tiny.
+ */
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        return { meta: {}, body: raw };
+    const meta = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^\s*([a-zA-Z_][\w-]*)\s*:\s*(.*?)\s*$/);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        let value = kv[2];
+        const arr = value.match(/^\[(.*)\]$/);
+        if (arr) {
+            value = arr[1]
+                .split(',')
+                .map(s => s.trim().replace(/^["']|["']$/g, ''))
+                .filter(Boolean);
+        }
+        else {
+            value = value.replace(/^["']|["']$/g, '');
+        }
+        if (key === 'description' && typeof value === 'string')
+            meta.description = value;
+        if (key === 'aliases' && Array.isArray(value))
+            meta.aliases = value;
+    }
+    return { meta, body: match[2].trimStart() };
+}
+function loadFromDir(dir, scope) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const commands = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const fullPath = join(dir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                continue;
+            // Sanity ceiling — a slash-command template above 64KB is almost
+            // certainly someone dumping a doc in the wrong folder.
+            if (stat.size > 65_536)
+                continue;
+            const raw = readFileSync(fullPath, 'utf-8');
+            const { meta, body } = parseFrontmatter(raw);
+            const name = entry.replace(/\.md$/, '').toLowerCase();
+            if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+                continue; // names match `/foo-bar`
+            commands.push({
+                name,
+                description: meta.description ?? `Custom ${scope} command`,
+                body: body.trim(),
+                source: fullPath,
+                scope,
+                aliases: (meta.aliases ?? []).map(a => a.toLowerCase()).filter(a => /^[a-z0-9][a-z0-9-]*$/.test(a)),
+            });
+        }
+        catch {
+            // Skip unreadable / malformed files silently — they shouldn't block
+            // the rest of the catalog from loading.
+        }
+    }
+    return commands;
+}
+/**
+ * Load all custom commands available in this workspace.
+ * Project commands shadow global commands with the same name.
+ */
+export function loadCustomCommands(workspaceRoot) {
+    const global = loadFromDir(join(homedir(), '.codeep', 'commands'), 'global');
+    const project = workspaceRoot
+        ? loadFromDir(join(workspaceRoot, '.codeep', 'commands'), 'project')
+        : [];
+    // Project wins on name collisions; collapse to a single map keyed by name.
+    const byName = new Map();
+    for (const cmd of global)
+        byName.set(cmd.name, cmd);
+    for (const cmd of project)
+        byName.set(cmd.name, cmd);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve a user-typed slash name to a custom command, checking primary
+ * name first then aliases. Project scope wins over global on collisions
+ * (handled inside loadCustomCommands).
+ */
+export function findCustomCommand(name, workspaceRoot) {
+    const lower = name.toLowerCase();
+    const all = loadCustomCommands(workspaceRoot);
+    return all.find(c => c.name === lower || c.aliases.includes(lower)) ?? null;
+}
+/**
+ * Expand `{{args}}`, `$ARGUMENTS`, and `{{argN}}` placeholders in the
+ * command body. If the body has no placeholders, the args are appended
+ * on a new line so the agent still sees them.
+ */
+export function expandCommand(cmd, args) {
+    const joined = args.join(' ');
+    const hasPlaceholder = /\{\{args\}\}|\$ARGUMENTS|\{\{arg\d+\}\}/.test(cmd.body);
+    let expanded = cmd.body
+        .replace(/\{\{args\}\}/g, joined)
+        .replace(/\$ARGUMENTS/g, joined);
+    // Positional: {{arg1}}, {{arg2}}, ...
+    expanded = expanded.replace(/\{\{arg(\d+)\}\}/g, (_m, n) => {
+        const idx = parseInt(n, 10) - 1;
+        return args[idx] ?? '';
+    });
+    if (!hasPlaceholder && joined) {
+        expanded += `\n\n${joined}`;
+    }
+    return expanded;
+}
+/**
+ * Render the catalog as a Markdown block for `/commands`.
+ */
+export function formatCommandList(commands) {
+    if (!commands.length) {
+        return [
+            '_No custom commands yet._',
+            '',
+            'Create one by adding a Markdown file:',
+            '',
+            '- `<workspace>/.codeep/commands/<name>.md` — project-scoped',
+            '- `~/.codeep/commands/<name>.md` — global (all projects)',
+            '',
+            'Example:',
+            '',
+            '```markdown',
+            '---',
+            'description: Detailed security review of a file',
+            '---',
+            '',
+            'Please perform a thorough security review of: {{args}}',
+            '```',
+            '',
+            'Then call it as `/<name> <args>`.',
+        ].join('\n');
+    }
+    const projectCmds = commands.filter(c => c.scope === 'project');
+    const globalCmds = commands.filter(c => c.scope === 'global');
+    const lines = ['## Custom Commands', ''];
+    if (projectCmds.length) {
+        lines.push('**Project**');
+        for (const c of projectCmds) {
+            const aliasNote = c.aliases.length ? ` (aliases: ${c.aliases.map(a => `\`/${a}\``).join(', ')})` : '';
+            lines.push(`- \`/${c.name}\`${aliasNote} — ${c.description}`);
+        }
+        lines.push('');
+    }
+    if (globalCmds.length) {
+        lines.push('**Global**');
+        for (const c of globalCmds) {
+            const aliasNote = c.aliases.length ? ` (aliases: ${c.aliases.map(a => `\`/${a}\``).join(', ')})` : '';
+            lines.push(`- \`/${c.name}\`${aliasNote} — ${c.description}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/utils/hooks.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project-local lifecycle hooks.
+ *
+ * User drops executable shell scripts in `.codeep/hooks/<event>.sh` and Codeep
+ * runs them at the relevant moment during a session. Generalises what the
+ * `agentAutoCommit` and `agentAutoVerify` config flags do — anything those
+ * can do, a `post_edit` hook can do too, without a code change in the CLI.
+ *
+ * Supported events:
+ *
+ *   `pre_tool_call`   — fires before every tool execution. NON-ZERO exit
+ *                       BLOCKS the tool call (the agent gets a clear error
+ *                       message). Use for policy enforcement: block writes
+ *                       to certain paths, refuse risky commands, etc.
+ *
+ *   `post_edit`       — fires after a successful write_file or edit_file.
+ *                       Exit code is ignored (auto-format / auto-lint:
+ *                       failure shouldn't block the agent). Receives the
+ *                       file path. Use for prettier/eslint/gofmt.
+ *
+ *   `on_error`        — fires when a tool call returns success=false.
+ *                       Exit code ignored. Use for centralised logging
+ *                       or alerting.
+ *
+ *   `pre_commit`      — fires before the /commit skill stages anything.
+ *                       NON-ZERO exit BLOCKS the commit. Use for test
+ *                       runs, lint gates, etc.
+ *
+ * Environment variables every hook receives:
+ *   CODEEP_HOOK_EVENT     - one of the event names above
+ *   CODEEP_WORKSPACE      - workspace root absolute path
+ *   CODEEP_SESSION_ID     - current Codeep session id
+ *
+ * Event-specific extras:
+ *   pre_tool_call / on_error:
+ *     CODEEP_HOOK_TOOL    - tool name (read_file, write_file, …)
+ *     CODEEP_HOOK_PARAMS  - JSON-encoded tool parameters
+ *   post_edit:
+ *     CODEEP_HOOK_TOOL    - 'write_file' | 'edit_file'
+ *     CODEEP_HOOK_FILE    - absolute path of the file that was edited
+ *
+ * Security note: hooks run arbitrary shell. They are project-scoped — a
+ * cloned repo with hostile hooks would execute its scripts on the user's
+ * machine the first time they trigger an agent tool call. The welcome
+ * banner warns when hooks exist (see `summarizeHooks`); we do not run
+ * hooks from `~/.codeep/hooks/` (global) for that reason.
+ */
+export type HookEvent = 'pre_tool_call' | 'post_edit' | 'on_error' | 'pre_commit';
+export declare const HOOK_EVENTS: readonly HookEvent[];
+export interface HookContext {
+    event: HookEvent;
+    workspaceRoot: string;
+    sessionId?: string;
+    /** For pre_tool_call / on_error / post_edit */
+    toolName?: string;
+    /** For pre_tool_call / on_error */
+    toolParams?: Record<string, unknown>;
+    /** For post_edit */
+    filePath?: string;
+}
+export interface HookResult {
+    /** True if a hook script existed and was actually invoked. */
+    executed: boolean;
+    /** Exit code, or 0 if no hook was present. */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True if this hook event blocks downstream work AND the hook failed. */
+    blocked: boolean;
+    /** Path that was executed (useful for error messages). */
+    scriptPath?: string;
+}
+/**
+ * Execute the configured hook for an event, if any. Returns `executed: false`
+ * if no script exists. Caller is responsible for checking `blocked` and
+ * aborting the parent action when it's true.
+ */
+export declare function runHook(ctx: HookContext, opts?: {
+    timeoutMs?: number;
+}): HookResult;
+/**
+ * Inspect a workspace and return which hook scripts are installed.
+ * Used by the welcome banner and `/hooks` slash command.
+ */
+export declare function listInstalledHooks(workspaceRoot: string): {
+    event: HookEvent;
+    scriptPath: string;
+}[];
+/**
+ * Render an installed-hook list as Markdown for `/hooks` output.
+ */
+export declare function formatHookList(hooks: ReturnType<typeof listInstalledHooks>): string;
+/**
+ * Short one-line summary used in the welcome banner when hooks are present.
+ * Returns empty string if no hooks installed.
+ */
+export declare function summarizeHooks(workspaceRoot: string): string;

package/dist/utils/hooks.js

@@ -0,0 +1,223 @@
+/**
+ * Project-local lifecycle hooks.
+ *
+ * User drops executable shell scripts in `.codeep/hooks/<event>.sh` and Codeep
+ * runs them at the relevant moment during a session. Generalises what the
+ * `agentAutoCommit` and `agentAutoVerify` config flags do — anything those
+ * can do, a `post_edit` hook can do too, without a code change in the CLI.
+ *
+ * Supported events:
+ *
+ *   `pre_tool_call`   — fires before every tool execution. NON-ZERO exit
+ *                       BLOCKS the tool call (the agent gets a clear error
+ *                       message). Use for policy enforcement: block writes
+ *                       to certain paths, refuse risky commands, etc.
+ *
+ *   `post_edit`       — fires after a successful write_file or edit_file.
+ *                       Exit code is ignored (auto-format / auto-lint:
+ *                       failure shouldn't block the agent). Receives the
+ *                       file path. Use for prettier/eslint/gofmt.
+ *
+ *   `on_error`        — fires when a tool call returns success=false.
+ *                       Exit code ignored. Use for centralised logging
+ *                       or alerting.
+ *
+ *   `pre_commit`      — fires before the /commit skill stages anything.
+ *                       NON-ZERO exit BLOCKS the commit. Use for test
+ *                       runs, lint gates, etc.
+ *
+ * Environment variables every hook receives:
+ *   CODEEP_HOOK_EVENT     - one of the event names above
+ *   CODEEP_WORKSPACE      - workspace root absolute path
+ *   CODEEP_SESSION_ID     - current Codeep session id
+ *
+ * Event-specific extras:
+ *   pre_tool_call / on_error:
+ *     CODEEP_HOOK_TOOL    - tool name (read_file, write_file, …)
+ *     CODEEP_HOOK_PARAMS  - JSON-encoded tool parameters
+ *   post_edit:
+ *     CODEEP_HOOK_TOOL    - 'write_file' | 'edit_file'
+ *     CODEEP_HOOK_FILE    - absolute path of the file that was edited
+ *
+ * Security note: hooks run arbitrary shell. They are project-scoped — a
+ * cloned repo with hostile hooks would execute its scripts on the user's
+ * machine the first time they trigger an agent tool call. The welcome
+ * banner warns when hooks exist (see `summarizeHooks`); we do not run
+ * hooks from `~/.codeep/hooks/` (global) for that reason.
+ */
+import { existsSync, readdirSync, statSync, accessSync, constants } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+export const HOOK_EVENTS = ['pre_tool_call', 'post_edit', 'on_error', 'pre_commit'];
+/** Events whose non-zero exit aborts the action that triggered them. */
+const BLOCKING_EVENTS = new Set(['pre_tool_call', 'pre_commit']);
+const NOT_EXECUTED = { executed: false, exitCode: 0, stdout: '', stderr: '', blocked: false };
+function getHooksDir(workspaceRoot) {
+    return join(workspaceRoot, '.codeep', 'hooks');
+}
+function findHookScript(workspaceRoot, event) {
+    const dir = getHooksDir(workspaceRoot);
+    if (!existsSync(dir))
+        return null;
+    // Allow `.sh` and bare (no-extension) executable; users sometimes prefer
+    // `.codeep/hooks/post_edit` over `post_edit.sh`. Try both.
+    for (const name of [`${event}.sh`, event]) {
+        const full = join(dir, name);
+        if (!existsSync(full))
+            continue;
+        try {
+            const stat = statSync(full);
+            if (!stat.isFile())
+                continue;
+            // Must be executable by the current user — otherwise we'd surprise
+            // them with a hook that silently does nothing.
+            accessSync(full, constants.X_OK);
+            return full;
+        }
+        catch {
+            // Not executable or unreadable — try next candidate.
+        }
+    }
+    return null;
+}
+/**
+ * Execute the configured hook for an event, if any. Returns `executed: false`
+ * if no script exists. Caller is responsible for checking `blocked` and
+ * aborting the parent action when it's true.
+ */
+export function runHook(ctx, opts = {}) {
+    const script = findHookScript(ctx.workspaceRoot, ctx.event);
+    if (!script)
+        return NOT_EXECUTED;
+    const env = {
+        ...process.env,
+        CODEEP_HOOK_EVENT: ctx.event,
+        CODEEP_WORKSPACE: ctx.workspaceRoot,
+    };
+    if (ctx.sessionId)
+        env.CODEEP_SESSION_ID = ctx.sessionId;
+    if (ctx.toolName)
+        env.CODEEP_HOOK_TOOL = ctx.toolName;
+    if (ctx.toolParams) {
+        // Cap env var size — most shells choke at ~128KB total env, and a
+        // `write_file` with a 100KB content field would single-handedly blow
+        // past that. We truncate the serialised JSON instead and append a
+        // marker so hook scripts can detect overflow if they care.
+        const PARAMS_CAP = 8192;
+        let serialized = JSON.stringify(ctx.toolParams);
+        if (serialized.length > PARAMS_CAP) {
+            serialized = serialized.slice(0, PARAMS_CAP) + '...[truncated]';
+        }
+        env.CODEEP_HOOK_PARAMS = serialized;
+    }
+    if (ctx.filePath)
+        env.CODEEP_HOOK_FILE = ctx.filePath;
+    // 30s ceiling so a runaway lint / test command can't wedge the agent
+    // loop. Configurable per-call so tests can use a tight timeout.
+    const timeout = opts.timeoutMs ?? 30_000;
+    let proc;
+    try {
+        proc = spawnSync(script, [], {
+            cwd: ctx.workspaceRoot,
+            env,
+            timeout,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        // Should be rare — spawnSync usually returns a result rather than throwing.
+        return {
+            executed: true,
+            exitCode: 1,
+            stdout: '',
+            stderr: `hook spawn failed: ${err.message}`,
+            blocked: BLOCKING_EVENTS.has(ctx.event),
+            scriptPath: script,
+        };
+    }
+    const exitCode = proc.status ?? (proc.error ? 1 : 0);
+    const stdout = proc.stdout ?? '';
+    const stderr = proc.stderr ?? '';
+    const blocked = BLOCKING_EVENTS.has(ctx.event) && exitCode !== 0;
+    return { executed: true, exitCode, stdout, stderr, blocked, scriptPath: script };
+}
+/**
+ * Inspect a workspace and return which hook scripts are installed.
+ * Used by the welcome banner and `/hooks` slash command.
+ */
+export function listInstalledHooks(workspaceRoot) {
+    const dir = getHooksDir(workspaceRoot);
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    // Build a set of which events have a script — try both `<event>.sh` and
+    // bare-name forms, mirroring findHookScript.
+    const seen = new Set();
+    const out = [];
+    for (const event of HOOK_EVENTS) {
+        for (const candidate of [`${event}.sh`, event]) {
+            if (!entries.includes(candidate))
+                continue;
+            const full = join(dir, candidate);
+            try {
+                if (!statSync(full).isFile())
+                    continue;
+                accessSync(full, constants.X_OK);
+                if (seen.has(event))
+                    break;
+                seen.add(event);
+                out.push({ event, scriptPath: full });
+                break;
+            }
+            catch {
+                // Skip unreadable / non-executable.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Render an installed-hook list as Markdown for `/hooks` output.
+ */
+export function formatHookList(hooks) {
+    if (hooks.length === 0) {
+        return [
+            '_No hooks installed in this workspace._',
+            '',
+            'Drop an executable script in `.codeep/hooks/<event>.sh` to enable one. Supported events:',
+            '',
+            ...HOOK_EVENTS.map(e => `- \`${e}\`${BLOCKING_EVENTS.has(e) ? '  *(non-zero exit blocks the action)*' : ''}`),
+            '',
+            'Example — auto-format on save:',
+            '',
+            '```bash',
+            '#!/bin/bash',
+            '# .codeep/hooks/post_edit.sh',
+            'prettier --write "$CODEEP_HOOK_FILE" 2>/dev/null',
+            '```',
+        ].join('\n');
+    }
+    const lines = ['## Installed hooks', ''];
+    for (const h of hooks) {
+        const tag = BLOCKING_EVENTS.has(h.event) ? ' *(blocking)*' : '';
+        lines.push(`- \`${h.event}\`${tag} — \`${h.scriptPath}\``);
+    }
+    return lines.join('\n');
+}
+/**
+ * Short one-line summary used in the welcome banner when hooks are present.
+ * Returns empty string if no hooks installed.
+ */
+export function summarizeHooks(workspaceRoot) {
+    const hooks = listInstalledHooks(workspaceRoot);
+    if (hooks.length === 0)
+        return '';
+    return `${hooks.length} hook${hooks.length === 1 ? '' : 's'} active (${hooks.map(h => h.event).join(', ')})`;
+}