When Are Background Hook Pipelines Spawned Concurrently in Worktrunk?

Background hook pipelines in Worktrunk spawn concurrently immediately after the main command succeeds, with all registered post-hooks launching simultaneously as detached processes rather than executing sequentially.

Worktrunk orchestrates post-operation hooks through a sophisticated background pipeline system in the max-sixty/worktrunk repository. Understanding when and how these background hook pipelines activate is crucial for optimizing workflow automation and resource management. This article examines the concurrent execution model as implemented in the source code.

The Trigger Point for Concurrent Execution

Background hook pipelines activate only after the primary command completes successfully. When you execute operations like merge, remove, or start, Worktrunk first completes the main task, then initiates the background phase.

According to the source code in src/commands/hook_plan.rs (lines 405-415), the system registers applicable background hooks—such as post-merge, post-remove, or post-start—immediately after the primary operation succeeds. The HookPlan determines which hooks apply to the current command context and prepares them for concurrent execution.

How the HookAnnouncer Orchestrates Concurrent Spawning

The HookAnnouncer struct serves as the central coordinator for launching background pipelines. Located in src/commands/hook_announcement.rs, this component manages the transition from registration to execution.

Registration Phase

Before spawning, the system collects all relevant hooks into the announcer's registry. The HookPlan identifies which post-hooks match the current command type and registers them for background execution, ensuring only relevant pipelines are queued for the operation.

Concurrent Spawning Mechanism

At lines 425-440 of src/commands/hook_announcement.rs, the spawn_registered_hooks method iterates through all registered hooks and launches them simultaneously. Rather than awaiting each hook's completion sequentially, the announcer invokes spawn_detached_exec for every registered pipeline in rapid succession.

The actual process spawning implementation resides in src/commands/process.rs (lines 339-360). Here, the spawn_detached_exec function creates detached wt hook run-pipeline processes for each registered hook. This approach ensures true concurrency, as each pipeline operates independently with its own output logging and process context.

Foreground vs. Background Execution Context

Worktrunk distinguishes between inline and detached execution modes. As documented in src/cli/mod.rs (lines 1620-1630), post-hooks run in the background by default, with output redirected to log files. Users can override this behavior using wt hook <type> --foreground to execute hooks inline within the main process, blocking until completion.

The priority model described in src/priority.rs (lines 41-62) confirms that background pipelines execute as separate detached processes, allowing the main command to return control to the user immediately while hooks continue processing asynchronously.

Practical Code Example

The following Rust code illustrates the concurrent spawning pattern found in the Worktrunk source:

// From src/commands/hook_announcement.rs
pub fn spawn_registered_hooks(&self) -> Result<()> {
    for hook in self.registered_hooks.iter() {
        // Each hook spawns immediately without awaiting others
        spawn_detached_exec(
            &hook.command, 
            &hook.log_path, 
            &hook.context_json
        )?;
    }
    Ok(())
}

This iteration demonstrates the concurrent nature: the loop processes all registered hooks without blocking between iterations, creating multiple detached processes nearly simultaneously via spawn_detached_exec.

Summary

• Background hook pipelines spawn immediately after the main command succeeds, not before or during
• The HookAnnouncer coordinates all spawning through src/commands/hook_announcement.rs (lines 425-440)
• All registered post-hooks launch concurrently via spawn_detached_exec in src/commands/process.rs (lines 339-360)
• Execution occurs as detached wt hook run-pipeline processes, not sequential blocking calls
• Hook registration and filtering occurs in src/commands/hook_plan.rs (lines 405-415) before spawning begins

Frequently Asked Questions

What triggers background hook pipelines to start in Worktrunk?

Background hook pipelines trigger immediately after the primary command completes successfully. The system first finishes operations like merge or remove, then registers applicable post-hooks through the HookPlan and spawns them all at once via the HookAnnouncer.

Do background hooks run sequentially or in parallel?

Background hooks run in parallel. The HookAnnouncer's spawn_registered_hooks method iterates through all registered hooks and calls spawn_detached_exec for each without awaiting completion, creating concurrent detached processes for every registered pipeline.

Can I run Worktrunk hooks in the foreground instead of background?

Yes. According to src/cli/mod.rs, you can execute hooks inline using the --foreground flag with wt hook <type>. This runs the hook pipeline within the main process rather than spawning a detached background process, allowing you to observe output directly in the terminal.

Where does Worktrunk handle the actual process spawning for hooks?

The actual process spawning occurs in src/commands/process.rs within the spawn_detached_exec function (lines 339-360). This function creates the detached wt hook run-pipeline processes that execute the background hooks independently, as noted in the priority model documentation at src/priority.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}