Module hooks 

User-configurable shell commands that fire on scheduler events.

Hooks are off by default and gated behind a confirmation dialog (see scheduler::commands::hooks::set_hooks). The threat model is documented in docs/HOOKS.md — anyone with write access to settings.json can run arbitrary code as the user, so the master hooks_enabled toggle is the sole trust boundary.

Structs

Hook

One configured hook: subscribe to event, run command when it fires (if enabled). command is POSIX-style argv that we split with shell-words — no shell is involved, so pipes / redirects need an explicit sh -c wrapper.

HookContext

Per-call context populated by the scheduler. Fields show up as $ENTRACTE_KIND, $ENTRACTE_DURATION_SECS, $ENTRACTE_OUTCOME when the hook child runs; empty when not applicable to the event.

Enums

HookEvent

The scheduler events a hook can subscribe to. Serialised as the lowercase snake-case name (also the value passed in $ENTRACTE_EVENT).

Constants

MAX_HOOKS_PER_EVENT

Hard cap on hooks fired per event. A misconfigured (or malicious) settings.json could otherwise register thousands of entries and fork-bomb the host on every break boundary. 32 is well above any realistic per-event subscription count.

Functions

build_env

Build the (key, value) env vars handed to the hook child: ENTRACTE_EVENT, ENTRACTE_KIND, ENTRACTE_DURATION_SECS, ENTRACTE_OUTCOME. Missing fields are empty strings so consumers can shell-test them uniformly.

kind_str 🔒

matching_hooks

Return the subset of hooks that should fire for event. Returns empty when the master hooks_enabled toggle is off, regardless of per-hook enabled flags.

program_log_label 🔒

run_hooks

Fire every matching hook for event. Each child runs on its own std::thread and inherits stdio from /dev/null. Fire-and-forget: we never block on the child or capture its output.

run_hooks_with

Same as run_hooks but delegates spawning to spawn. The callback receives each Hook (already filtered by event and enabled, and already truncated to MAX_HOOKS_PER_EVENT) plus the env vars that would be passed to its child. Used by tests to verify the cap without actually shelling out hundreds of processes.

spawn_hook 🔒