Hooks

Hooks run a shell command or send an HTTP request when something happens in Enconvo, such as an agent starting, completing, failing, or using a tool. You set them up in a JSON file, so you can add notifications, logs, local automation, or integrations without building an extension.

Most hooks are fire-and-forget: they run in the background and don’t block Enconvo. PreToolUse, Stop, and SubagentStop are the exception during agent runs. The agent waits for them, so they can block a tool call or send the agent back to work. See Blocking hooks.

Quick start

Create the hooks folder

mkdir -p ~/.enconvo

Create ~/.enconvo/hooks.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Agent status changed' >> /tmp/enconvo-hooks.log"
          }
        ]
      }
    ]
  }
}

Trigger an agent

Start any agent or chat command. When its status changes, Enconvo runs the configured command and appends a line to /tmp/enconvo-hooks.log.

Config file

Hooks live in:

~/.enconvo/hooks.json

Enconvo also reads the legacy file at ~/.config/enconvo/hooks.json when the new file doesn’t exist. If both files exist, ~/.enconvo/hooks.json wins. The file is read again whenever an event fires, so you can edit hooks while Enconvo is running. You don’t need to restart.

Manage hooks in Settings

Open Settings → Hooks to see the hooks in ~/.enconvo/hooks.json, grouped by event. Turn an entry on or off with its switch, or click Open hooks.json to edit the file. Turning an entry off or on writes enabled: false or enabled: true on that entry, without changing its command or webhook.

How hooks work

When an event fires, Enconvo:

Loads ~/.enconvo/hooks.json.
Falls back to ~/.config/enconvo/hooks.json only if the new file is absent.
Finds entries inside the top-level hooks object whose key matches the event name.
Applies the optional matcher regex.
Skips entries where enabled is false.
Runs every configured hook concurrently.

Hook event names follow the Claude Code and Codex lifecycle set: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, Stop, and SubagentStop. The old Enconvo event names and the old flat JSON shape still work for existing installs, but new writes use the wrapped Codex-style format.

Configuration reference

{
  "hooks": {
    "event_name": [
      {
        "matcher": "optional_regex_filter",
        "enabled": true,
        "hooks": [
          { "type": "command", "command": "..." },
          { "type": "http", "url": "..." }
        ]
      }
    ]
  }
}

Field	Type	Required	Description
`hooks`	object	Yes	Event map keyed by event name.
`event_name`	string	Yes	Event to listen for. Use this as a key inside `hooks`.
`matcher`	string	No	Regex filter. For tool events, it matches `toolName`, `toolTitle`, or `path`; for other events, it matches the hook event name.
`enabled`	boolean	No	Set to `false` to keep the entry in config but skip execution. Defaults to `true`.
`hooks`	array	Yes	Command and HTTP hooks to execute.

Command hook

A command hook runs a shell command. Enconvo writes the event payload to the command’s stdin as JSON.

{
  "type": "command",
  "command": "bash ~/.enconvo/hooks/on-status-change.sh",
  "timeout": 30000
}

Field	Type	Default	Description
`type`	`"command"`	-	Required hook type.
`command`	string	-	Shell command to execute.
`timeout`	number	`30000`	Timeout in milliseconds.

HTTP hook

An HTTP hook sends the event payload as the JSON request body.

{
  "type": "http",
  "url": "https://example.com/webhook",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "timeout": 30000
}

Field	Type	Default	Description
`type`	`"http"`	-	Required hook type.
`url`	string	-	HTTP endpoint URL.
`method`	string	`"POST"`	HTTP method.
`headers`	object	`{}`	Additional request headers.
`timeout`	number	`30000`	Timeout in milliseconds.

Blocking hooks

During an agent or bot run, three events run as blocking hooks. The agent waits for every matching hook (they run in parallel) before it continues, and reads their result the same way Claude Code and Codex do.

Event	When	What the hook can do
`PreToolUse`	Right before a tool call runs. The `matcher` is checked against the tool name, title, and route path.	Block the call, or rewrite its input.
`Stop`	Right before the agent ends its turn with an answer.	Send the agent back to work with an instruction.
`SubagentStop`	Right before a subagent finishes.	Send the subagent back to work with an instruction.

A hook decides in one of two ways:

Exit code 2 blocks. The text the command writes to stderr is the reason.
Exit code 0 with JSON on stdout. Any other output, exit code, error, or timeout decides nothing, and the run continues as if the hook weren’t there.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Writing outside the project is not allowed."
  }
}

