#Hooks and Scripts

A credential-free release-preparation session. It proves the two contracts that are easiest to get wrong by hand: the generated hook wrapper, and the process envelope the framework puts around an authored script.

• Run from the repository root: pnpm example:hooks
• Package: @agent-bundle-example/hooks-and-scripts
• Public dependencies: agent-bundle (workspace:*)
• Targets: portable, codex, claude
• Credentials: none: the example reads only checked-in JSON under release/
• Source: examples/hooks-and-scripts

#What it proves

• A hook is authored as a handler, not a host document. src/hooks/session-start.ts is one module that calls the application-owned releaseContext function. The build bundles that plain Node dependency into each host wrapper; it does not start an MCP server or render worker. See Hooks.
• Both script declaration modes. verify-release ships by convention: any unclaimed plain script under src/scripts/ is discovered, while detect-risk stays explicitly configured because it restricts its targets to portable. The example keeps both modes covered on purpose.
• The framework owns the process envelope. Both scripts export main and return an exit code. Argv handling, awaiting, and exit-code adoption belong to the generated envelope, so a nonzero return becomes a real blocking exit rather than a swallowed value. See Scripts and assets.
• Emitted scripts resolve their own assets. assets: ['release/*.json'] copies the release manifest and risk register once into the artifact root's assets/, shared by every target, and each emitted script reads them relative to its own module, never relative to the shell's working directory.
• A failed rebuild keeps the last-good artifact. That is the reversible walkthrough below.

#What is authored

#Working in the Workbench

1. The header is the authoritative current-or-stale epoch state. Under Application → Events / Hooks, select sessionStart, choose the Claude fixture, and run it. The event route workspace shows canonical input, including "source": "workbench", and the projected result. Use its Replay tab to rerun the epoch-bound input.
2. Under Application → Scripts, select verify-release for the Claude target and run it. The emitted script reads the packaged release/release-manifest.json beside its own module and reports release 2.4.0 ready for packaging.
3. Switch the target to portable and select detect-risk. It reads release/risk-register.json, reports high-severity REL-204, exits with code 2, and finalizes a durable blocking trace.
4. Follow the runs in Trace to see each invocation and kernel phase; an attached host's real hook delivery adds its correlated receipt there too. Use Open route to restore a recorded snapshot. Use Advanced → Raw logs for uncorrelated producer details, Advanced → Artifact for emitted files and provenance, and Advanced → Evals → Compare after two eval runs exist.

#The reversible diagnostic walkthrough

The checked-in project is healthy, so seeing last-good behavior means breaking it on purpose. Temporarily replace the body of src/hooks/session-start.ts with a syntactically incomplete handler, press Rebuild, and wait for the completed Failed state. Open Problems from the header failure count: the Workbench reports the new diagnostic while Application continues to expose the last-good tree and artifact. Restore the checked-in handler, press Rebuild again, and wait for Idle: a new active epoch replaces the stale catalog and clears the diagnostic.

Do not read a Building state as a completed repair, the new active epoch is the evidence.

#Noninteractive checks

After the repository-level pnpm build:

cd examples/hooks-and-scripts
pnpm validate
pnpm build

pnpm check is the same validation-and-build pair in one command. To exercise the emitted hook wrapper without the Workbench, use the CLI's own hook surface:

pnpm exec agent-bundle hooks list --artifact artifact