Declarative hook profiles with explicit capability boundaries

[tonythethompson]

Problem

Nushell hooks are stateful configuration that can run package code in response to interactive events. Treating them as ordinary modules would either require unsafe config-file mutation or make activation semantics opaque. Numan currently has no first-class model for them.

Goal

Specify an opt-in hook-profile capability that composes only Numan-managed hook registrations, is fully reversible, and makes runtime triggers visible before enablement.

Proposed contract

• Hook support is a distinct capability/profile, not implicit behavior of a module, script, or package install.
• A manifest declares structured bindings: supported event, package-local handler, optional filter, and stable binding ID. Arbitrary config-record injection is out of scope.
• numan inspect displays every declared trigger and handler before activation. Enabling hooks requires an explicit activation mode/flag separate from ordinary package activation.
• Numan writes or sources only a generated, ownership-marked integration surface. It must preserve user-owned $env.config.hooks entries and never rewrite a user's configuration file wholesale.
• Binding merge semantics are additive and identity-based. Duplicate IDs or incompatible bindings fail closed rather than shadowing one another.
• Handler code never executes during install, inspect, lock, update, deactivate, or recovery. It executes only when Nushell emits the declared event in a later interactive session.
• Deactivation removes exactly the owned binding and preserves unrelated user/package hooks.

Safety constraints

• Start with a deliberately small allow-list of hook events whose composition and acceptance behavior can be proven.
• No automatic directory-triggered activation, no implicit network access policy, and no hidden environment mutation.
• Hook profiles must participate in lockfile/state provenance and show as a higher-risk capability in status/inspect output.
• Interrupted activation must recover to either the prior known-good hook profile or a disabled state; never a partially merged one.

Acceptance criteria

• A design note documents the supported event allow-list, binding schema, merge rules, conflict rules, lifecycle states, and exact user-config boundary.
• Fixtures cover clean enable/disable, preservation of user hooks, duplicate binding IDs, malformed handlers, update, drift, and interruption recovery.
• Real-Nu acceptance tests prove hooks run only for their declared event, survive a new shell, and are gone after deactivation on Linux, macOS, and Windows.
• numan inspect and numan status make hook capability and active event bindings visible.

Non-goals

• Importing or rewriting arbitrary existing $env.config.hooks.
• Enabling hooks merely because a package was installed.
• Providing generic event automation beyond Nushell's supported hook model.