Hooks

Configure a hook

Add a hooks object to your user ~/.junie/config.json or to a file passed with --config-location:

Each entry has a matcher and a list of hooks to run when the matcher matches.

Project-local hooks from <project-root>/.junie/config.json are ignored by default for safety. Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. If you intentionally want to run hooks from a project file, pass that file explicitly with --config-location.

Triggering events

Hook input

Each hook receives a single line of JSON on standard input:

For UserPromptSubmit, the payload carries the prompt text:

For PreToolUse, the payload carries the tool name and its full input:

For SessionEnd, the payload uses reason instead of source:

For Stop, the payload carries the agent's submission text and a retry flag:

stop_hook_active is true on every re-run that follows a previous Stop block in the same task; false on the first dispatch. When the agent's submission text is empty, last_assistant_message is sent as an empty string (not the literal word Empty).

For PermissionRequest, the payload describes the action that triggered the permission dialog:

tool_name is the tool category (Bash, Edit, Read, or an MCP tool name). tool_input contains the full serialized action.

For StopFailure, the payload carries the matched error class and the underlying failure description:

error is the matcher target (one of the 9 values listed in the StopFailure section). error_details is always present, but its source depends on the underlying failure category: for rate_limit it is the dynamic provider response (e.g. the body of a 429), for model_refused and country_forbidden it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (authentication_failed, billing_error from CostExceeded, invalid_request, server_error from InferenceServerTimeout/BadResponseException, max_output_tokens, unknown from UnexpectedException) it is a static description of the failure class rather than a provider-supplied string.

The field names match Claude Code's StopFailure wire protocol, so the same hook script can be shared between agents.

Run hooks in the background

By default, a hook blocks the triggering action until it completes — the prompt waits for UserPromptSubmit, the tool waits for PreToolUse, and so on. For long-running tasks (test suites, deployments, external API calls) set "async": true on the hook command to run it in the background while the agent keeps working.

Failure handling

Hook output and exit status do not block Junie startup:

• Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history.

• A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start.

• If the command exceeds its timeout, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start.

• Invalid hook configuration, such as an unsupported type, invalid matcher, or non-positive timeout, is shown as a TUI error message. Junie continues to start.

Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks.

Stop hook blocking and retries

A Stop hook can request the agent to retry submission by:

• Exiting with status code 2. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used.

• Printing {"decision":"block","reason":"…"} to stdout on a successful exit. The reason is appended to the agent's state as an observer message so the agent can address the issue and submit again.

• Setting blockOnError: true on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason.

To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the JUNIE_STOP_HOOK_BLOCK_CAP environment variable; set it to 0 to disable the cap.

A Stop hook can request a hard halt (no retry, the task ends with a failure exit status) by printing {"continue":false,"stopReason":"…"} to stdout on a successful exit. continue: false takes precedence over decision: "block". Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status.

A Stop hook can send messages on a successful exit through two distinct JSON fields:

• {"hookSpecificOutput":{"additionalContext":"…"}} (or a top-level additionalContext) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a block (retry), a continue: false hard-halt, and on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits additionalContext without decision: block, the agent runs one extra step with the context attached and then submits. The shared JUNIE_STOP_HOOK_BLOCK_CAP counter bounds runaway continuations the same way it bounds blocks.

• {"systemMessage":"…"} — user-facing payload. The Stop executor does not currently surface it in the TUI.

Both fields are accumulated across all hooks that ran in the chain.

Merging hooks across configuration files

When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. Higher-priority files do not override lower-priority files; their entries are appended.

Only trusted sources participate in hook merging: user configuration and explicit --config-location files. Default project-local hooks entries are skipped and reported as a hook configuration warning.

For the configuration precedence order, see Configuration files.

Limitations

• The supported events are SessionStart, UserPromptSubmit, PreToolUse, Stop, StopFailure, PermissionRequest, and SessionEnd.

• UserPromptSubmit is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it.

• SessionStart, PreToolUse, Stop, StopFailure, PermissionRequest, and SessionEnd are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them.

• StopFailure is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; decision: block and continue: false are demoted to TUI failure notifications.

• StopFailure fires only on classified LLM/API failures (the 9 error values listed in the StopFailure section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future PostToolUseFailure hook.

• Only type: "command" hooks are supported.

• Hooks within a single entry run sequentially. Parallel execution is not supported.

• SessionEnd hooks cannot block session termination, even if they return a non-zero exit code or decision: block in their stdout.

• SessionEnd dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command timeout will be effectively bounded by this overall budget.

• Stop hooks do not run for chat-type tasks.

• blockOnError is a Junie extension and is honoured for Stop hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle.

• The Stop stdin contains only hook_event_name, stop_hook_active, and last_assistant_message.

• On /new or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its SessionEnd hook is not dispatched on the switch. Only the incoming session's SessionStart hook fires (with source: clear for a fresh /new, source: resume for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither SessionStart nor SessionEnd.

• Hook output is discarded for SessionEnd. For PreToolUse, additionalContext is added to the model context and updatedInput can replace the tool's input for that call.

• The SessionStart/UserPromptSubmit/SessionEnd executors log continue: false as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only Stop maps continue: false to a real abort action.

• additionalContext on stdout — agent-facing, never published to the TUI. For sync hooks: UserPromptSubmit prepends it to the prompt; Stop folds it into the agent's observer message on block / hard-halt retries and on a plain successful exit (Claude-style continue, see Stop hook blocking and retries); PreToolUse adds it to the model context for that tool step; SessionStart, SessionEnd, and PermissionRequest ignore it. For async hooks (async: true): the field is queued and prepended to the next user submit regardless of the originating event.

• systemMessage on stdout — user-facing TUI info message, published as <Event> hook: <message>. For sync hooks it is honoured by the SessionStart, SessionEnd, and UserPromptSubmit executors. For async hooks it is published on completion for any event that supports async: true.

• PermissionRequest hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly.