claude-git-hooks 2.35.2 → 2.43.0

package/lib/utils/analysis-engine.js

@@ -278,7 +278,8 @@ export const createEmptyResult = () => ({
  *
  * @param {Object} result - Analysis result
  */
-export const displayIssueSummary = (result) => {
+export const displayIssueSummary = (result, { silent = false } = {}) => {
+    if (silent) return;
     const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues || {};
     const total = blocker + critical + major + minor + info;
 
@@ -296,7 +297,8 @@ export const displayIssueSummary = (result) => {
  *
  * @param {Object} result - Analysis result from Claude
  */
-export const displayResults = (result) => {
+export const displayResults = (result, { silent = false } = {}) => {
+    if (silent) return;
     console.log();
     console.log('╔════════════════════════════════════════════════════════════════════╗');
     console.log('║                     CODE QUALITY ANALYSIS                          ║');
@@ -376,7 +378,7 @@ const ORCHESTRATOR_THRESHOLD = 3;
  * @returns {Promise<Object>} Analysis result
  */
 export const runAnalysis = async (filesData, config, options = {}) => {
-    const { saveDebug = config.system?.debug, hook = 'analysis' } = options;
+    const { saveDebug = config.system?.debug, hook = 'analysis', headless = false, costTracker = null } = options;
 
     if (filesData.length === 0) {
         logger.debug('analysis-engine - runAnalysis', 'No files to analyze');
@@ -396,7 +398,7 @@ export const runAnalysis = async (filesData, config, options = {}) => {
     if (useOrchestrator) {
         // Orchestrated parallel execution: Opus groups files semantically
         const orchestrationStart = Date.now();
-        const orchestration = await orchestrateBatches(filesData);
+        const orchestration = await orchestrateBatches(filesData, { headless });
         const orchestrationTime = Date.now() - orchestrationStart;
 
         const { batches, commonContext } = orchestration;
@@ -442,7 +444,9 @@ export const runAnalysis = async (filesData, config, options = {}) => {
                     timeout: config.analysis?.timeout,
                     model: batch.model,
                     saveDebug: false,
-                    telemetryContext
+                    telemetryContext,
+                    headless,
+                    costTracker
                 });
             })
         );
@@ -489,7 +493,9 @@ export const runAnalysis = async (filesData, config, options = {}) => {
         result = await analyzeCode(prompt, {
             timeout: config.analysis?.timeout,
             saveDebug,
-            telemetryContext
+            telemetryContext,
+            headless,
+            costTracker
         });
     }
 

package/lib/utils/claude-client.js

@@ -29,6 +29,8 @@ import {
 } from './claude-diagnostics.js';
 import { which } from './which-command.js';
 import { recordJsonParseFailure, recordBatchSuccess, rotateTelemetry } from './telemetry.js';
+import { CostTracker } from './cost-tracker.js';
+import { traceGeneration, flush as langfuseFlush } from './langfuse-tracer.js';
 
 /**
  * Custom error for Claude client failures
@@ -43,6 +45,24 @@ class ClaudeClientError extends Error {
     }
 }
 
+/**
+ * Model alias map — resolves shorthand names to full SDK model IDs.
+ * Env var overrides match Lumiere contract (CLAUDE_MODEL_HAIKU, CLAUDE_MODEL_SONNET, CLAUDE_MODEL_OPUS).
+ * Full model IDs (e.g., 'claude-sonnet-4-6') pass through unchanged.
+ */
+const MODEL_ALIASES = {
+    haiku: process.env.CLAUDE_MODEL_HAIKU || 'claude-haiku-4-5-20251001',
+    sonnet: process.env.CLAUDE_MODEL_SONNET || 'claude-sonnet-4-6',
+    opus: process.env.CLAUDE_MODEL_OPUS || 'claude-opus-4-6'
+};
+
+/**
+ * Resolves a model alias to a full model ID.
+ * @param {string} model - Alias ('sonnet') or full ID ('claude-sonnet-4-6')
+ * @returns {string} Full model ID
+ */
+const resolveModelAlias = (model) => MODEL_ALIASES[model] || model;
+
 /**
  * Detect if running on Windows
  * Why: Need to use 'wsl claude' instead of 'claude' on Windows
@@ -329,6 +349,145 @@ const getClaudeCommand = () => {
     return { command: 'claude', args: [] };
 };
 
+/**
+ * Executes a prompt via the Anthropic SDK (headless mode only).
+ *
+ * This is the execution backend for headless environments (ECS, CI) where no
+ * interactive Claude CLI session exists — only an ANTHROPIC_API_KEY. Activated
+ * when `options.headless === true` in `executeClaude`. (refs GH#133, enables CT-791)
+ *
+ * The SDK handles transient retries internally (2 automatic retries on rate
+ * limits, timeouts, and 5xx errors). Errors thrown from this function have
+ * already exhausted SDK-level retries and are marked `fromSDK: true` so that
+ * the outer `withRetry` does NOT retry them again.
+ *
+ * Model alias resolution: Accepts shorthand aliases ('sonnet', 'opus', 'haiku')
+ * and resolves them to full model IDs via MODEL_ALIASES. Env var overrides
+ * (CLAUDE_MODEL_SONNET, etc.) are supported.
+ *
+ * @param {string} prompt - Prompt text to send
+ * @param {Object} options - Execution options
+ * @param {string} options.model - Model name or alias (default: config.claude.defaultModel)
+ * @param {number} options.timeout - Timeout in milliseconds (default: 120000)
+ * @param {number} options.maxTokens - Max output tokens (default: 16384)
+ * @returns {Promise<string>} Raw text response
+ * @throws {ClaudeClientError} With context.errorInfo.fromSDK: true
+ */
+const _executeSDK = async (prompt, { model, timeout = 120000, maxTokens } = {}) => {
+    // Lazy-load SDK — not imported at module top to avoid requiring the package
+    // in CLI (non-headless) environments where it is not needed
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+
+    const resolvedModel = resolveModelAlias(model || config.claude?.defaultModel || 'sonnet');
+
+    logger.debug('claude-client - _executeSDK', 'Executing via Anthropic SDK (headless)', {
+        promptLength: prompt.length,
+        model: resolvedModel,
+        timeout,
+        maxTokens: maxTokens || 16384
+    });
+
+    const startTime = Date.now();
+
+    try {
+        const client = new Anthropic({ timeout });
+
+        const response = await client.messages.create({
+            model: resolvedModel,
+            max_tokens: maxTokens || 16384,
+            messages: [{ role: 'user', content: prompt }]
+        });
+
+        // Extract text from ALL text blocks (SDK can return multiple content blocks)
+        const text = response.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('');
+
+        const elapsedTime = Date.now() - startTime;
+        const usage = response.usage || {};
+
+        const normalizedUsage = {
+            input_tokens: usage.input_tokens || 0,
+            output_tokens: usage.output_tokens || 0,
+            cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+            cache_read_input_tokens: usage.cache_read_input_tokens || 0
+        };
+
+        logger.debug('claude-client - _executeSDK', 'SDK response received', {
+            elapsedTime,
+            model: resolvedModel,
+            inputTokens: normalizedUsage.input_tokens,
+            outputTokens: normalizedUsage.output_tokens,
+            cacheCreationTokens: normalizedUsage.cache_creation_input_tokens,
+            cacheReadTokens: normalizedUsage.cache_read_input_tokens,
+            contentBlocks: response.content.length,
+            responseLength: text.length
+        });
+
+        return { text, usage: normalizedUsage, model: resolvedModel };
+    } catch (error) {
+        const elapsedTime = Date.now() - startTime;
+
+        if (error.constructor?.name === 'RateLimitError' || error.status === 429) {
+            logger.error(
+                'claude-client - _executeSDK',
+                `SDK rate limit exceeded (after SDK retries): ${error.message}`,
+                error
+            );
+            throw new ClaudeClientError('SDK rate limit exceeded', {
+                cause: error,
+                context: {
+                    elapsedTime,
+                    model: resolvedModel,
+                    errorInfo: { type: 'RATE_LIMIT', fromSDK: true }
+                }
+            });
+        }
+
+        if (error.constructor?.name === 'APIStatusError' || error.status) {
+            logger.error(
+                'claude-client - _executeSDK',
+                `SDK API error (status ${error.status}): ${error.message}`,
+                error
+            );
+            throw new ClaudeClientError(`SDK API error (status ${error.status})`, {
+                cause: error,
+                context: {
+                    elapsedTime,
+                    model: resolvedModel,
+                    statusCode: error.status,
+                    errorInfo: { type: 'API_STATUS_ERROR', fromSDK: true }
+                }
+            });
+        }
+
+        // Unknown error — propagate with SDK marker so withRetry skips it
+        logger.error('claude-client - _executeSDK', `SDK error: ${error.message}`, error);
+        throw new ClaudeClientError(`SDK error: ${error.message}`, {
+            cause: error,
+            context: {
+                elapsedTime,
+                model: resolvedModel,
+                errorInfo: { type: 'SDK_ERROR', fromSDK: true }
+            }
+        });
+    }
+};
+
+/**
+ * Verify SDK connectivity with a minimal 1-token ping.
+ * @returns {Promise<{ok: boolean, usage?: Object, error?: string}>}
+ */
+async function verifySDKConnection() {
+    try {
+        const result = await _executeSDK('ping', { model: 'haiku', maxTokens: 5, timeout: 10000 });
+        return { ok: true, usage: result.usage };
+    } catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+
 /**
  * Executes Claude CLI with a prompt
  * Why: Centralized Claude CLI execution with error handling and timeout
@@ -338,11 +497,43 @@ const getClaudeCommand = () => {
  * @param {Object} options - Execution options
  * @param {number} options.timeout - Timeout in milliseconds (default: 120000 = 2 minutes)
  * @param {string} options.model - Claude model override (e.g., 'haiku', 'sonnet', 'opus')
+ * @param {boolean} options.headless - Use SDK instead of CLI (default: false)
  * @returns {Promise<string>} Claude's response
  * @throws {ClaudeClientError} If execution fails or times out
  */
-const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null } = {}) =>
-    new Promise((resolve, reject) => {
+const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null, headless = false, maxTokens = null, costTracker = null } = {}) => {
+    // Headless mode: use Anthropic SDK directly (GH#133)
+    // Branch here (not in executeClaudeWithRetry) because analyzeCode calls
+    // executeClaude directly via withRetry — branching here covers all paths.
+    if (headless) {
+        const startTime = Date.now();
+        return _executeSDK(prompt, { model, timeout, maxTokens }).then(async (sdkResult) => {
+            const durationMs = Date.now() - startTime;
+            if (costTracker) {
+                costTracker.add({
+                    command: 'executeClaude',
+                    model: sdkResult.model,
+                    tokens_input: sdkResult.usage.input_tokens,
+                    tokens_output: sdkResult.usage.output_tokens,
+                    cache_creation: sdkResult.usage.cache_creation_input_tokens,
+                    cache_read: sdkResult.usage.cache_read_input_tokens,
+                    duration_ms: durationMs
+                });
+            }
+            // Langfuse generation — awaited so trace is queued before flush runs (no-op when disabled)
+            await traceGeneration({
+                name: 'executeClaude',
+                model: sdkResult.model,
+                input: prompt,
+                output: sdkResult.text,
+                usage: sdkResult.usage,
+                durationMs
+            }).catch(() => {});
+            return sdkResult.text;
+        });
+    }
+
+    return new Promise((resolve, reject) => {
         // Get platform-specific command
         const { command, args, loginShell } = getClaudeCommand();
 
@@ -637,6 +828,7 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = nu
             );
         }
     });
+};
 
 /**
  * Executes Claude CLI fully interactively
@@ -1039,9 +1231,11 @@ const executeClaudeWithRetry = async (prompt, options = {}) => {
  */
 const analyzeCode = async (
     prompt,
-    { timeout = 120000, model = null, saveDebug = config.system.debug, telemetryContext = {} } = {}
+    { timeout = 120000, model = null, saveDebug = config.system.debug, telemetryContext = {}, headless = false, costTracker = null } = {}
 ) => {
     const startTime = Date.now();
+    // In headless mode, always track costs — create internal tracker if caller didn't supply one
+    const tracker = costTracker || (headless ? new CostTracker() : null);
 
     logger.debug('claude-client - analyzeCode', 'Starting code analysis', {
         promptLength: prompt.length,
@@ -1056,10 +1250,10 @@ const analyzeCode = async (
     });
 
     // Use withRetry to wrap the entire analysis flow (with telemetry tracking)
-    return withRetry(
+    const result = await withRetry(
         async () => {
-            // Execute Claude CLI
-            const response = await executeClaude(prompt, { timeout, model });
+            // Execute Claude (CLI or SDK depending on headless flag)
+            const response = await executeClaude(prompt, { timeout, model, headless, costTracker: tracker });
 
             // Save debug if requested
             if (saveDebug) {
@@ -1067,19 +1261,24 @@ const analyzeCode = async (
             }
 
             // Extract and parse JSON
-            const result = extractJSON(response, telemetryContext);
+            const parsed = extractJSON(response, telemetryContext);
 
             const duration = Date.now() - startTime;
 
             logger.debug('claude-client - analyzeCode', 'Analysis complete', {
-                hasApproved: 'approved' in result,
-                hasQualityGate: 'QUALITY_GATE' in result,
-                blockingIssuesCount: result.blockingIssues?.length ?? 0,
+                hasApproved: 'approved' in parsed,
+                hasQualityGate: 'QUALITY_GATE' in parsed,
+                blockingIssuesCount: parsed.blockingIssues?.length ?? 0,
                 duration
             });
 
+            // Attach cost data in headless mode (GH#142)
+            if (tracker && headless) {
+                parsed._costs = tracker.toJSON();
+            }
+
             // Telemetry is now recorded by withRetry wrapper
-            return result;
+            return parsed;
         },
         {
             operationName: 'analyzeCode',
@@ -1089,6 +1288,13 @@ const analyzeCode = async (
             }
         }
     );
+
+    // Flush Langfuse traces after analysis completes (no-op when disabled)
+    if (headless) {
+        await langfuseFlush().catch(() => {});
+    }
+
+    return result;
 };
 
 export {
@@ -1101,5 +1307,9 @@ export {
     analyzeCode,
     isWindows,
     isWSLAvailable,
-    getClaudeCommand
+    getClaudeCommand,
+    MODEL_ALIASES,
+    resolveModelAlias,
+    _executeSDK,
+    verifySDKConnection
 };

package/lib/utils/claude-diagnostics.js

@@ -355,7 +355,8 @@ const formatGenericError = (errorInfo) => {
  * @returns {boolean} True if error might resolve with retry
  */
 export const isRecoverableError = (errorInfo) =>
-    errorInfo.type === ClaudeErrorType.EXECUTION_ERROR ||
-    errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
-    errorInfo.type === ClaudeErrorType.NETWORK ||
-    errorInfo.type === ClaudeErrorType.TIMEOUT;
+    !errorInfo.fromSDK &&
+    (errorInfo.type === ClaudeErrorType.EXECUTION_ERROR ||
+        errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
+        errorInfo.type === ClaudeErrorType.NETWORK ||
+        errorInfo.type === ClaudeErrorType.TIMEOUT);

package/lib/utils/cost-tracker.js

@@ -0,0 +1,128 @@
+// MODEL_PRICING last updated: 2026-04-28 (source: anthropic.com/pricing)
+//
+// Cache pricing (per Anthropic public pricing, mirrors Lumiere observability/pricing.py):
+//   cache_creation = base input price * 1.25
+//   cache_read     = base input price * 0.10
+
+import logger from './logger.js';
+
+/**
+ * Pricing per 1M tokens (USD) keyed by full Anthropic model ID.
+ * Mirrors mscope-S-L/Lumiere observability/pricing.py exactly.
+ */
+const MODEL_PRICING = {
+    // Sonnet 4.5 (Sep 2025)
+    'claude-sonnet-4-5-20250929': { input_per_1m: 3.0, output_per_1m: 15.0 },
+    // Sonnet 4.6 (Apr 2025)
+    'claude-sonnet-4-6-20250414': { input_per_1m: 3.0, output_per_1m: 15.0 },
+    'claude-sonnet-4-6': { input_per_1m: 3.0, output_per_1m: 15.0 },
+    // Opus 4.6 (Apr 2025)
+    'claude-opus-4-6-20250415': { input_per_1m: 15.0, output_per_1m: 75.0 },
+    'claude-opus-4-6': { input_per_1m: 15.0, output_per_1m: 75.0 },
+    // Haiku 4.5 (Oct 2025)
+    'claude-haiku-4-5-20251001': { input_per_1m: 1.0, output_per_1m: 5.0 },
+    'claude-haiku-4-5': { input_per_1m: 1.0, output_per_1m: 5.0 }
+};
+
+/** Fallback for unknown models — uses sonnet pricing (conservative). */
+const DEFAULT_PRICING = { input_per_1m: 3.0, output_per_1m: 15.0 };
+
+/**
+ * Calculate cost in USD for a given token usage and model.
+ *
+ * @param {Object} params
+ * @param {number} params.tokens_input - Regular input tokens
+ * @param {number} params.tokens_output - Output tokens
+ * @param {string} params.model - Full Anthropic model ID
+ * @param {number} [params.cache_creation=0] - Cache creation (write) tokens
+ * @param {number} [params.cache_read=0] - Cache read tokens
+ * @returns {number} Cost in USD, rounded to 6 decimal places
+ */
+function calculateCost({ tokens_input, tokens_output, model, cache_creation = 0, cache_read = 0 }) {
+    const pricing = MODEL_PRICING[model];
+    if (!pricing) {
+        logger.warning(`cost-tracker: unknown model "${model}", using DEFAULT_PRICING (sonnet)`);
+    }
+    const { input_per_1m, output_per_1m } = pricing || DEFAULT_PRICING;
+
+    const costInput = (tokens_input / 1_000_000) * input_per_1m;
+    const costCacheCreation = (cache_creation / 1_000_000) * input_per_1m * 1.25;
+    const costCacheRead = (cache_read / 1_000_000) * input_per_1m * 0.1;
+    const costOutput = (tokens_output / 1_000_000) * output_per_1m;
+
+    return Math.round((costInput + costCacheCreation + costCacheRead + costOutput) * 1_000_000) / 1_000_000;
+}
+
+/**
+ * Tracks costs across multiple Claude SDK calls within a single invocation.
+ */
+class CostTracker {
+    constructor() {
+        this.entries = [];
+    }
+
+    /**
+     * Record a single SDK call.
+     *
+     * @param {Object} params
+     * @param {string} params.command - Caller label (e.g. 'executeClaude', 'analyzeCode')
+     * @param {string} params.model - Full Anthropic model ID
+     * @param {number} params.tokens_input - Input tokens
+     * @param {number} params.tokens_output - Output tokens
+     * @param {number} [params.cache_creation=0] - Cache creation tokens
+     * @param {number} [params.cache_read=0] - Cache read tokens
+     * @param {number} [params.duration_ms=0] - Wall-clock milliseconds
+     */
+    add({ command, model, tokens_input, tokens_output, cache_creation = 0, cache_read = 0, duration_ms = 0 }) {
+        const cost_usd = calculateCost({ tokens_input, tokens_output, model, cache_creation, cache_read });
+        this.entries.push({
+            command,
+            model,
+            tokens_input,
+            tokens_output,
+            cache_creation_tokens: cache_creation,
+            cache_read_tokens: cache_read,
+            cost_usd,
+            duration_ms
+        });
+    }
+
+    /**
+     * Export tracker data as a plain object suitable for JSON serialization.
+     *
+     * @returns {{ entries: Array, totals: Object }}
+     */
+    toJSON() {
+        const totals = {
+            input_tokens: 0,
+            output_tokens: 0,
+            cache_creation_tokens: 0,
+            cache_read_tokens: 0,
+            cost_usd: 0,
+            duration_ms: 0
+        };
+        for (const e of this.entries) {
+            totals.input_tokens += e.tokens_input;
+            totals.output_tokens += e.tokens_output;
+            totals.cache_creation_tokens += e.cache_creation_tokens;
+            totals.cache_read_tokens += e.cache_read_tokens;
+            totals.cost_usd += e.cost_usd;
+            totals.duration_ms += e.duration_ms;
+        }
+        totals.cost_usd = Math.round(totals.cost_usd * 1_000_000) / 1_000_000;
+
+        return { entries: [...this.entries], totals };
+    }
+
+    /**
+     * Emit one structured JSON log line per entry via logger.info().
+     * Designed for CloudWatch Logs Insights: `fields @timestamp, command, cost_usd`.
+     */
+    logSummary() {
+        for (const entry of this.entries) {
+            logger.info(JSON.stringify({ metric: 'claude_hooks_cost', ...entry }));
+        }
+    }
+}
+
+export { MODEL_PRICING, DEFAULT_PRICING, calculateCost, CostTracker };

package/lib/utils/diff-analysis-orchestrator.js

@@ -183,7 +183,7 @@ const _buildCommonContext = (filesData, batchGroups) => {
  * @param {Array<import('./analysis-engine.js').FileData>} filesData
  * @returns {Promise<{batches: Array<{files: FileData[], rationale: string, model: string}>, commonContext: string}>}
  */
-export const orchestrateBatches = async (filesData) => {
+export const orchestrateBatches = async (filesData, { headless = false } = {}) => {
     logger.debug('diff-analysis-orchestrator - orchestrateBatches', 'Building file overview', {
         fileCount: filesData.length
     });
@@ -223,6 +223,7 @@ export const orchestrateBatches = async (filesData) => {
         rawResponse = await executeClaudeWithRetry(prompt, {
             model: ORCHESTRATOR_MODEL,
             timeout: ORCHESTRATOR_TIMEOUT,
+            headless,
             telemetryContext: {
                 hook: 'orchestrator',
                 fileCount: filesData.length,

package/lib/utils/git-operations.js

@@ -12,7 +12,7 @@
  * - logger: For debug and error logging
  */
 
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import logger from './logger.js';
@@ -1546,6 +1546,106 @@ const getCommitFiles = (hash, { repoPath } = {}) => {
     }
 };
 
+/**
+ * Gets the SHA of the current staged tree (index)
+ * Why: Used as a fingerprint to verify that staged content hasn't changed between
+ * pre-commit (writes marker) and prepare-commit-msg (reads marker). Identical
+ * staging produces identical SHA; any `git add` in between invalidates it.
+ *
+ * Side effect: git write-tree creates a loose object in .git/objects/ as a
+ * by-product of computing the tree SHA. The object is harmless and will be
+ * collected by the next `git gc` run.
+ *
+ * @returns {string} 40-character hex SHA of the staged tree
+ * @throws {GitError} If git write-tree fails
+ */
+const getStagedTreeSha = () => {
+    logger.debug('git-operations - getStagedTreeSha', 'Computing staged tree SHA');
+
+    const sha = execGitCommand('write-tree');
+
+    logger.debug('git-operations - getStagedTreeSha', 'Tree SHA computed', { sha });
+    return sha;
+};
+
+/**
+ * Checks whether a commit has the Hooks-Verified trailer set to 'true'
+ * Why: Used by tests and downstream CI checks (CT-702) to verify that
+ * a commit passed pre-commit analysis
+ *
+ * @param {string} commitHash - Commit hash to check (short or full SHA)
+ * @returns {boolean} True if the commit has Hooks-Verified: true trailer
+ */
+const hasHooksVerifiedTrailer = (commitHash) => {
+    logger.debug('git-operations - hasHooksVerifiedTrailer', 'Checking trailer', { commitHash });
+
+    const sanitizedHash = /^[0-9a-f]{7,40}$/i.test(String(commitHash)) ? commitHash : null;
+    if (!sanitizedHash) {
+        throw new GitError('Invalid commit hash', {
+            command: 'hasHooksVerifiedTrailer',
+            output: commitHash
+        });
+    }
+
+    try {
+        const output = execGitCommand(
+            `log -1 --format=%(trailers:key=Hooks-Verified,valueonly) ${sanitizedHash}`
+        );
+        const hasTrailer = output.trim().includes('true');
+
+        logger.debug('git-operations - hasHooksVerifiedTrailer', 'Trailer check result', {
+            commitHash: sanitizedHash,
+            hasTrailer
+        });
+        return hasTrailer;
+    } catch (error) {
+        logger.error(
+            'git-operations - hasHooksVerifiedTrailer',
+            'Failed to check trailer',
+            error
+        );
+        return false;
+    }
+};
+
+/**
+ * Appends a git trailer to a commit message using git interpret-trailers
+ * Why: git interpret-trailers is the canonical implementation — it handles existing
+ * trailer blocks, comment lines, signed-off-by blocks, and deduplication correctly.
+ * Reimplementing from scratch is fragile and error-prone.
+ *
+ * @param {string} message - Current commit message
+ * @param {string} key - Trailer key (e.g., 'Hooks-Verified')
+ * @param {string} value - Trailer value (e.g., 'true')
+ * @returns {string} Message with trailer appended
+ */
+const appendTrailer = (message, key, value) => {
+    logger.debug('git-operations - appendTrailer', 'Appending trailer', { key, value });
+
+    try {
+        // Why: spawnSync avoids shell interpretation — key/value are passed as discrete
+        // argv entries, not interpolated into a shell command string
+        const result = spawnSync('git', ['interpret-trailers', '--trailer', `${key}: ${value}`], {
+            input: message,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        if (result.error || result.status !== 0) {
+            throw result.error || new Error(result.stderr || 'interpret-trailers failed');
+        }
+
+        logger.debug('git-operations - appendTrailer', 'Trailer appended successfully');
+        return result.stdout;
+    } catch (error) {
+        logger.error('git-operations - appendTrailer', 'Failed to append trailer', error);
+        throw new GitError('Failed to append trailer', {
+            command: `git interpret-trailers --trailer "${key}: ${value}"`,
+            cause: error
+        });
+    }
+};
+
 export {
     GitError,
     getStagedFiles,
@@ -1581,5 +1681,8 @@ export {
     getLatestTag,
     isWorkingDirectoryClean,
     getActiveBranch,
-    getCommitFiles
+    getCommitFiles,
+    getStagedTreeSha,
+    hasHooksVerifiedTrailer,
+    appendTrailer
 };