Hooks

Overview

Hooks let you run a shell command or send an HTTP request when something happens inside EnConvo, such as an agent starting, completing, failing, or using a tool. They are configured with 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 do not 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.

Config File

Create your hooks config at:

~/.enconvo/hooks.json

EnConvo also reads the legacy file at ~/.config/enconvo/hooks.json when the new file does not exist. If both files exist, ~/.enconvo/hooks.json wins. The file is checked again whenever an event fires, so you can edit hooks while EnConvo is running. No restart is required.

Manage Hooks in Settings

Open Settings → Hooks to inspect hooks from ~/.enconvo/hooks.json. The settings panel groups entries by event, lets you toggle an entry on or off, and can open the JSON file for editing. Toggling writes enabled: false or enabled: true on that hook entry without changing the command or webhook definition.

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.

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 old flat JSON shape are still readable 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 were not 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 only applies 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.

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 do not need to be migrated immediately.

Recipes

macOS Notification on Agent Failure

{
  "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

My hook did not run

Confirm that ~/.enconvo/hooks.json is valid JSON, the top-level key matches the event name, and the command works when run manually. If you still have ~/.config/enconvo/hooks.json, remember that it is ignored when the new file exists.

How do I test a script manually?

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

Do hooks block EnConvo?

Only PreToolUse, Stop, and SubagentStop during agent runs, which the agent waits for. Every other hook is fire-and-forget. If any hook fails or times out, EnConvo logs the failure and continues as if the hook were not there.

Should commands use absolute paths?

Prefer absolute paths for scripts and binaries. Shell ~ expansion works when the command is executed through a shell, but absolute paths are easier to debug.

Agents

Learn about EnConvo agents and custom bots

Extension API Reference

Build extensions that emit or listen to events

Get started

Everyday workspace

Voice and recordings

Context and knowledge

Write and create

Agents and automation

Connect tools and apps

Settings and account

Release history

Overview

Config File

Manage Hooks in Settings

Quick Start

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 on Agent Failure

Log Agent Status Changes

Log Agent Tool Calls

Send to Slack

Custom Script

Troubleshooting

Agents

Extension API Reference

​Overview

​Config File

​Manage Hooks in Settings

​Quick Start

​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 on Agent Failure

​Log Agent Status Changes

​Log Agent Tool Calls

​Send to Slack

​Custom Script

​Troubleshooting

Agents

Extension API Reference

Overview

Config File

Manage Hooks in Settings

Quick Start

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 on Agent Failure

Log Agent Status Changes

Log Agent Tool Calls

Send to Slack

Custom Script

Troubleshooting