JSON output	Effect
`hookSpecificOutput.permissionDecision: "deny"`	`PreToolUse`: the call does not run. The model sees `permissionDecisionReason` as the tool result and can choose another way.
`hookSpecificOutput.permissionDecision: "ask"`	Treated as `deny`. Enconvo has no confirmation prompt for hooks yet.
`hookSpecificOutput.permissionDecision: "allow"`	`PreToolUse`: the call runs.
`hookSpecificOutput.updatedInput`	`PreToolUse`: the call runs with this input instead of the model’s.
`{ "decision": "block", "reason": "..." }`	`Stop` / `SubagentStop`: the agent keeps working, with `reason` as its next instruction. On `PreToolUse` it blocks the call.
`{ "decision": "approve" }`	Same as `allow`.

HTTP hooks decide with a 2xx response whose body is the same JSON. When several hooks match, a deny wins over ask, which wins over allow. The reasons are joined, and the last updatedInput is used. A Stop hook can send the agent back at most 5 times in one turn. On the second and later checks, stop_hook_active is true, so a hook can let the agent stop once its instruction has been followed. Stop blocking applies only when the agent finishes normally; a failed or stopped run still fires Stop in the background.

The agent waits for blocking hooks, so a slow PreToolUse hook slows every tool call, and a slow Stop hook delays the end of the turn. Keep them fast, set a short timeout, or run slow work in the background (command &).

Blocking hooks receive the regular event payload plus the Claude Code fields at the top level:

{
  "hook_event_name": "PreToolUse",
  "session_id": "Qx2...",
  "cwd": "/Users/you/project",
  "tool_name": "bash",
  "tool_input": { "command": "rm -rf build" },
  "tool_use_id": "call_1",
  "event": "PreToolUse",
  "sourceEvent": "agent_tool_step_changed",
  "params": { "toolName": "bash", "status": "running", "sessionId": "Qx2..." },
  "timestamp": 1742313600000
}

Stop and SubagentStop receive stop_hook_active and last_assistant_message instead of the tool fields. Command hooks run in the agent’s working directory.

Block a dangerous command

#!/bin/bash
# ~/.enconvo/hooks/guard.sh
COMMAND=$(jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -q 'rm -rf /'; then
  echo "Deleting from the filesystem root is not allowed." >&2
  exit 2
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [{ "type": "command", "command": "bash ~/.enconvo/hooks/guard.sh", "timeout": 5000 }]
      }
    ]
  }
}

Make the agent run tests before finishing

#!/bin/bash
# ~/.enconvo/hooks/require-tests.sh
[ "$(jq -r '.stop_hook_active')" = "true" ] && exit 0
echo '{"decision":"block","reason":"Run the test suite and fix any failures before you finish."}'

Event payload

Command hooks receive this JSON on stdin. HTTP hooks receive the same JSON as the request body.

{
  "event": "UserPromptSubmit",
  "fullEvent": "event-UserPromptSubmit",
  "sourceEvent": "run_status_changed",
  "sourceFullEvent": "event-run_status_changed",
  "params": {
    "commandKey": "agent|main",
    "runStatus": "running"
  },
  "timestamp": 1742313600000
}

Field	Description
`event`	Short event name.
`fullEvent`	Internal event name with the `event-` prefix.
`sourceEvent`	Original Enconvo event that produced this hook event, when the event is mapped for Codex compatibility.
`sourceFullEvent`	Original internal event name with the `event-` prefix.
`params`	Event-specific payload.
`timestamp`	Unix timestamp in milliseconds.

Background hooks get the Claude Code fields too: hook_event_name, session_id when the event has one, and, for tool events, tool_name, tool_input, and tool_use_id.

Available events

Event	Params	When
`SessionStart`	`{ command, commandKey }`	A new chat session is created.
`UserPromptSubmit`	`{ commandKey, runStatus, status?, sessionId? }`	An agent, chat, or bot run starts from user input.
`PreToolUse`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call starts. Blocking during agent runs.
`PermissionRequest`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call reaches a permission or denied state.
`PostToolUse`	`{ toolCallId, toolName, toolTitle?, status, sessionId?, commandKey? }`	A tool call succeeds, fails, completes, or is denied.
`Stop`	`{ commandKey, runStatus, status?, sessionId? }`	An agent, chat, or bot run reaches a terminal status. Blocking when an agent finishes normally.
`SubagentStop`	`{ commandKey, runStatus, status?, sessionId? }`	A subagent is about to finish. Blocking. Subagents do not fire `Stop`.

