hook-creator

Hooks

Hooks are short-lived commands that receive one runtime event as JSON on stdin and may write one JSON object to stdout to replace it. They live in skills as hooks.json files and are discovered at startup and when reload_hooks is called.

Use hooks for small runtime adapters:

• pre/post tool-call policy
• prompt augmentation before the model is invoked
• send_message shaping or audit
• metrics and local logging
• startup/shutdown setup and teardown

Do not use hooks for long-running services. Use UI plugins, pollers, supervisor jobs, or OS services for that.

hooks.json

{
  "hooks": [
    {
      "name": "message-policy",
      "command": "uv run python hook.py",
      "events": ["pre_tool_call", "post_tool_call", "pre_prompt"],
      "env": {},
      "timeout_seconds": 10,
      "include_conversation": false
    }
  ]
}

Valid events:

• pre_tool_call
• post_tool_call
• pre_prompt
• pre_startup
• post_startup
• pre_shutdown
• post_shutdown

There are no tool-name filters in hooks.json. Filter explicitly in the hook script:

import json
import sys

event = json.loads(sys.stdin.readline())
if event.get("tool") != "send_message":
    print(json.dumps(event))
    raise SystemExit

event["args"]["text"] = event["args"]["text"].strip()
print(json.dumps(event))

Contract

The hook process runs from the directory containing hooks.json.

Environment:

• STATE_DIR: the skill directory
• HOOK_NAME: the hook name
• HOOK_EVENT: the event type

Input:

• exactly one JSON object plus a newline on stdin

Output:

• stdout empty means no-op
• stdout containing a JSON object replaces the event for the next hook
• stderr is logged as hook_stderr

For pre_tool_call, returning an event with an args object changes the tool args before execution. For post_tool_call, returning an event with result changes the result shown to the agent after a successful tool call. For pre_prompt, returning prompt replaces the prompt, and returning append_prompt appends text to the prompt.