Customize

Hooks

Scripts that allow, block or rewrite tool calls and prompts.

A hook is a command Faelith runs at a fixed point of every turn. It can block a tool, rewrite its input, block a prompt, or add context the model sees.

Events#

Event	When
`UserPromptSubmit`	Before your prompt is sent
`PreToolUse`	Right before a tool runs (Bash, file writes, `mcp__`, `plugin__` …)
`PostToolUse`	After a tool returns
`Stop`	When the main turn ends

Configure#

.faelith/hooks.json in a project, or the hooks key in ~/.faelith/settings.json:

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python .faelith/hooks/deny-rm.py", "timeout": 10 }]
      }
    ]
  }
}

matcher is a tool name, a prefix like File*, or * for all. The hook receives the event as JSON on stdin and runs in the session's working directory. The default timeout is 30 seconds; a timeout blocks the call.

Results#

Hook outcome	Effect
Exit code `2`	Blocks; stderr is shown as the reason
Exit `0` with JSON	`allow`, `reason`, `replacement_input` (new tool input), `context_addition`
Exit `0` with plain text	The text is added as context
Any other exit code	Does not block; the model sees a warning

A rewritten input goes through the permission checks again, so hooks cannot bypass them. Project hooks run only after you trust the workspace; user hooks always run. /hooks shows what is loaded.

Found a mistake or a gap? Tell us and we will fix the page.