perf(alias): skip unused template-var accessors in hook context

[max-sixty]

build_hook_context used to run git rev-parse <branch> for {{ commit }} and git for-each-ref for {{ upstream }} on every alias and hook dispatch, regardless of whether the pipeline referenced those vars. The referenced_vars_for_config set (already computed for --KEY=VALUE routing) now gates each accessor: a var is populated only if some template in the pipeline references it.

Addresses the parent-side piece of #2322: on macOS hosts with slow execve (~200 ms/fork), simple aliases now skip two guaranteed forks. On healthy systems each saved fork is ~3–5 ms, so the proportional win is similar but the absolute number is smaller.

Scope

• run_alias and prepare_steps pass the referenced_vars_for_config union to gate accessors.
• Preview/debug paths (wt step eval, wt switch --execute, wt hook <type> preview, wt step for-each) pass None — they want the full context for inspection.
• Verbose mode (-v) at alias and hook dispatch sites passes None: the template-variable table prints (unset) for anything not populated, and users running -v are debugging and expect every var.

Accurate error hints

expand_shell_template now takes an optional ValidationScope. When template expansion fails with an undefined-variable error, the "Available variables" hint lists every var the scope supports (via vars_available_in) rather than only the keys currently populated at runtime. Without this, lazy gating would narrow the hint — a template with a typo or a legitimately-unset var would see a shorter list omitting vars the pipeline didn't reference. The hint is meant to answer "what could you have typed," which is a property of the scope, not of this invocation's gated context.

As a bonus the hint now correctly lists scope-valid vars that weren't populated eagerly either (upstream, owner, pr_number, pr_url, hook_name for a pre-start hook), so users chasing "undefined value" for those vars see them suggested.

Benchmarks (benches/alias, warm OS cache, macOS)

The bench matrix now covers three alias variants against the same repo: noop (zero vars), commit ({{ commit }}), everything (all gated vars via | default).

variant	warm/1	warm/100	delta vs pre-#2340 noop baseline
noop	45 ms	45 ms	−18% / −22%
commit	52 ms	49 ms	noop + rev-parse fork
everything	54 ms	49 ms	noop + rev-parse + for-each-ref

commit/everything land close to the pre-change baseline because they exercise the same accessors as before. The gap between noop and commit/everything (~4–7 ms) is the cost of the 2 forks lazy gating avoids — extrapolated to Mark's macOS (#2322) that's ~400 ms saved per simple-alias dispatch.

Test plan

• cargo run -- hook pre-merge --yes — 3318 tests, 0 failures; lints green
• RUST_LOG=worktrunk=debug wt noop trace confirms noop alias drops from 7 → 5 git subprocesses in the parent; wt showall (references all gated vars) keeps 7

Co-Authored-By: Claude noreply@anthropic.com

[worktrunk-bot]

Lazy gating cleanly delegates to the existing referenced_vars_for_config and the verbose-mode bypass keeps -v debugging accurate. The bench matrix split (noop/commit/everything) is a nice regression guard for future accessor changes. One concern about a silent contract change in stdin JSON — see inline.

The user-facing docs in docs/content/hook.md (## JSON context) and the matching block in src/cli/mod.rs still claim "Hooks receive all template variables as JSON on stdin". With this change, vars not referenced by any template in the pipeline are gated out of the context map, so they're also missing from the JSON piped to the script. A Python hook doing ctx['default_branch'] (or commit, upstream, owner, remote_url) when no template references those vars will now hit a KeyError it didn't hit before — and the failure is opaque from the user's side (their hook script didn't change). Worth either a docs update calling out the new behavior or always populating the JSON eagerly even when the template gates accessors out.

[worktrunk-bot]

Suggested change

	/// `main_worktree_path` that share accessors with canonical names). When `None`,
	/// every accessor runs — used by preview/debug paths that want the full context.
	/// `main_worktree_path` that share accessors with canonical names). When `None`,
	/// every accessor runs — used by preview/debug paths that want the full context.
	///
	/// Vars skipped by gating are also absent from the JSON piped to hook stdin,
	/// so scripts that read context fields not referenced in any template will
	/// see those keys missing.

[worktrunk-bot]

codecov/patch: 96.12% vs 96.62% target — 0.5% under, ~1–2 lines on this diff. Most likely uncovered candidates, in order: (1) the Alias arm of origin_scope (no alias test currently triggers a template-expansion error to exercise it — post_create_upstream_template.snap only covers the Hook arm); (2) the main_worktree_path deprecated-alias branch in build_hook_context (no test references it); (3) the is_empty() early-return in override_available_vars. The first two are easy to add — happy to push a follow-up commit with an alias-error test plus a main_worktree_path template reference if you'd like, otherwise leaving it to you.

[max-sixty]

one downside of this is that it breaks the json piping to stdin

so I think we should leave to see how much it improves things once everything else merges