wave-agent-sdk 1.0.10 → 1.1.0

package/dist/agent.d.ts

@@ -23,7 +23,9 @@ export declare class Agent {
     private messageQueue;
     private dispatchPromise;
     private isAborting;
+    private isDestroyed;
     private dispatchAborted;
+    private asyncWorkRegistry;
     private memoryRuleManager;
     private liveConfigManager;
     private taskManager;
@@ -122,6 +124,13 @@ export declare class Agent {
         }>;
         type?: "message" | "bang";
     }): boolean;
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    private assertNotDestroyed;
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -244,12 +253,6 @@ export declare class Agent {
      * Background the current foreground task
      */
     backgroundCurrentTask(): Promise<void>;
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    triggerWorktreeRemoveHook(worktreePath: string): Promise<void>;
     /** Destroy managers, clean up resources */
     destroy(): Promise<void>;
     /**

package/dist/agent.js

@@ -53,7 +53,8 @@ export class Agent {
     constructor(options) {
         this.bangManager = null;
         this.dispatchPromise = null; // Track current dispatch for teardown
-        this.isAborting = false; // Guard: prevents tryDispatch from firing during abortMessage
+        this.isAborting = false; // Transient guard: prevents tryDispatch from firing during abortMessage (reset when the abort completes)
+        this.isDestroyed = false; // Terminal guard: set in destroy(), never reset — no dispatch may ever start after destroy
         this.dispatchAborted = false; // Set on abort while a dispatch is running: suppress the .finally re-check so preserved notifications don't get dispatched after abort
         this.sessionStartTime = Date.now();
         const { logger, workdir, systemPrompt, stream = true } = options;
@@ -113,6 +114,7 @@ export class Agent {
         this.bangManager = this.container.get("BangManager");
         this.cronManager = this.container.get("CronManager");
         this.messageQueue = this.container.get("MessageQueue");
+        this.asyncWorkRegistry = this.container.get("AsyncWorkRegistry");
         // Wire up CWD change callback from AIManager to sync Agent's workdir
         this.aiManager.setOnCwdChange((newCwd) => {
             this.workdir = newCwd;
@@ -256,6 +258,17 @@ export class Agent {
         }
         return updated;
     }
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    assertNotDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error("Agent destroyed");
+        }
+    }
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -263,6 +276,8 @@ export class Agent {
      * onLoadingChange(false), and onCommandRunningChange(false).
      */
     tryDispatch() {
+        if (this.isDestroyed)
+            return; // Terminal: agent destroyed, never dispatch again
         if (this.isAborting)
             return; // Suppress dispatch during abort to prevent queued notifications from being dispatched as a side-effect
         if (this.dispatchAborted)
@@ -274,7 +289,7 @@ export class Agent {
         if (this.aiManager.isLoading || this.isCommandRunning)
             return;
         this.messageQueue.transitionTo("dispatching");
-        this.dispatchPromise = this.processQueuedMessage()
+        this.dispatchPromise = this.asyncWorkRegistry.track(this.processQueuedMessage()
             .catch((error) => {
             this.logger?.error("Failed to process queued message:", error);
         })
@@ -285,7 +300,7 @@ export class Agent {
                 this.tryDispatch(); // Re-check after processing
             }
             this.dispatchAborted = false;
-        });
+        }));
     }
     /**
      * Process the next queued item when the agent becomes idle.
@@ -499,6 +514,7 @@ export class Agent {
     }
     /** Execute bash command (bang command) */
     async bang(command) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the bang command
         if (this.aiManager.isLoading || this.isCommandRunning) {
             this.messageQueue.enqueue({ type: "bang", content: command });
@@ -625,37 +641,14 @@ export class Agent {
         await this.foregroundTaskManager.backgroundCurrentTask();
         this.options.callbacks?.onBackgroundCurrentTask?.();
     }
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    async triggerWorktreeRemoveHook(worktreePath) {
-        if (!this.hookManager.hasHooks("WorktreeRemove")) {
-            return;
-        }
-        try {
-            const sessionId = this.messageManager.getSessionId();
-            const transcriptPath = this.messageManager.getTranscriptPath();
-            const hookResults = await this.hookManager.executeHooks("WorktreeRemove", {
-                event: "WorktreeRemove",
-                projectDir: this.workdir,
-                timestamp: new Date(),
-                sessionId,
-                transcriptPath,
-                cwd: this.workdir,
-                worktreePath,
-                env: Object.fromEntries(Object.entries(this.configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
-            });
-            // Process results via messageManager (may not be visible during shutdown)
-            this.hookManager.processHookResults("WorktreeRemove", hookResults, this.messageManager);
-        }
-        catch (error) {
-            this.logger?.warn("WorktreeRemove hooks execution failed:", error);
-        }
-    }
     /** Destroy managers, clean up resources */
     async destroy() {
+        // Terminal guard: suppress any dispatch triggered during teardown (e.g. the
+        // onLoadingChange(false) fired by abortAIMessage() below, or the dispatch
+        // .finally re-check). Without this, leftover queued messages would be
+        // dispatched fire-and-forget and outlive the agent. Never reset: destroy()
+        // is terminal, no dispatch should ever start afterwards.
+        this.isDestroyed = true;
         // Log session_end event and shutdown telemetry
         await logOTelEvent("session_end", {
             duration: String(Math.round((Date.now() - this.sessionStartTime) / 1000)),
@@ -717,7 +710,13 @@ export class Agent {
         }
         // Cleanup remote settings polling
         remoteSettingsService.shutdown();
-        // Cleanup memory store
+        // Drain live async work (dispatch, background subagents, fork subagents):
+        // abort steps above make them settle; wait for them so no async side
+        // effect outlives the agent. Timeout fallback keeps destroy bounded.
+        const drained = await this.asyncWorkRegistry.drain();
+        if (!drained) {
+            this.logger?.error(`Async work did not drain: ${this.asyncWorkRegistry.size} live work item(s) remain after destroy`);
+        }
     }
     /**
      * Trigger the rewind UI callback
@@ -738,6 +737,7 @@ export class Agent {
      * @returns Promise that resolves to the AI's answer
      */
     async askBtw(question, abortSignal, onContent, onReasoning) {
+        this.assertNotDestroyed();
         const result = await this.aiManager.runBtwFork(question, abortSignal, onContent, onReasoning);
         return result.content ?? result.error ?? "No response received";
     }
@@ -760,6 +760,7 @@ export class Agent {
      * @returns Promise that resolves to the background task ID
      */
     async forkSubagent(prompt, options, abortSignal) {
+        this.assertNotDestroyed();
         return this.aiManager.runForkSubagent(prompt, options, abortSignal);
     }
     /**
@@ -789,6 +790,7 @@ export class Agent {
      * ```
      */
     async sendMessage(content, images) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the message — unless it's an immediate
         // slash command (e.g., /clear, /compact) that should execute
         // right away even while AI is processing

package/dist/builtin/skills/settings.js

@@ -92,8 +92,8 @@ Wave supports the following hook events:
 - \`PermissionRequest\`: Triggered when Wave requests permission to use a tool.
 - \`Stop\`: Triggered when Wave finishes its response cycle (no more tool calls).
 - \`SubagentStop\`: Triggered when a subagent finishes its response cycle.
-- \`WorktreeCreate\`: Triggered when a new worktree is created.
-- \`WorktreeRemove\`: Triggered before a worktree is removed (e.g., via ExitWorktree with \`action: "remove"\`). Non-blocking. Fires **before** the worktree directory is deleted so hooks can still read files inside it. The hook receives \`worktree_path\` in the JSON input. Useful for cleanup tasks (e.g., \`docker compose -p $(basename "$worktree_path") down\`).
+- \`WorktreeCreate\`: Triggered to create a new worktree, replacing \`git worktree add\`. The hook performs the creation itself (e.g., \`git worktree add\`, or any other VCS/external provisioning) and must output the worktree's absolute path on stdout (path return). Creation is blocked if all hooks fail or produce no output. Receives \`name\` in the JSON input. The resulting session is marked "hook-based".
+- \`WorktreeRemove\`: Triggered when a hook-based worktree (created by a \`WorktreeCreate\` hook) is removed (e.g., via ExitWorktree with \`action: "remove"\`), replacing \`git worktree remove\` for that worktree: the hook performs the removal itself (e.g., \`git worktree remove --force\` plus external resource cleanup). Fires **before** the worktree directory is deleted so hooks can still read files inside it. Receives \`worktree_path\` in the JSON input. Failures are logged but non-blocking. Git-created worktrees are removed by git directly and do not trigger this hook.
 - \`CwdChanged\`: Triggered when the working directory changes (e.g., entering/exiting a worktree). Non-blocking.
 - \`SessionStart\`: Triggered during session initialization. Hooks can inject \`additionalContext\` and \`initialUserMessage\` via stdout.
 - \`SessionEnd\`: Triggered during agent destruction (fire-and-forget, non-blocking). Useful for cleanup, resource teardown, and analytics.
@@ -245,9 +245,34 @@ SessionEnd hooks receive \`end_source\` in the JSON input indicating how the ses
 }
 \`\`\`
 
+## WorktreeCreate Hooks
+
+\`WorktreeCreate\` hooks replace \`git worktree add\`: when configured, Wave does not create the worktree itself — the hook does. The hook must output the worktree's absolute path on **stdout** (the first successful hook's trimmed stdout is used as the path). All hooks failing or producing no output blocks the creation with \`WorktreeCreate hook failed: ...\`. The resulting session is marked "hook-based" and skips Wave's post-creation setup (\`settings.local.json\` / \`.worktreeinclude\` propagation) — the hook is responsible for any initialization.
+
+### Input
+WorktreeCreate hooks receive \`name\` (the worktree name) in the JSON input, alongside the common fields \`session_id\`, \`transcript_path\`, \`cwd\`, \`hook_event_name\`.
+
+### Example Configuration
+\`\`\`json
+{
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "command": "worktree_path=\\"$WAVE_PROJECT_DIR/.wave/worktrees/$(jq -r '.name')\\" && mkdir -p \\"$worktree_path\\" && git worktree add \\"$worktree_path\\" 2>/dev/null; echo \\"$worktree_path\\"",
+            "description": "Create the worktree and print its path"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
 ## WorktreeRemove Hooks
 
-\`WorktreeRemove\` hooks fire **before** the worktree directory is deleted, so they can still read files inside it. They are non-blocking (Notification type): the hook never replaces \`git worktree remove\` itself. Useful for cleaning up external resources that were provisioned for the worktree (databases, containers, etc.).
+\`WorktreeRemove\` hooks replace \`git worktree remove\` for **hook-based** worktrees (those created by a \`WorktreeCreate\` hook). When a hook-based worktree is removed from any entry point (CLI exit, ExitWorktree tool, \`wave -p\`, stdio RPC), Wave calls the hook instead of running \`git worktree remove\` — the hook performs the actual removal, so it can clean up external resources it provisioned (databases, containers, etc.) at the same time. Hooks fire **before** the worktree directory is deleted, so they can still read files inside it. Failures are logged but non-blocking. If no \`WorktreeRemove\` hook is configured for a hook-based worktree, Wave logs a warning and leaves the worktree in place. Git-created worktrees (no \`WorktreeCreate\` hook) are removed by git directly and do **not** trigger this hook.
 
 ### Input
 WorktreeRemove hooks receive \`worktree_path\` in the JSON input (alongside the common fields \`session_id\`, \`transcript_path\`, \`cwd\`, \`hook_event_name\`). The worktree name can be derived via \`basename "$worktree_path"\`.
@@ -260,8 +285,8 @@ WorktreeRemove hooks receive \`worktree_path\` in the JSON input (alongside the
       {
         "hooks": [
           {
-            "command": "worktree_path=$(jq -r '.worktree_path') && docker compose -p \\"$(basename \\"$worktree_path\\")\\" down || true",
-            "description": "Tear down the worktree's docker compose project before removal"
+            "command": "worktree_path=$(jq -r '.worktree_path') && git worktree remove --force \\"$worktree_path\\" && docker compose -p \\"$(basename \\"$worktree_path\\")\\" down",
+            "description": "Remove the worktree and tear down its docker compose project"
           }
         ]
       }
@@ -297,7 +322,7 @@ When hooks are registered via a **plugin**, Wave automatically:
 }
 \`\`\`
 
-The shell also receives \`WAVE_PLUGIN_ROOT\` as an env var, so \`$WAVE_PLUGIN_ROOT\` works in the hook script itself.
+The shell also receives \`WAVE_PLUGIN_ROOT\` as an env var, so \`$WAVE_PLUGIN_ROOT\` works in the hook script itself. For \`WorktreeCreate\`, the script must print the created worktree's absolute path to stdout.
 
 ## Best Practices
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./core/session.js";
 export * from "./services/authService.js";
+export * from "./services/worktreeHooks.js";
 export * from "./constants/tools.js";
 export * from "./agent.js";
 export * from "./core/plugin.js";
@@ -21,6 +22,7 @@ export * from "./utils/hookMatcher.js";
 export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
+export * from "./utils/pathEncoder.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 // Export all services
 export * from "./core/session.js";
 export * from "./services/authService.js";
+export * from "./services/worktreeHooks.js";
 // Export constants
 export * from "./constants/tools.js";
 // Export main agent
@@ -25,6 +26,7 @@ export * from "./utils/hookMatcher.js";
 export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
+export * from "./utils/pathEncoder.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, } from "./services/configurationService.js";

package/dist/managers/aiManager.d.ts

@@ -12,6 +12,15 @@ interface ForkLoopResult {
 }
 export interface AIManagerCallbacks {
     onCompactionStateChange?: (isCompacting: boolean) => void;
+    /**
+     * Streaming content from the compaction fork (accumulated, same semantics
+     * as `onContentUpdate` in CallAgentOptions). Reasoning chunks fall back to
+     * this channel when no reasoning callback is provided. Consumed by the CLI
+     * to show the compaction loading tail.
+     */
+    onCompactionContentUpdate?: (content: string) => void;
+    /** Streaming reasoning from the compaction fork (accumulated). */
+    onCompactionReasoningUpdate?: (content: string) => void;
     onUsageAdded?: (usage: Usage) => void;
     onCwdChange?: (newCwd: string) => void;
 }
@@ -59,6 +68,7 @@ export declare class AIManager {
     private get memoryService();
     private get taskManager();
     private get backgroundTaskManager();
+    private get asyncWorkRegistry();
     private get hookManager();
     private get reversionManager();
     private get permissionManager();

package/dist/managers/aiManager.js

@@ -103,6 +103,9 @@ export class AIManager {
     get backgroundTaskManager() {
         return this.container.get("BackgroundTaskManager");
     }
+    get asyncWorkRegistry() {
+        return this.container.get("AsyncWorkRegistry");
+    }
     get hookManager() {
         return this.container.get("HookManager");
     }
@@ -431,7 +434,7 @@ export class AIManager {
             // 4. Fork path: fork the conversation with the same system prompt,
             // tools, model, and generation params as the main loop so the forked
             // request prefix matches exactly and the prompt cache is reused.
-            const forkResult = await this.runCompactFork(recentChatMessages, compactPrompt, options.abortSignal);
+            const forkResult = await this.runCompactFork(recentChatMessages, compactPrompt, options.abortSignal, this.callbacks?.onCompactionContentUpdate, this.callbacks?.onCompactionReasoningUpdate);
             const summaryContent = forkResult.content;
             const compactTokens = forkResult.usage;
             if (!summaryContent) {
@@ -600,6 +603,25 @@ export class AIManager {
                 // gateway's idle timeout fires (non-streaming waits for the full
                 // response, which exceeds the timeout on large contexts).
                 stream: true,
+                // Surface partial output to the caller (e.g. the compaction loading
+                // tail) as it arrives. Reasoning chunks from thinking models go to
+                // the reasoning channel when the caller supplies one; otherwise they
+                // fall back to the content channel (CLI mixes both).
+                onContentUpdate: (content) => {
+                    if (content.trim()) {
+                        options.onContentUpdate?.(content);
+                    }
+                },
+                onReasoningUpdate: (reasoning) => {
+                    if (reasoning.trim()) {
+                        if (options.onReasoningUpdate) {
+                            options.onReasoningUpdate(reasoning);
+                        }
+                        else {
+                            options.onContentUpdate?.(reasoning);
+                        }
+                    }
+                },
             });
             if (result.usage) {
                 totalUsage = {
@@ -652,10 +674,12 @@ export class AIManager {
      * Fork-path compaction: deny all tool calls locally (the model is told to
      * summarize, not act) and feed the rejections back for another turn.
      */
-    async runCompactFork(historyMessages, compactPrompt, abortSignal) {
+    async runCompactFork(historyMessages, compactPrompt, abortSignal, onContentUpdate, onReasoningUpdate) {
         return this.runForkLoop(historyMessages, compactPrompt, {
             maxTurns: MAX_FORK_TURNS,
             deniedToolMessage: "Tool use is not allowed during compaction",
+            onContentUpdate,
+            onReasoningUpdate,
         }, abortSignal);
     }
     /**
@@ -811,8 +835,10 @@ export class AIManager {
             }
         };
         // Fire-and-forget: the fork runs to completion in the background; the
-        // caller gets the task ID immediately.
-        (async () => {
+        // caller gets the task ID immediately. Tracked in the async work registry
+        // so destroy() drains it before returning (abort via the task's onStop
+        // makes the loop settle).
+        const forkPromise = (async () => {
             try {
                 const result = await this.runForkLoop(historyMessages, prompt, {
                     // /subtask aligns with Claude Code's fork subagent
@@ -859,6 +885,7 @@ export class AIManager {
                 abortCleanup?.();
             }
         })();
+        this.asyncWorkRegistry?.track(forkPromise);
         return taskId;
     }
     /**

package/dist/managers/subagentManager.d.ts

@@ -75,6 +75,7 @@ export declare class SubagentManager {
     private stream;
     constructor(container: Container, options: SubagentManagerOptions);
     private get configurationService();
+    private get asyncWorkRegistry();
     /**
      * Initialize the SubagentManager by loading and caching configurations
      */

package/dist/managers/subagentManager.js

@@ -23,6 +23,9 @@ export class SubagentManager {
     get configurationService() {
         return this.container.get("ConfigurationService");
     }
+    get asyncWorkRegistry() {
+        return this.container.get("AsyncWorkRegistry");
+    }
     /**
      * Initialize the SubagentManager by loading and caching configurations
      */
@@ -331,7 +334,7 @@ export class SubagentManager {
                 instance.backgroundTaskId = taskId;
                 // Execute in background
                 // Note: notification enqueueing is handled by internalExecute when instance.backgroundTaskId is set
-                (async () => {
+                const backgroundPromise = (async () => {
                     try {
                         const result = await this.internalExecute(instance, prompt, abortSignal);
                         const task = backgroundTaskManager?.getTask(taskId);
@@ -360,6 +363,7 @@ export class SubagentManager {
                         this.releaseInstance(instance.subagentId);
                     }
                 })();
+                this.asyncWorkRegistry?.track(backgroundPromise);
                 return taskId;
             }
             const result = await this.internalExecute(instance, prompt, abortSignal);

package/dist/services/hook.js

@@ -7,6 +7,8 @@
  */
 import { spawn } from "child_process";
 import { generateSessionFilePath } from "./session.js";
+import { resolveShellPath } from "../utils/shellResolver.js";
+import { toPosixCommand } from "../utils/windowsPaths.js";
 // =============================================================================
 // Hook Execution Functions
 // =============================================================================
@@ -56,10 +58,10 @@ async function buildHookJsonInput(context) {
     if (context.subagentType !== undefined) {
         jsonInput.subagent_type = context.subagentType;
     }
-    // Add name field for WorktreeCreate events
+    // Add name field for WorktreeCreate events (aligned with Claude Code)
     if (context.event === "WorktreeCreate") {
-        if (context.worktreeName !== undefined) {
-            jsonInput.name = context.worktreeName;
+        if (context.name !== undefined) {
+            jsonInput.name = context.name;
         }
     }
     // Add worktree_path field for WorktreeRemove events
@@ -133,11 +135,43 @@ export async function executeCommand(command, context, options) {
         let stdout = "";
         let stderr = "";
         let timedOut = false;
-        // Parse command for shell execution
+        // Parse command for shell execution.
+        //
+        // Windows uses Git Bash (POSIX shell) instead of cmd.exe: cmd.exe's `/c`
+        // does not strip quotes from arguments after the first token, so commands
+        // like `node "C:\path\script.js"` silently fail (issue #1773). Git Bash
+        // parses quotes correctly, and Windows paths in the command are converted
+        // to POSIX form first (Git Bash resolves `/c/Users/...` and translates it
+        // back to a Windows path when spawning native executables like node.exe).
+        // Falls back to cmd.exe when no Git Bash is installed.
         const isWindows = process.platform === "win32";
-        const shell = isWindows ? "cmd.exe" : "/bin/sh";
-        const shellFlag = isWindows ? "/c" : "-c";
-        const childProcess = spawn(shell, [shellFlag, command], {
+        const bashPath = isWindows ? resolveShellPath() : undefined;
+        let shell;
+        let shellFlag;
+        let finalCommand;
+        if (bashPath) {
+            shell = bashPath;
+            shellFlag = "-c";
+            finalCommand = toPosixCommand(command);
+            // Windows .sh scripts aren't directly executable — run them via bash
+            // when the command itself is a .sh file (e.g. `${WAVE_PLUGIN_ROOT}/x.sh`).
+            const trimmed = finalCommand.trim();
+            const firstToken = trimmed.match(/^("([^"]*)"|'([^']*)'|\S+)/)?.[0] ?? "";
+            if (firstToken.endsWith(".sh") && !trimmed.startsWith("bash ")) {
+                finalCommand = `bash ${finalCommand}`;
+            }
+        }
+        else if (isWindows) {
+            shell = "cmd.exe";
+            shellFlag = "/c";
+            finalCommand = command;
+        }
+        else {
+            shell = "/bin/sh";
+            shellFlag = "-c";
+            finalCommand = command;
+        }
+        const childProcess = spawn(shell, [shellFlag, finalCommand], {
             stdio: ["pipe", "pipe", "pipe"],
             cwd: context.projectDir,
             env: {

package/dist/services/initializationService.js

@@ -127,27 +127,6 @@ export class InitializationService {
         catch (error) {
             logger?.warn("SessionStart hooks execution failed:", error);
         }
-        // Trigger WorktreeCreate hook if this is a new worktree
-        if (agentOptions.isNewWorktree && hookManager) {
-            try {
-                logger?.info(`Triggering WorktreeCreate hook for ${agentOptions.worktreeName}...`);
-                const hookResults = await hookManager.executeHooks("WorktreeCreate", {
-                    event: "WorktreeCreate",
-                    projectDir: workdir,
-                    timestamp: new Date(),
-                    sessionId: messageManager.getSessionId(),
-                    transcriptPath: messageManager.getTranscriptPath(),
-                    cwd: workdir,
-                    worktreeName: agentOptions.worktreeName,
-                    env: Object.fromEntries(Object.entries(configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
-                });
-                // Process hook results
-                hookManager.processHookResults("WorktreeCreate", hookResults, messageManager);
-            }
-            catch (error) {
-                logger?.warn("WorktreeCreate hooks execution failed:", error);
-            }
-        }
         // Resolve and validate configuration after loading settings.json
         resolveAndValidateConfig();
         // Initialize auto-memory directory

package/dist/services/jsonlHandler.d.ts

@@ -10,6 +10,20 @@ import type { SessionFilename } from "../types/session.js";
 export interface JsonlWriteOptions {
     atomic?: boolean;
 }
+/**
+ * Creation-time metadata persisted in the session file's header line
+ * (`{"type":"metadata",...}`). The header is append-only — written once on
+ * session creation and never rewritten — so only fields that are fixed at
+ * creation time belong here.
+ */
+export interface SessionMetadataHeader {
+    /** Real working directory (the encoded project dir name is lossy for paths containing "-"). */
+    workdir?: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt?: string;
+    /** Git branch at creation time (`git branch --show-current`), when the directory is a git repo. */
+    gitBranch?: string;
+}
 /**
  * JSONL handler class for message persistence operations
  */
@@ -17,9 +31,20 @@ export declare class JsonlHandler {
     private readonly defaultWriteOptions;
     constructor();
     /**
-     * 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.
      */
-    createSession(filePath: string): Promise<void>;
+    createSession(filePath: string, metadata?: SessionMetadataHeader): Promise<void>;
     /**
      * Append a single message to JSONL file
      */
@@ -40,6 +65,16 @@ export declare class JsonlHandler {
      * Get the last message from JSONL file using efficient file reading (simplified)
      */
     getLastMessage(filePath: string): Promise<Message | null>;
+    /**
+     * 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
+     */
+    readMetadata(filePath: string): Promise<SessionMetadataHeader | null>;
     /**
      * Validate messages before writing
      */