wave-agent-sdk 1.0.10 → 1.1.0

package/dist/services/jsonlHandler.js

@@ -4,7 +4,7 @@
  */
 import { appendFile, readFile, writeFile, stat, mkdir } from "fs/promises";
 import { dirname } from "path";
-import { getLastLine } from "../utils/fileUtils.js";
+import { getLastLine, readFirstNLines } from "../utils/fileUtils.js";
 /**
  * JSONL handler class for message persistence operations
  */
@@ -15,13 +15,26 @@ export class JsonlHandler {
         };
     }
     /**
-     * Create a new session file (simplified - no metadata header)
+     * Create a new session file.
+     *
+     * When `metadata` is provided, the first line is a metadata header
+     * recording creation-time facts about the session:
+     * `{"type":"metadata","workdir":...,"createdAt":...,"gitBranch":...}`. The
+     * encoded project dir name is lossy for paths containing "-", so persisting
+     * the real path lets session listing show it without decoding; `createdAt`
+     * and `gitBranch` similarly avoid lossy/fabricated reconstruction later.
+     * The header carries no `timestamp`, so message readers filter it out
+     * naturally.
+     *
+     * Legacy callers that omit `metadata` still get an empty file.
      */
-    async createSession(filePath) {
+    async createSession(filePath, metadata) {
         // Ensure directory exists
         await this.ensureDirectory(dirname(filePath));
-        // Create empty file (no metadata line needed)
-        await writeFile(filePath, "", "utf8");
+        const content = metadata && Object.keys(metadata).length > 0
+            ? `${JSON.stringify({ type: "metadata", ...metadata })}\n`
+            : "";
+        await writeFile(filePath, content, "utf8");
     }
     /**
      * Append a single message to JSONL file
@@ -83,11 +96,14 @@ export class JsonlHandler {
                 return [];
             }
             const allMessages = [];
-            // Parse all messages (no metadata line to skip)
+            // Parse all messages, skipping the metadata header line (if any)
             for (let i = 0; i < lines.length; i++) {
                 const line = lines[i];
                 try {
                     const message = JSON.parse(line);
+                    // Metadata header line: not a message, skip
+                    if (message.type === "metadata")
+                        continue;
                     if (message.timestamp)
                         allMessages.push(message);
                 }
@@ -127,6 +143,10 @@ export class JsonlHandler {
             }
             try {
                 const parsed = JSON.parse(lastLine);
+                // A file whose only line is the metadata header has no messages yet
+                if (parsed.type === "metadata") {
+                    return null;
+                }
                 return parsed;
             }
             catch (error) {
@@ -137,6 +157,35 @@ export class JsonlHandler {
             throw new Error(`Failed to get last message from "${filePath}": ${error}`);
         }
     }
+    /**
+     * Read the creation-time metadata from the session file's header line.
+     *
+     * Newer session files start with a `{"type":"metadata",...}` line (see
+     * `createSession`). Legacy files have no header.
+     *
+     * @param filePath - Path to the session JSONL file
+     * @returns The persisted metadata, or null when the file has no header
+     */
+    async readMetadata(filePath) {
+        try {
+            const lines = await readFirstNLines(filePath, 1);
+            if (lines.length === 0) {
+                return null;
+            }
+            const header = JSON.parse(lines[0]);
+            if (header?.type === "metadata") {
+                return {
+                    workdir: header.workdir,
+                    createdAt: header.createdAt,
+                    gitBranch: header.gitBranch,
+                };
+            }
+        }
+        catch {
+            // Unreadable or invalid first line — treat as a legacy file
+        }
+        return null;
+    }
     /**
      * Validate messages before writing
      */

package/dist/services/session.d.ts

@@ -33,6 +33,8 @@ export interface SessionMetadata {
     lastActiveAt: Date;
     latestTotalTokens: number;
     firstMessage?: string;
+    /** Git branch at session creation time (from the metadata header). */
+    branch?: string;
 }
 /**
  * Generate a new session ID using Node.js native crypto.randomUUID()
@@ -123,11 +125,31 @@ export declare function listSessions(workdir: string): Promise<SessionMetadata[]
  */
 export declare function listSessionsFromJsonl(workdir: string): Promise<SessionMetadata[]>;
 /**
- * List all sessions across all project directories
+ * List all sessions across all project directories.
  *
- * @returns Promise that resolves to array of session metadata objects
- */
-export declare function listAllSessions(): Promise<SessionMetadata[]>;
+ * When `worktreePaths` is provided, only project directories that match a
+ * same-repo git worktree (plus the current working directory's own project
+ * dir) are scanned — used by the `wave -r` picker's worktree aggregation
+ * (`Ctrl+W`). When omitted, every project directory under the sessions dir
+ * is scanned (all-projects mode, `Ctrl+A`).
+ *
+ * No time-based filtering is applied — all sessions whose files still exist
+ * are listed, regardless of how long ago they were last active.
+ *
+ * @param options.worktreePaths - Absolute paths of same-repo worktrees
+ *   (from `git worktree list`). When provided, scanning is limited to
+ *   matching project directories.
+ * @param options.workdir - Current working directory. Its own project dir is
+ *   always included in worktree mode so sessions created from a subdirectory
+ *   inside a worktree are not missed.
+ * @returns Promise that resolves to array of session metadata objects,
+ *   deduplicated by sessionId (newest lastActiveAt wins), sorted by
+ *   lastActiveAt descending.
+ */
+export declare function listAllSessions(options?: {
+    worktreePaths?: string[];
+    workdir?: string;
+}): Promise<SessionMetadata[]>;
 /**
  * Clean up expired sessions older than 14 days based on file modification time
  *
@@ -161,6 +183,15 @@ export declare function cleanupMetaOnlySessions(): Promise<number>;
  * @returns Promise that resolves to true if session exists, false otherwise
  */
 export declare function sessionExistsInJsonl(sessionId: string, workdir: string, sessionType?: "main" | "subagent"): Promise<boolean>;
+/**
+ * Get the content of the first non-meta message in a session file
+ * For user role: get text block content
+ * For assistant role: get compact block content
+ * Skips meta messages (isMeta: true) to find the first meaningful message
+ * @param filePath - Path to the session JSONL file
+ * @returns Promise that resolves to the first non-meta message content or null if not found
+ */
+export declare function getFirstMessageContentFromFile(filePath: string): Promise<string | null>;
 /**
  * Get the content of the first non-meta message in a session
  * For user role: get text block content

package/dist/services/session.js

@@ -18,11 +18,14 @@ import { promises as fs } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { randomUUID } from "crypto";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { PathEncoder } from "../utils/pathEncoder.js";
 import { JsonlHandler } from "../services/jsonlHandler.js";
 import { extractLatestTotalTokens } from "../utils/tokenCalculation.js";
 import { logger } from "../utils/globalLogger.js";
 import { getMessageContent, sliceFromLastCompact, } from "../utils/messageOperations.js";
+const execFileAsync = promisify(execFile);
 /**
  * Generate a new session ID using Node.js native crypto.randomUUID()
  * @returns UUID string for session identification
@@ -82,6 +85,22 @@ export async function getSessionFilePath(sessionId, workdir, sessionType = "main
     const filename = jsonlHandler.generateSessionFilename(sessionId, sessionType);
     return join(projectDir.encodedPath, filename);
 }
+/**
+ * Resolve the current git branch for a working directory, if any.
+ *
+ * Returns undefined when the directory is not inside a git repo, git is
+ * unavailable, or the command fails/times out — the session can still be
+ * created, its metadata header just omits the branch.
+ */
+async function getGitBranch(workdir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", workdir, "branch", "--show-current"], { timeout: 2000, windowsHide: true });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Create a new session
  * @param sessionId - UUID session identifier
@@ -91,7 +110,15 @@ export async function getSessionFilePath(sessionId, workdir, sessionType = "main
 export async function createSession(sessionId, workdir, sessionType = "main") {
     const jsonlHandler = new JsonlHandler();
     const filePath = await getSessionFilePath(sessionId, workdir, sessionType);
-    await jsonlHandler.createSession(filePath);
+    // Persist creation-time metadata in the header line: the real workdir
+    // (lossy via decodeSync), the real creation timestamp, and the git branch
+    // at creation time. The header is append-only — written once, never
+    // rewritten — so only creation-time-constant fields belong here.
+    await jsonlHandler.createSession(filePath, {
+        workdir,
+        createdAt: new Date().toISOString(),
+        gitBranch: await getGitBranch(workdir),
+    });
 }
 /**
  * Append messages to session using JSONL format (new approach)
@@ -124,6 +151,38 @@ export async function appendMessages(sessionId, newMessages, workdir, sessionTyp
         atomic: false,
     });
 }
+/**
+ * Scan all project directories for a session file by ID. Used as a fallback
+ * when the session is not found in the given working directory (e.g. resuming
+ * a session created in another project or a sibling git worktree via
+ * `wave --restore <id>`).
+ *
+ * @param sessionId - UUID session identifier
+ * @param sessionType - Type of session ("main" or "subagent")
+ * @returns Full path to the session file, or null if not found anywhere
+ */
+async function findSessionFileAcrossProjects(sessionId, sessionType) {
+    const targetFile = sessionType === "subagent"
+        ? `subagent-${sessionId}.jsonl`
+        : `${sessionId}.jsonl`;
+    try {
+        const projectDirs = await fs.readdir(SESSION_DIR);
+        for (const projectDirName of projectDirs) {
+            const candidate = join(SESSION_DIR, projectDirName, targetFile);
+            try {
+                await fs.access(candidate);
+                return candidate;
+            }
+            catch {
+                // ENOENT/ENOTDIR — keep scanning other project dirs
+            }
+        }
+    }
+    catch {
+        // Sessions base dir missing or unreadable — nothing to scan
+    }
+    return null;
+}
 /**
  * Load session data from JSONL file (new approach)
  *
@@ -138,16 +197,25 @@ export async function loadSessionFromJsonl(sessionId, workdir, sessionType = "ma
         // Generate the session file path directly using known session type
         const filePath = await generateSessionFilePath(sessionId, workdir, sessionType);
         // Check if file exists
+        let resolvedPath = filePath;
         try {
-            await fs.access(filePath);
+            await fs.access(resolvedPath);
         }
         catch (error) {
             if (error.code === "ENOENT") {
-                return null;
+                // Cross-project fallback: the session may live in a different project
+                // directory (e.g. `wave --restore <id>` run from another cwd).
+                const fallbackPath = await findSessionFileAcrossProjects(sessionId, sessionType);
+                if (!fallbackPath) {
+                    return null;
+                }
+                resolvedPath = fallbackPath;
+            }
+            else {
+                throw error;
             }
-            throw error;
         }
-        const allMessages = await jsonlHandler.read(filePath);
+        const allMessages = await jsonlHandler.read(resolvedPath);
         // Find the last compact boundary — only return messages from there forward
         const messages = sliceFromLastCompact(allMessages);
         // Extract metadata from messages
@@ -227,8 +295,6 @@ export async function listSessionsFromJsonl(workdir) {
         const encoder = new PathEncoder();
         const baseDir = SESSION_DIR;
         const projectDir = await encoder.getProjectDirectory(workdir, baseDir);
-        const sevenDaysAgo = new Date();
-        sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
         let files;
         try {
             files = await fs.readdir(projectDir.encodedPath);
@@ -260,6 +326,9 @@ export async function listSessionsFromJsonl(workdir) {
                 // PERFORMANCE OPTIMIZATION: Only read the last message for timestamps and tokens
                 const jsonlHandler = new JsonlHandler();
                 const lastMessage = await jsonlHandler.getLastMessage(filePath);
+                // Creation-time metadata (workdir is not needed here — the project
+                // dir gives the original path — but createdAt / branch are).
+                const header = await jsonlHandler.readMetadata(filePath);
                 // Handle timing information efficiently
                 let lastActiveAt;
                 if (lastMessage) {
@@ -270,20 +339,20 @@ export async function listSessionsFromJsonl(workdir) {
                     const stats = await fs.stat(filePath);
                     lastActiveAt = stats.mtime;
                 }
-                if (lastActiveAt < sevenDaysAgo) {
-                    continue;
-                }
                 // Return inline object for performance (no interface instantiation overhead)
                 const sessionMeta = {
                     id: sessionId,
                     sessionType: "main",
                     subagentType: undefined,
                     workdir: projectDir.originalPath,
-                    createdAt: new Date(),
+                    createdAt: header?.createdAt
+                        ? new Date(header.createdAt)
+                        : new Date(),
                     lastActiveAt,
                     latestTotalTokens: lastMessage?.usage
                         ? extractLatestTotalTokens([lastMessage])
                         : 0,
+                    branch: header?.gitBranch,
                 };
                 // Try to get first message content for display
                 try {
@@ -310,12 +379,30 @@ export async function listSessionsFromJsonl(workdir) {
     }
 }
 /**
- * List all sessions across all project directories
+ * List all sessions across all project directories.
  *
- * @returns Promise that resolves to array of session metadata objects
+ * When `worktreePaths` is provided, only project directories that match a
+ * same-repo git worktree (plus the current working directory's own project
+ * dir) are scanned — used by the `wave -r` picker's worktree aggregation
+ * (`Ctrl+W`). When omitted, every project directory under the sessions dir
+ * is scanned (all-projects mode, `Ctrl+A`).
+ *
+ * No time-based filtering is applied — all sessions whose files still exist
+ * are listed, regardless of how long ago they were last active.
+ *
+ * @param options.worktreePaths - Absolute paths of same-repo worktrees
+ *   (from `git worktree list`). When provided, scanning is limited to
+ *   matching project directories.
+ * @param options.workdir - Current working directory. Its own project dir is
+ *   always included in worktree mode so sessions created from a subdirectory
+ *   inside a worktree are not missed.
+ * @returns Promise that resolves to array of session metadata objects,
+ *   deduplicated by sessionId (newest lastActiveAt wins), sorted by
+ *   lastActiveAt descending.
  */
-export async function listAllSessions() {
+export async function listAllSessions(options) {
     try {
+        const { worktreePaths, workdir } = options ?? {};
         const baseDir = SESSION_DIR;
         let projectDirs;
         try {
@@ -327,9 +414,54 @@ export async function listAllSessions() {
             }
             throw error;
         }
+        // Worktree-aware mode: only scan project dirs that match a same-repo
+        // worktree path. Prefixes are sorted longest-first so a short prefix like
+        // "home-user-repo" cannot swallow "home-user-repo-wt" (short paths require
+        // exact match; prefix + "-" matching only kicks in for paths truncated by
+        // the 200-char encoding limit, mirroring Claude Code's session listing).
+        // Each entry also carries the real path so matching dirs can display it
+        // instead of the lossy decodeSync of the encoded name.
+        const encoder = new PathEncoder();
+        const caseInsensitive = process.platform === "win32";
+        let indexed = null;
+        if (worktreePaths && worktreePaths.length > 0) {
+            indexed = [];
+            const seen = new Set();
+            for (const wt of worktreePaths) {
+                let encoded;
+                try {
+                    encoded = await encoder.encode(wt);
+                }
+                catch {
+                    encoded = encoder.encodeSync(wt);
+                }
+                const prefix = caseInsensitive ? encoded.toLowerCase() : encoded;
+                if (seen.has(prefix))
+                    continue;
+                seen.add(prefix);
+                indexed.push({ prefix, path: wt });
+            }
+            indexed.sort((a, b) => b.prefix.length - a.prefix.length);
+            // Always include the current working directory's own project dir —
+            // the cwd may be a subdirectory inside a worktree whose root prefix
+            // does not match (short-path matching is exact-only).
+            if (workdir) {
+                let encodedCwd;
+                try {
+                    encodedCwd = await encoder.encode(workdir);
+                }
+                catch {
+                    encodedCwd = encoder.encodeSync(workdir);
+                }
+                const prefix = caseInsensitive ? encodedCwd.toLowerCase() : encodedCwd;
+                if (!seen.has(prefix)) {
+                    seen.add(prefix);
+                    indexed.push({ prefix, path: workdir });
+                }
+            }
+        }
         const allSessions = [];
-        const sevenDaysAgo = new Date();
-        sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+        const MAX_ENCODED_PREFIX_LENGTH = 200;
         for (const projectDirName of projectDirs) {
             const projectPath = join(baseDir, projectDirName);
             try {
@@ -337,6 +469,23 @@ export async function listAllSessions() {
                 if (!stat.isDirectory()) {
                     continue;
                 }
+                // The indexed match (worktree mode) carries the real path of the
+                // worktree / cwd that encoded to this dir name.
+                let matchedIndexed;
+                if (indexed) {
+                    const dirName = caseInsensitive
+                        ? projectDirName.toLowerCase()
+                        : projectDirName;
+                    matchedIndexed = indexed.find(({ prefix }) => dirName === prefix ||
+                        (prefix.length >= MAX_ENCODED_PREFIX_LENGTH &&
+                            dirName.startsWith(prefix + "-")));
+                    if (!matchedIndexed)
+                        continue;
+                }
+                // Decode the encoded directory name back to the original project
+                // path for display; fall back to the encoded name when the path was
+                // truncated with a hash suffix (lossy, cannot be reliably reversed).
+                const decodedWorkdir = encoder.decodeSync(projectDirName) ?? projectDirName;
                 // Scan .jsonl files in the project directory
                 const files = await fs.readdir(projectPath);
                 for (const file of files) {
@@ -351,6 +500,9 @@ export async function listAllSessions() {
                         const sessionId = uuidMatch[1];
                         const jsonlHandler = new JsonlHandler();
                         const lastMessage = await jsonlHandler.getLastMessage(filePath);
+                        // Creation-time metadata — read per file: branch can differ
+                        // between sessions created in the same directory over time.
+                        const header = await jsonlHandler.readMetadata(filePath);
                         let lastActiveAt;
                         if (lastMessage) {
                             lastActiveAt = new Date(lastMessage.timestamp);
@@ -359,18 +511,36 @@ export async function listAllSessions() {
                             const stats = await fs.stat(filePath);
                             lastActiveAt = stats.mtime;
                         }
-                        if (lastActiveAt < sevenDaysAgo)
-                            continue;
+                        // Populate the first-message preview like listSessionsFromJsonl
+                        // does, so aggregated modes (Ctrl+A / Ctrl+W) show real content
+                        // instead of the "No content" fallback.
+                        let firstMessage;
+                        try {
+                            const firstContent = await getFirstMessageContentFromFile(filePath);
+                            if (firstContent) {
+                                firstMessage = firstContent;
+                            }
+                        }
+                        catch {
+                            // Ignore errors getting first message
+                        }
+                        // Prefer the real worktree path, then the persisted metadata
+                        // header, then the lossy decodeSync fallback for legacy files.
+                        const workdir = matchedIndexed?.path ?? header?.workdir ?? decodedWorkdir;
                         allSessions.push({
                             id: sessionId,
                             sessionType: "main",
                             subagentType: undefined,
-                            workdir: projectDirName,
-                            createdAt: new Date(),
+                            workdir,
+                            createdAt: header?.createdAt
+                                ? new Date(header.createdAt)
+                                : new Date(),
                             lastActiveAt,
                             latestTotalTokens: lastMessage?.usage
                                 ? extractLatestTotalTokens([lastMessage])
                                 : 0,
+                            firstMessage,
+                            branch: header?.gitBranch,
                         });
                     }
                     catch {
@@ -382,7 +552,17 @@ export async function listAllSessions() {
                 // Skip if stat/readdir fails
             }
         }
-        return allSessions.sort((a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime());
+        // Deduplicate by sessionId — the same session can appear in multiple
+        // project dirs (e.g. worktree branches). Keep the newest lastActiveAt.
+        const byId = new Map();
+        for (const session of allSessions) {
+            const existing = byId.get(session.id);
+            if (!existing ||
+                session.lastActiveAt.getTime() > existing.lastActiveAt.getTime()) {
+                byId.set(session.id, session);
+            }
+        }
+        return [...byId.values()].sort((a, b) => b.lastActiveAt.getTime() - a.lastActiveAt.getTime());
     }
     catch (error) {
         throw new Error(`Failed to list all sessions: ${error}`);
@@ -578,28 +758,23 @@ export async function sessionExistsInJsonl(sessionId, workdir, sessionType) {
     }
 }
 /**
- * Get the content of the first non-meta message in a session
+ * Get the content of the first non-meta message in a session file
  * For user role: get text block content
  * For assistant role: get compact block content
  * Skips meta messages (isMeta: true) to find the first meaningful message
- * @param sessionId - Session ID to get first message from
- * @param workdir - Working directory for session operations
+ * @param filePath - Path to the session JSONL file
  * @returns Promise that resolves to the first non-meta message content or null if not found
  */
-export async function getFirstMessageContent(sessionId, workdir) {
+export async function getFirstMessageContentFromFile(filePath) {
     try {
-        const encoder = new PathEncoder();
-        const baseDir = SESSION_DIR;
-        const projectDir = await encoder.getProjectDirectory(workdir, baseDir);
-        const filePath = join(projectDir.encodedPath, `${sessionId}.jsonl`);
         // Read first N lines to skip meta messages
         const { readFirstNLines } = await import("../utils/fileUtils.js");
         const lines = await readFirstNLines(filePath, 10);
         for (const line of lines) {
             try {
                 const message = JSON.parse(line);
-                // Skip meta messages
-                if (message.isMeta) {
+                // Skip the metadata header line and meta messages
+                if (message.type === "metadata" || message.isMeta) {
                     continue;
                 }
                 const content = getMessageContent(message);
@@ -608,11 +783,33 @@ export async function getFirstMessageContent(sessionId, workdir) {
                 }
             }
             catch (error) {
-                logger.warn(`Failed to parse message in session ${sessionId}:`, error);
+                logger.warn(`Failed to parse message in session file ${filePath}:`, error);
             }
         }
         return null;
     }
+    catch (error) {
+        logger.warn(`Failed to get first message content from ${filePath}:`, error);
+        return null;
+    }
+}
+/**
+ * Get the content of the first non-meta message in a session
+ * For user role: get text block content
+ * For assistant role: get compact block content
+ * Skips meta messages (isMeta: true) to find the first meaningful message
+ * @param sessionId - Session ID to get first message from
+ * @param workdir - Working directory for session operations
+ * @returns Promise that resolves to the first non-meta message content or null if not found
+ */
+export async function getFirstMessageContent(sessionId, workdir) {
+    try {
+        const encoder = new PathEncoder();
+        const baseDir = SESSION_DIR;
+        const projectDir = await encoder.getProjectDirectory(workdir, baseDir);
+        const filePath = join(projectDir.encodedPath, `${sessionId}.jsonl`);
+        return getFirstMessageContentFromFile(filePath);
+    }
     catch (error) {
         logger.warn(`Failed to get first message content for session ${sessionId}:`, error);
         return null;
@@ -675,10 +872,10 @@ export async function handleSessionRestoration(restoreSessionId, continueLastSes
             // Use only JSONL format - no legacy support
             sessionToRestore = await loadSessionFromJsonl(restoreSessionId, workdir);
             if (!sessionToRestore) {
-                // Session doesn't exist on disk (e.g. new project with no messages saved yet).
-                // Gracefully fall back to starting fresh instead of throwing.
-                logger?.warn(`Session ${restoreSessionId} not found on disk, starting fresh session`);
-                return;
+                // loadSessionFromJsonl already scans every project directory as a
+                // fallback — reaching here means the session does not exist anywhere.
+                // Surface a clear error instead of silently starting a fresh session.
+                throw new Error(`Session ${restoreSessionId} not found on disk`);
             }
         }
         else if (continueLastSession) {

package/dist/services/worktreeHooks.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Worktree hooks — replace semantics (aligned with Claude Code).
+ *
+ * When `WorktreeCreate` / `WorktreeRemove` hooks are configured, wave delegates
+ * worktree creation/removal to the hooks instead of running git itself:
+ * - `WorktreeCreate`: the first successful hook's stdout (trimmed) is the
+ *   worktree path. All failures / empty output block creation.
+ * - `WorktreeRemove`: only fires for hook-based worktrees; wave never runs
+ *   `git worktree remove` for them. Failures are logged, never blocking.
+ *
+ * Unlike HookManager (DI-bound, per-agent), this module operates on a merged
+ * `PartialHookConfiguration` so it can be used from standalone CLI paths
+ * (packages/code) that load settings via `loadMergedWaveConfig`.
+ * See docs/specs/multi-agent/worktree.md.
+ */
+import type { PartialHookConfiguration } from "../types/hooks.js";
+/** Minimal context required to run worktree hooks standalone. */
+export interface WorktreeHookContext {
+    /** Absolute project directory (also the hook cwd / $WAVE_PROJECT_DIR) */
+    projectDir: string;
+    sessionId?: string;
+    transcriptPath?: string;
+    /** Additional environment variables for the hook process */
+    env?: Record<string, string>;
+}
+export declare function hasWorktreeCreateHook(configuration: PartialHookConfiguration | undefined): boolean;
+export declare function hasWorktreeRemoveHook(configuration: PartialHookConfiguration | undefined): boolean;
+/**
+ * Execute WorktreeCreate hooks and return the worktree path from hook stdout.
+ *
+ * The first successful hook (exit code 0) with non-empty stdout provides the
+ * worktree path (trimmed). Throws if every hook fails or none emits output —
+ * creation is blocked.
+ *
+ * Callers should check hasWorktreeCreateHook() before calling.
+ */
+export declare function executeWorktreeCreateHook(name: string, configuration: PartialHookConfiguration | undefined, context: WorktreeHookContext): Promise<{
+    worktreePath: string;
+}>;
+/**
+ * Execute WorktreeRemove hooks for a hook-based worktree.
+ * Returns true if hooks ran, false if none were configured.
+ * Failures are logged but never throw (non-blocking, aligned with Claude Code).
+ */
+export declare function executeWorktreeRemoveHook(worktreePath: string, configuration: PartialHookConfiguration | undefined, context: WorktreeHookContext): Promise<boolean>;