Legacy Enconvo names such as run_status_changed and agent_tool_step_changed still work, so existing hook files don’t need to be migrated right away.

Recipes

macOS notification when an agent fails

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "STATUS=$(cat | jq -r '.params.runStatus // .params.status') && [ \"$STATUS\" = \"failed\" ] && osascript -e 'display notification \"An agent failed\" with title \"EnConvo\"'"
          }
        ]
      }
    ]
  }
}

Log agent status changes

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: (.timestamp / 1000 | strftime(\"%Y-%m-%d %H:%M:%S\")), agent: .params.commandKey, status: (.params.runStatus // .params.status)}' >> ~/.enconvo/agent-status.log"
          }
        ]
      }
    ]
  }
}

Log agent tool calls

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.params | \"\\(.status) \\(.toolName) \\(.toolCallId)\"' >> ~/.enconvo/agent-tools.log"
          }
        ]
      }
    ]
  }
}

Send to Slack

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
          }
        ]
      }
    ]
  }
}

Custom script

Create a script that reads the event payload from stdin:

#!/bin/bash
# ~/.enconvo/hooks/on-status-change.sh
INPUT=$(cat)
STATUS=$(echo "$INPUT" | jq -r '.params.runStatus // .params.status')
AGENT=$(echo "$INPUT" | jq -r '.params.commandKey')

echo "[$(date)] $AGENT -> $STATUS" >> /tmp/enconvo-hooks.log

if [ "$STATUS" = "failed" ]; then
  osascript -e "display notification \"$AGENT failed\" with title \"EnConvo\""
fi

Reference it from ~/.enconvo/hooks.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.enconvo/hooks/on-status-change.sh"
          }
        ]
      }
    ]
  }
}

Make the script executable:

chmod +x ~/.enconvo/hooks/on-status-change.sh

Troubleshooting

Problem	What to do
A hook didn’t run	Check that `~/.enconvo/hooks.json` is valid JSON, that the top-level key matches the event name, and that the command works when you run it yourself. If you still have `~/.config/enconvo/hooks.json`, it’s ignored while the new file exists.
You’re not sure whether hooks block Enconvo	Only `PreToolUse`, `Stop`, and `SubagentStop` block, during agent runs. Every other hook is fire-and-forget. If any hook fails or times out, Enconvo logs the failure and continues as if the hook weren’t there.
A command can’t find a script or binary	Use absolute paths. Shell `~` expansion works when the command runs through a shell, but absolute paths are easier to debug.

Test a script by hand

Pipe a sample payload into the script:

echo '{"event":"Stop","params":{"commandKey":"agent|main","runStatus":"failed"},"timestamp":1742313600000}' | bash ~/.enconvo/hooks/on-status-change.sh

Agents

Learn about Enconvo agents and custom bots

Extension API Reference

Build extensions that emit or listen to events

Get started

Ask AI anywhere

Voice

Recordings and transcripts

Context, knowledge, and the web

Write and create

Files and utilities

Agents and AI Commands

Workflows and automations

Plugins and integrations

iPhone

Settings and account

Reference

Quick start

Config file

Manage hooks in Settings

How hooks work

Configuration reference

Command hook

HTTP hook

Blocking hooks

Block a dangerous command

Make the agent run tests before finishing

Event payload

Available events

Recipes

macOS notification when an agent fails

Log agent status changes

Log agent tool calls

Send to Slack

Custom script

Troubleshooting

Test a script by hand

Agents

Extension API Reference

​Quick start

​Config file

​Manage hooks in Settings

​How hooks work

​Configuration reference

​Command hook

​HTTP hook

​Blocking hooks

​Block a dangerous command

​Make the agent run tests before finishing

​Event payload

​Available events

​Recipes

​macOS notification when an agent fails

​Log agent status changes

​Log agent tool calls

​Send to Slack

​Custom script

​Troubleshooting

​Test a script by hand

​Related

Agents

Extension API Reference

Quick start

Config file

Manage hooks in Settings

How hooks work

Configuration reference

Command hook

HTTP hook

Blocking hooks

Block a dangerous command

Make the agent run tests before finishing

Event payload

Available events

Recipes

macOS notification when an agent fails

Log agent status changes

Log agent tool calls

Send to Slack

Custom script

Troubleshooting

Test a script by hand

Related