# ADR-009: Role hooks are the role author's domain (https://jackin.tailrocks.com/reference/adrs/adr-009-role-hooks-authors-domain/)



**Status**: Accepted

jackin❯ runs role hooks (`setup-once.sh`, `source.sh`, `preflight.sh`) exactly as the role author wrote them and does not police, sandbox, rewrite, or rate-limit them. The only responsibilities of jackin❯ are to run them as the standard start flow and to hard-fail the start, surfacing the error, when a hook exits non-zero. Deterministic dependency installation is steered toward the role's own Dockerfile by documentation, not by any enforcement mechanism.

## Why this is recorded [#why-this-is-recorded]

The runtime-restore work is partly motivated by slow startups, and a tempting "fix" is to make jackin❯ detect heavy hooks (e.g. `mise install`), warn, or run hooks in a no-network / read-only sandbox so runtime installs fail. We explicitly rejected all of that. A future contributor chasing startup speed will likely propose hook-policing again; this records that it is a deliberate non-goal, so the next person does not "fix" something that was decided.

## Considered options [#considered-options]

* **Detect installer commands and warn (or `--debug` hard-fail).** Rejected: jackin❯ should not judge hook contents; a hook is the author's chosen way to run things, and detection by text-scan is brittle while detection by timing punishes legitimately slow-but-correct hooks.
* **Run hooks in a restricted sandbox (no network / read-only rootfs) so runtime installs physically fail.** Rejected: it also breaks legitimate hooks that need network (preflight reachability checks) or disk writes (per-instance state), and constrains what roles can do at start.
* **Run hooks faithfully; hard-fail on non-zero exit; document intended use (chosen).** jackin❯ reports failures faithfully and otherwise stays out of the way.

## Consequences [#consequences]

* A role that installs dependencies at runtime stays slow; that latency is the author's to own, by the author's choice. The contract of jackin❯ (no runtime agent install, no runtime plugin install, image-baked default state) is unaffected and remains enforced.
* The intended split — `setup-once.sh` = per-instance state init, `source.sh` = env/PATH, `preflight.sh` = cheap validation, deterministic deps = role Dockerfile — is author-facing guidance, not a jackin❯-enforced rule.
* No new image-build hook is added; the role's own Dockerfile is the build-time surface.