peaks-loop 3.0.0

package/dist/src/services/fuzzy-matching/fzf-pick-service.js

@@ -0,0 +1,158 @@
+/**
+ * Generic fzf binary picker (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Promoted from `src/services/slice/slice-pick-service.ts` (which is
+ * the only prior caller). Encapsulates the canonical fzf integration
+ * pattern: format items as one-line text, spawn `fzf --multi`, parse
+ * the multi-selection, write a `<list-id>-picked.json` artifact.
+ *
+ * Two distinct things live in `src/services/fuzzy-matching/`:
+ *  - `fuzzy-match-service.ts` — in-process fzf *npm package* (the
+ *    Fzf class). Used by `memory search` / `retrospective search`.
+ *  - `fzf-pick-service.ts`    — spawns the fzf *binary* for
+ *    interactive TTY multi-select. Used by `peaks slice pick`,
+ *    `peaks memory list --pick`, `peaks retrospective index --pick`.
+ *
+ * The two are independent (one is a library, the other spawns a CLI);
+ * do not merge them. fzf-for-js returns positions; the binary returns
+ * raw lines. Different output shapes → different consumers.
+ *
+ * Source-of-truth: the binary is the *consumer* of the formatter
+ * output, not an input. Each caller injects its own `formatLine` and
+ * `parseLine` so a future swap to skim/peco is a one-line change per
+ * caller, not a refactor of this service.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const MIN_FZF_VERSION = '0.38';
+const SPAWN_TIMEOUT_MS = 60_000;
+const MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/**
+ * Pick a subset of `items` interactively via fzf. The full flow:
+ *   1. Check fzf presence + version.
+ *   2. Format items as one-line text (caller's formatLine).
+ *   3. Spawn `fzf --multi` (or test override).
+ *   4. Parse the multi-selection back into T[] (caller's parseLine).
+ *   5. Write `<outputPath>` with the picked + meta + fzfVersion.
+ *
+ * Failure modes:
+ *   - fzf missing → throws with `brew install fzf | apt-get install fzf` hint.
+ *   - fzf version too old → throws.
+ *   - fzf exits 130 (Esc) → returns `{ picked: [], outputPath, fzfVersion }` (NOT thrown).
+ *   - parseLine returns null for a line → silently dropped (line ignored).
+ */
+export async function pickFromList(options) {
+    const fzfBin = options.fzfBin ?? 'fzf';
+    const fzfVersion = checkFzfVersion(fzfBin);
+    if (options.items.length === 0) {
+        // Nothing to pick from. Still write an empty picked artifact so
+        // downstream commands have a stable file contract.
+        const emptyPayload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked: [] };
+        writeArtifact(options.outputPath, emptyPayload);
+        return { picked: [], outputPath: options.outputPath, fzfVersion };
+    }
+    const fzfInput = options.items.map(options.formatLine).join('\n');
+    const args = [];
+    args.push(options.multi === false ? '--no-multi' : '--multi');
+    args.push(`--prompt=${options.prompt ?? 'pick> '}`);
+    if (options.preview === true) {
+        args.push('--preview', 'cat');
+    }
+    let stdout;
+    if (options.overrideStdin !== undefined) {
+        stdout = options.overrideStdin;
+    }
+    else {
+        try {
+            stdout = execFileSync(fzfBin, args, {
+                input: fzfInput,
+                cwd: options.projectRoot,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: false,
+                timeout: SPAWN_TIMEOUT_MS,
+                maxBuffer: MAX_BUFFER_BYTES
+            }).toString('utf8');
+        }
+        catch (error) {
+            const err = error;
+            if (err.status === 130) {
+                stdout = ''; // user pressed Esc
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const selectedLines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const seen = new Set();
+    const picked = [];
+    for (const line of selectedLines) {
+        const item = options.parseLine(line);
+        if (item === null)
+            continue;
+        // Dedup by JSON serialization (caller's T may not be hashable otherwise).
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        picked.push(item);
+    }
+    const payload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked };
+    writeArtifact(options.outputPath, payload);
+    return { picked, outputPath: options.outputPath, fzfVersion };
+}
+function checkFzfVersion(fzfBin) {
+    let stdout;
+    try {
+        stdout = execFileSync(fzfBin, ['--version'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+            timeout: 5_000
+        }).toString('utf8');
+    }
+    catch (error) {
+        if (isEnoent(error) || isCommandNotFound(error)) {
+            throw new Error(`fzf binary not found. Install with: brew install fzf  (or apt: apt-get install fzf). ` +
+                `fzf >= ${MIN_FZF_VERSION} is required for interactive list picking.`);
+        }
+        throw error;
+    }
+    const version = stdout.trim().split('\n')[0] ?? '';
+    if (compareVersions(version, MIN_FZF_VERSION) < 0) {
+        throw new Error(`fzf version ${version} is older than required ${MIN_FZF_VERSION}`);
+    }
+    return version;
+}
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((p) => parseInt(p, 10) || 0);
+    const bParts = b.split('.').map((p) => parseInt(p, 10) || 0);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i += 1) {
+        const av = aParts[i] ?? 0;
+        const bv = bParts[i] ?? 0;
+        if (av < bv)
+            return -1;
+        if (av > bv)
+            return 1;
+    }
+    return 0;
+}
+function isEnoent(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    return error.code === 'ENOENT';
+}
+function isCommandNotFound(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    const msg = error.message ?? '';
+    return /command not found|not found/i.test(msg);
+}
+function writeArtifact(outputPath, payload) {
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf8');
+}

