Hooks
Shell commands that fire on session lifecycle events — and the git-safety check that runs on discard.
A hook is a shell command actor.sh runs at a lifecycle moment. Hooks attach side effects — set up a sandbox, post a notification, guard against data loss — without changing actor.sh itself.
The two hooks
| Hook | Fires | On failure |
|---|---|---|
on-start | once, when a session is created | the creation is rolled back |
on-discard | once, when a session is discarded | the discard is refused (unless --force) |
Both are single shell commands, run via /bin/sh -c. They're configured in
settings.kdl:
hooks {
on-start "echo \"starting $ACTOR_NAME in $ACTOR_WORKSPACE\""
on-discard "my-cleanup-script"
}
Environment
Hooks receive context about the session as environment variables — its name, its workspace path, and its agent — so one script can behave correctly for any session it fires on.
The git-safety default
Even with no hooks block configured, actor.sh ships a default on-discard
hook: it refuses to discard a session whose worktree has any uncommitted
state — staged, unstaged, or untracked. This is the check behind
discarding:
uncommitted work is never thrown away silently.
Pass --force to discard to bypass a failing on-discard hook (including
this default).
Defining your own on-discard hook replaces the default — if you still want
the git-safety behaviour, build it into your command.