Guide / artifact / HOOK

HOOK artifact: automate on an event

Use a HOOK artifact for a script that a supported provider runs when a mapped session, prompt, tool or agent event occurs.

The hook props

A hook has three required content properties. trigger is the provider-neutral event name, hook_category describes the hook family expected by the distribution contract, and entrypoint points to the executable file in the bundle.

trigger Use a mapped value such as session_start, prompt_submit, pre_action, post_action, permission_request, subagent_start, subagent_stop, context_pre_compact or agent_stop. Mappings differ by provider.
hook_category Declare the category required by the artifact contract. Keep it stable when updating a hook so consumers can reason about its behavior.
entrypoint Relative executable path such as hooks/on-prompt.sh. The file must be included in files and is chmod 0755 during application.

Example hook

This hook receives its event through the provider's hook adapter. The script is copied into a HubBound-owned directory and registered with ownership metadata.

{
  "trigger": "prompt_submit",
  "hook_category": "command",
  "entrypoint": "hooks/on-prompt.sh"
}

Safety and portability

A hook is executable code. Review it like code, keep it small and make its behavior explicit. Unknown triggers are soft-skipped by providers that have no confident native mapping; they are not silently translated into a different event.

  • Never put secrets in the script or manifest; read them from the environment supplied by the user or provider.
  • Avoid destructive commands by default and fail closed when required input is absent.
  • Use portable shell or document the runtime when the hook needs a specific interpreter.
  • Include every imported helper in files; the release snapshot does not follow arbitrary runtime paths.

What install does

Supported providers copy the full artifact files into a managed HubBound hook directory, mark the entry as owned, make the entrypoint executable and register the mapped event. Uninstall removes only the HubBound-owned registration and files.

Deploy guide