package/dist/src/services/fuzzy-matching/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Options for the generic fuzzy-match kernel.
+ */
+export interface FuzzyMatchOptions {
+    /** Maximum number of matches to return. Default 6. */
+    limit?: number;
+    /** When true, matching is case-sensitive. Default false (smart-case). */
+    caseSensitive?: boolean;
+}
+/**
+ * A single fuzzy-match hit. `item` is the original entry; `score` is
+ * normalized to [0, 1] with the top of the current batch at 1.0;
+ * `positions` is the set of char indices in the searchable text that
+ * contributed to the match.
+ */
+export interface FuzzyMatchResult<T> {
+    item: T;
+    score: number;
+    positions: number[];
+}

package/dist/src/services/fuzzy-matching/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/handoff/handoff-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare class IncompleteHandoffError extends Error {
+    readonly code: "INCOMPLETE_HANDOFF";
+    constructor(message: string);
+}
+export interface ParsedHandoff {
+    readonly frontmatter: HandoffFrontmatter;
+    readonly body: string;
+}
+export declare function parseHandoff(filePath: string): ParsedHandoff;

package/dist/src/services/handoff/handoff-parser.js

@@ -0,0 +1,69 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+export class IncompleteHandoffError extends Error {
+    code = 'INCOMPLETE_HANDOFF';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteHandoffError';
+    }
+}
+const REQUIRED_FIELDS = [
+    'rid',
+    'slice_id',
+    'agent_id',
+    'schema_version',
+    'status',
+    'created_at'
+];
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+export function parseHandoff(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return legacyDefaults(content);
+    }
+    const [, yamlContent, body] = match;
+    const parsed = parseYaml(yamlContent ?? '');
+    if (parsed === null || parsed === undefined) {
+        return legacyDefaults(content);
+    }
+    const missing = REQUIRED_FIELDS.filter((f) => parsed[f] === undefined);
+    if (missing.length > 0) {
+        throw new IncompleteHandoffError(`Missing required frontmatter fields: ${missing.join(', ')}`);
+    }
+    return {
+        frontmatter: parsed,
+        body: body ?? ''
+    };
+}
+function legacyDefaults(content) {
+    return {
+        frontmatter: {
+            rid: 'unknown',
+            slice_id: 'unknown',
+            agent_id: 'unknown',
+            schema_version: '0',
+            status: 'unknown',
+            created_at: new Date(0).toISOString()
+        },
+        body: content
+    };
+}

package/dist/src/services/handoff/handoff-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export type HandoffStatus = 'done' | 'failed' | 'partial' | 'blocked' | 'unknown';
+export type HandoffTestResult = 'pass' | 'fail' | 'inconclusive' | null;
+export type HandoffSchemaVersion = '0' | '1';
+export interface HandoffFrontmatter {
+    readonly rid: string;
+    readonly slice_id: string;
+    readonly agent_id: string;
+    readonly schema_version: HandoffSchemaVersion;
+    readonly status: HandoffStatus;
+    readonly created_at: string;
+    readonly duration_seconds?: number;
+    readonly files_changed?: readonly string[];
+    readonly lines_added?: number;
+    readonly lines_removed?: number;
+    readonly test_result?: HandoffTestResult;
+    readonly coverage?: number;
+    readonly errors?: readonly string[];
+    readonly warnings?: readonly string[];
+    readonly blockers?: readonly string[];
+    readonly upstream_dependencies?: readonly string[];
+}

package/dist/src/services/handoff/handoff-types.js

@@ -0,0 +1,19 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export {};

package/dist/src/services/handoff/handoff-writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare function writeHandoff(filePath: string, frontmatter: HandoffFrontmatter, body: string): void;

package/dist/src/services/handoff/handoff-writer.js

@@ -0,0 +1,30 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import { writeFileSync } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+const FRONTMATTER_OPEN = '---\n';
+const FRONTMATTER_CLOSE = '\n---\n\n';
+export function writeHandoff(filePath, frontmatter, body) {
+    const yamlStr = stringifyYaml(frontmatter).trimEnd();
+    const content = `${FRONTMATTER_OPEN}${yamlStr}${FRONTMATTER_CLOSE}${body}`;
+    writeFileSync(filePath, content, 'utf8');
+}

package/dist/src/services/hooks/output.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Slice 003-2026-06-16-hook-governance — single source of truth for the
+ * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
+ *
+ * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
+ * that every peaks-managed hook command MUST follow. Centralising the
+ * contract here lets us:
+ *   1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
+ *   2. Add a new helper (e.g. emitAsk) without changing every call site.
+ *   3. Stop hand-rolling the deny JSON in gate-commands.ts / hook-handle.ts,
+ *      which historically drifted into "PreToolUse:Bash hook error" noise.
+ *
+ * The contract (intentionally redundant with the doc; the doc is for humans,
+ * this is for the type checker):
+ *
+ *   emitHint(io, text)
+ *     - Writes `text` to io.stderr with a trailing newline.
+ *     - Does NOT write to io.stdout (the host reads stdout as the decision
+ *       signal; a hint on stdout is interpreted as a malformed decision).
+ *     - Does NOT set a non-zero process.exitCode. A hint is diagnostic only;
+ *       it must not change the host's permission decision.
+ *     - Empty `text` is a no-op (skips both the write and the trailing
+ *       newline so we never pollute stderr with blank lines).
+ *
+ *   emitBlock(io, reason)
+ *     - Builds the Claude-Code-shaped deny JSON:
+ *         { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *                                   "permissionDecision": "deny",
+ *                                   "permissionDecisionReason": <reason> } }
+ *       JSON.stringify is the canonical escape for the reason; quotes,
+ *       backslashes, and newlines inside the reason are preserved.
+ *     - Writes the serialized JSON to io.stdout with a trailing newline.
+ *     - Sets process.exitCode = 2. Claude Code treats exit-2 as the
+ *       "block" signal (see [Fact-Forcing Gate] note in .claude/HOOKS.md);
+ *       the JSON on stdout is the human-readable reason for the LLM.
+ *     - Surfaces the reason to io.stderr so an operator running the
+ *       hook command directly (or the LLM inspecting logs) can see
+ *       WHY the tool was blocked, not just THAT it was blocked.
+ *
+ *   emitDecision(io, decision)
+ *     - Writes the caller-provided decision JSON to io.stdout with a
+ *       trailing newline and returns the serialized string. Used by
+ *       IDE adapters that produce a different shape (e.g. Trae uses
+ *       hookEventName='beforeToolCall' instead of 'PreToolUse'). The
+ *       helper is intentionally shape-agnostic: the caller is the
+ *       adapter's `formatDecisionResponse`, which already knows the
+ *       IDE-specific shape.
+ *     - Does NOT set a non-zero process.exitCode. The decision is
+ *       communicated entirely via the stdout JSON; the host reads
+ *       permissionDecision='deny' to block. Setting exit=2 on top
+ *       of the JSON would be double-signaling.
+ *
+ * Platform notes:
+ *   - The contract is platform-independent. The helpers write to ProgramIO
+ *     (stdout / stderr) only; no path separators, no shell escaping, no
+ *     line-ending variants. The cross-platform contract test pins this.
+ *   - On win32, Node's process.stdout and process.stderr are binary-safe
+ *     and UTF-8; do not introduce \r\n anywhere. The contract is LF.
+ */
+import type { ProgramIO } from '../../cli/cli-helpers.js';
+/** Exit code the host treats as a hard block (Claude Code convention). */
+export declare const HOOK_BLOCK_EXIT_CODE = 2;
+/** Canonical Claude-Code hook event name. */
+export declare const CLAUDE_CODE_HOOK_EVENT = "PreToolUse";
+/** Permissive decision shape — anything JSON-serialisable. */
+export type DecisionShape = Record<string, unknown>;
+/**
+ * Hint — diagnostic, stderr-only, never affects the host decision.
+ * Returns the bytes written to stderr (or '' for an empty hint).
+ */
+export declare function emitHint(io: ProgramIO, text: string): string;
+/** Result of a block emission — the bytes written to stdout and the original reason. */
+export type EmitBlockResult = {
+    readonly stdout: string;
+    readonly reason: string;
+};
+/**
+ * Block — deny a tool call. Writes the Claude-Code-shaped deny JSON to
+ * stdout, sets process.exitCode = 2, and surfaces the reason to stderr.
+ */
+export declare function emitBlock(io: ProgramIO, reason: string): EmitBlockResult;
+/**
+ * Decision — write a caller-built decision object to stdout. Returns the
+ * serialized bytes so callers can log / assert on the exact string.
+ *
+ * Accepts either a plain object (canonical path; the helper does the
+ * JSON.stringify) or a pre-serialized string (used by adapter dispatch
+ * where `formatDecisionResponse` already serialized the IDE-shaped
+ * envelope). The string form is the legacy escape hatch and should not
+ * be used for new code.
+ */
+export declare function emitDecision(io: ProgramIO, decision: DecisionShape | string): string;

package/dist/src/services/hooks/output.js

@@ -0,0 +1,111 @@
+/**
+ * Slice 003-2026-06-16-hook-governance — single source of truth for the
+ * peaks hook output contract. See `.claude/HOOKS.md` for the canonical doc.
+ *
+ * Three helpers, one job: enforce the stdout/stderr/exit-code discipline
+ * that every peaks-managed hook command MUST follow. Centralising the
+ * contract here lets us:
+ *   1. Pin the contract in cross-platform tests (tests/unit/hooks/contract.test.ts).
+ *   2. Add a new helper (e.g. emitAsk) without changing every call site.
+ *   3. Stop hand-rolling the deny JSON in gate-commands.ts / hook-handle.ts,
+ *      which historically drifted into "PreToolUse:Bash hook error" noise.
+ *
+ * The contract (intentionally redundant with the doc; the doc is for humans,
+ * this is for the type checker):
+ *
+ *   emitHint(io, text)
+ *     - Writes `text` to io.stderr with a trailing newline.
+ *     - Does NOT write to io.stdout (the host reads stdout as the decision
+ *       signal; a hint on stdout is interpreted as a malformed decision).
+ *     - Does NOT set a non-zero process.exitCode. A hint is diagnostic only;
+ *       it must not change the host's permission decision.
+ *     - Empty `text` is a no-op (skips both the write and the trailing
+ *       newline so we never pollute stderr with blank lines).
+ *
+ *   emitBlock(io, reason)
+ *     - Builds the Claude-Code-shaped deny JSON:
+ *         { "hookSpecificOutput": { "hookEventName": "PreToolUse",
+ *                                   "permissionDecision": "deny",
+ *                                   "permissionDecisionReason": <reason> } }
+ *       JSON.stringify is the canonical escape for the reason; quotes,
+ *       backslashes, and newlines inside the reason are preserved.
+ *     - Writes the serialized JSON to io.stdout with a trailing newline.
+ *     - Sets process.exitCode = 2. Claude Code treats exit-2 as the
+ *       "block" signal (see [Fact-Forcing Gate] note in .claude/HOOKS.md);
+ *       the JSON on stdout is the human-readable reason for the LLM.
+ *     - Surfaces the reason to io.stderr so an operator running the
+ *       hook command directly (or the LLM inspecting logs) can see
+ *       WHY the tool was blocked, not just THAT it was blocked.
+ *
+ *   emitDecision(io, decision)
+ *     - Writes the caller-provided decision JSON to io.stdout with a
+ *       trailing newline and returns the serialized string. Used by
+ *       IDE adapters that produce a different shape (e.g. Trae uses
+ *       hookEventName='beforeToolCall' instead of 'PreToolUse'). The
+ *       helper is intentionally shape-agnostic: the caller is the
+ *       adapter's `formatDecisionResponse`, which already knows the
+ *       IDE-specific shape.
+ *     - Does NOT set a non-zero process.exitCode. The decision is
+ *       communicated entirely via the stdout JSON; the host reads
+ *       permissionDecision='deny' to block. Setting exit=2 on top
+ *       of the JSON would be double-signaling.
+ *
+ * Platform notes:
+ *   - The contract is platform-independent. The helpers write to ProgramIO
+ *     (stdout / stderr) only; no path separators, no shell escaping, no
+ *     line-ending variants. The cross-platform contract test pins this.
+ *   - On win32, Node's process.stdout and process.stderr are binary-safe
+ *     and UTF-8; do not introduce \r\n anywhere. The contract is LF.
+ */
+/** Exit code the host treats as a hard block (Claude Code convention). */
+export const HOOK_BLOCK_EXIT_CODE = 2;
+/** Canonical Claude-Code hook event name. */
+export const CLAUDE_CODE_HOOK_EVENT = 'PreToolUse';
+/**
+ * Hint — diagnostic, stderr-only, never affects the host decision.
+ * Returns the bytes written to stderr (or '' for an empty hint).
+ */
+export function emitHint(io, text) {
+    if (text.length === 0) {
+        return '';
+    }
+    const line = text.endsWith('\n') ? text : `${text}\n`;
+    io.stderr(line);
+    return line;
+}
+/**
+ * Block — deny a tool call. Writes the Claude-Code-shaped deny JSON to
+ * stdout, sets process.exitCode = 2, and surfaces the reason to stderr.
+ */
+export function emitBlock(io, reason) {
+    const safeReason = reason.length > 0 ? reason : 'denied by peaks';
+    const payload = {
+        hookSpecificOutput: {
+            hookEventName: CLAUDE_CODE_HOOK_EVENT,
+            permissionDecision: 'deny',
+            permissionDecisionReason: safeReason
+        }
+    };
+    const serialized = JSON.stringify(payload);
+    io.stdout(serialized);
+    io.stdout('\n');
+    io.stderr(`peaks: ${safeReason}\n`);
+    process.exitCode = HOOK_BLOCK_EXIT_CODE;
+    return { stdout: serialized, reason: safeReason };
+}
+/**
+ * Decision — write a caller-built decision object to stdout. Returns the
+ * serialized bytes so callers can log / assert on the exact string.
+ *
+ * Accepts either a plain object (canonical path; the helper does the
+ * JSON.stringify) or a pre-serialized string (used by adapter dispatch
+ * where `formatDecisionResponse` already serialized the IDE-shaped
+ * envelope). The string form is the legacy escape hatch and should not
+ * be used for new code.
+ */
+export function emitDecision(io, decision) {
+    const serialized = typeof decision === 'string' ? decision : JSON.stringify(decision);
+    io.stdout(serialized);
+    io.stdout('\n');
+    return serialized;
+}

package/dist/src/services/hooks/presence-marker-detector.d.ts

@@ -0,0 +1,16 @@
+export type DetectPresenceMarkerInput = {
+    project: string;
+    latestAssistantMessage: string;
+};
+export type DetectPresenceMarkerResult = {
+    active: boolean;
+    skill?: string;
+    markerFound: boolean;
+    warning?: string;
+};
+export type PresenceMarkerWarning = (typeof PRESENCE_MARKER_WARNING)[number];
+export declare const PRESENCE_MARKER_WARNING: readonly ["Peaks skill context may have been lost from this conversation; please re-invoke /peaks-<skill>."];
+/**
+ * Pure read-only presence-marker detection. No I/O side effects.
+ */
+export declare function detectPresenceMarker(input: DetectPresenceMarkerInput): DetectPresenceMarkerResult;