Agent Hooks

Shell hooks let a user run their own script at fixed points in the agent's lifecycle — to block a dangerous action, rewrite an input or an outbound message, inject context into the model, or warn the user. The script can be written in any language; it talks to the agent over a simple JSON-on-stdin, JSON-on-stdout protocol.

Tools: read_file, write_file, bash

When to use

Reach for hooks when the user wants the agent to automatically enforce a rule or react to an event without being asked each time. Examples:

• "Stop me from running rm -rf / destructive bash" → pre_tool_call block
• "Never let a private key get pushed to Telegram" → on_outbound_message block
• "Log every tool call for audit" → post_tool_call observe
• "Remind the agent of X at the start of every model call" → pre_llm_call context
• "Don't let the agent claim it published when it didn't" → on_completion_claim (in /goal) or on_stop (in normal chat)
• "If the answer fails my quality check, make the agent redo it" → on_stop block

If the user just wants a one-off check, that's not a hook — hooks are for recurring, automatic lifecycle enforcement.

How configuration works (the agent does it end-to-end)

The agent installs and activates a hook with zero user copy-paste. Write the script, write the config entry, then call the loopback self-approve API — it flips the master switch on, approves the script for every event it's wired to, and hot-mounts it live (no restart). The user just tests it afterward.

curl -s -X POST http://localhost:8000/internal/runtime/hooks/approve \
  -H 'Content-Type: application/json' \
  -d '{"command": "/data/workspace/hooks/security_guard.py"}'
# -> {"ok": true, "events": [...], "mounted": N, "master_enabled": true}

⚠️ ALWAYS use an absolute path under /data/workspace in both the yaml command: and this call. Never a relative path like skills/agent-hooks/templates/security_guard.py: the bridge spawns the script with the server cwd (/app), so a relative path resolves to /app/skills/… — an empty dir — and every spawn fails. Because the bridge fails OPEN (a script it can't run = "continue"), the guard then silently protects nothing while /hooks list still shows it "mounted". To avoid this, the standard install copies the template into /data/workspace/hooks/ and points the yaml there (see the workflow below). /app/skills is NOT the skills dir — the real one is /data/workspace/skills/ (a.k.a. /app/workspace/skills/ via symlink).

• command MUST be the exact command: string from the shell_hooks.yaml entry (the absolute script path). The hook MUST already be declared in the yaml — approval flips a declared hook to live, it can't conjure one out of thin air.
• The endpoint is loopback-only (same-uid-in-container trust boundary, same as .env reads). It auto-enables the master switch (enable_master defaults true), so the hook fires immediately.
• Approval records the script's mtime, so a later edit surfaces as drift in /hooks list / /hooks doctor — a swap-the-script change stays visible.

This is the whole activation story for the user — there isn't a second step. After the call returns {"ok": true}, tell them it's live and to test it. Do not mention /hooks approve, /hooks on, or "two gates" — those are internal.

Fallback (older builds only): if the curl returns 404, this runtime predates the self-approve API — only then fall back to asking the user to paste /hooks approve <command> then /hooks on.

The two gates (both handled by the self-approve API — you don't surface them)

Internally a hook fires only when BOTH hold; the self-approve call above flips both in one shot, so the user never sees or types either:

1. Master switch ON — shell_hooks.enabled: true in workspace/config/agent.yaml. The API auto-enables it (enable_master defaults true).
2. Per-hook approval — the (event, command) pair is recorded in the allowlist with the script's mtime (so a later edit shows as "changed since approval" drift — a swapped script stays visible). The API approves every event the command is wired to.

These exist as a security boundary, not as a user step. Do NOT mention "approve" or "two gates" when explaining hooks to a user — just say you'll set it up and they can test it. (Manual /hooks on + /hooks approve exist only as the 404 fallback for older runtimes.)

The /hooks command

Plain text on web / Telegram / WeChat (no LLM, no cost):

Events (12) and what each can do

Every payload also includes event, session_id, agent_id, cwd.

The event field is the dispatch key. It names which lifecycle moment is firing (pre_tool_call, on_user_message, …). A multi-event script (like security_guard.py, one file wired to five events) reads event to decide which branch to run — no event in the payload means no branch matches, so the script falls through to "continue" (empty output = allow). The runtime always sets it; you only have to remember it when hand-crafting a test payload (see the dry-run step below). It is NOT something you put in shell_hooks.yaml — there the event: key tells the bus when to call you; the event field in the payload is the bus telling the script which moment it is.

The three "make the agent fix it" levers (don't mix them up)

These three fire near the end of a turn but have very different power — pick by what you need to happen when something's wrong:

Rule of thumb: mask → on_response_end; redo in chat → on_stop; redo in a goal → on_completion_claim. Note on_response_end can only rewrite the stored copy — tokens already streamed to a live web client can't be unsent, so prefer on_stop when you need the user to actually see a corrected answer.

Output protocol (what the script prints on stdout)

JSON object, or empty for "continue". Fields:

{"decision": "block", "reason": "..."}   // deny the action / refuse completion
{"tool_input": {...}}                     // pre_tool_call: rewrite EXISTING input keys
{"notification": "..."}                   // on_outbound_message: rewrite the message
{"context": "..."}                        // pre_llm_call: inject into prompt (AGENT-facing)
{"systemMessage": "..."}                  // allow, but show the USER a note
{"add_warning": "..."}                    //   same user-facing note channel
<empty>                                   // continue, no change

context is agent-facing (goes into the prompt, pre_llm_call only). systemMessage / add_warning is user-facing (shown to the human on the tool-result / completion / outbound surfaces) — never injected into the prompt.

Safety: scripts run with shell=False + argv split (no shell injection) and a per-hook timeout. A script that errors, times out, or prints non-JSON falls through to continue — a broken hook can never break the agent.

Writing a readable reason

The reason is shown to the user (on the blocked-action card) and to the model. Keep it short and scannable — one clause for why, then the evidence. Don't write paragraphs: a reason fires on a card the user is already annoyed to see, and a wall of text buries the actual cause. Aim for the shape [tag] Blocked (<why>): <evidence> — ~8–12 words before the colon, never two sentences of hand-wringing.

The model still gets enough to act (the why + the offending payload); the user gets a card they can read at a glance. The UI splits one reason string into two parts for you, so you don't parse anything client-side:

• Explanation + command box — put the human sentence first, then : , then the offending command/payload. Everything after the first ": " is rendered in a separate monospace box. The split only triggers when that tail looks like a payload (has a space or is longer than ~12 chars), so an ordinary sentence that happens to contain a colon is left intact.
• Sentence only — a reason with no ": " shows as a single sentence and no command box. That's the right shape when there's nothing to quote (e.g. a pasted seed phrase).
• [tag] is stripped — a leading tag like [security] is removed before display and the sentence is auto-capitalised, so you can keep a tag for your own grep without it leaking into the UI.

// Good — short why + a clean command box:
{"decision": "block",
 "reason": "[security] Blocked (formats the disk): mkfs.ext4 /dev/sda1"}
//  ->  "Blocked (formats the disk)"   +   [ mkfs.ext4 /dev/sda1 ]

// Avoid — a bare command (no WHY) or a verbose two-sentence lecture:
{"decision": "block", "reason": "mkfs /dev/sda1"}
{"decision": "block", "reason": "This command is irreversible and would cause permanent data loss across the entire filesystem, so I have decided to block it for your safety: mkfs /dev/sda1"}

A hook that doesn't follow this still works — a plain string just renders as one sentence. The convention only unlocks the nicer "explanation + command" layout.

Config file format

workspace/config/shell_hooks.yaml:

hooks:
  - event: pre_tool_call
    matcher: "rm -rf|dd if=|mkfs"      # optional regex; script only spawns on a match (perf gate)
    command: ./extensions/shell_hooks/examples/block_secrets.py
    timeout: 10                          # seconds, default 20, max 120

Two hook transports

A hook is either a local command (default) or an HTTP endpoint — same payload in, same decision JSON out, only the transport differs.

hooks:
  - event: pre_tool_call
    type: http                          # omit type -> "command" (default)
    url: https://my-guard.example.com/hook
    timeout: 10

HTTP specifics:

• SSRF guard — the URL must be http(s) and must NOT resolve to a loopback / private / link-local (incl. cloud metadata 169.254.169.254) / reserved address (blocked at parse AND call time). Set STARCHILD_SHELL_HOOKS_HTTP_ALLOW_LOCAL=1 only to intentionally hit a local service.
• Approval keys on the URL: /hooks approve <event> <url>; /hooks list shows it as POST <url> and skips the executable/mtime checks.

Adding an LLM judgement (call the proxy, NOT /chat)

When a hook needs real reasoning ("does this leak a secret?", "is this completion actually done?"), call an LLM directly through the proxy from your script — never the agent's own /chat.

from core.http_client import proxied_post
import json, sys

event = json.load(sys.stdin)
r = proxied_post(
    "https://openrouter.ai/api/v1/chat/completions",
    json={
        "model": "minimax/minimax-m3",   # cheap default (~$0.0002/call)
        "messages": [
            {"role": "system", "content":
                'You are a guard. Output ONLY JSON {"decision":"block|allow","reason":"..."}.'},
            {"role": "user", "content": json.dumps(event)},
        ],
        "temperature": 0, "max_tokens": 200,
    },
    headers={"SC-CALLER-ID": "chat:hook"},   # required for billing
    timeout=40,
)
try:
    print(json.dumps(json.loads(r.json()["choices"][0]["message"]["content"])))
except Exception:
    print("{}")   # fail-open on any parse error

Why proxy-direct: OpenRouter is an external stateless API, so it does not re-enter the agent loop or fire pre_llm_call -> no recursion, one cheap completion instead of a full agent turn, your own prompt + pure-JSON response. Calling /chat from a hook re-emits the same event (the bridge guards against the loop, but it's needless overhead) — and an LLM hook that calls /chat must never sit on pre_llm_call. See the host docs sc-proxy.md section "Calling an LLM through the proxy".

Standard workflow (the agent's checklist)

1. Clarify the rule and pick the event from the table above.
2. Write the script — read JSON on stdin, print a decision on stdout. Exit non-zero / non-JSON = continue. Make it executable (chmod +x).
3. Put the script at a stable ABSOLUTE path under /data/workspace. For a shipped template, copy it out of the skill dir so a skill update can't move it:

   mkdir -p /data/workspace/hooks
   cp /data/workspace/skills/agent-hooks/templates/security_guard.py /data/workspace/hooks/
   chmod +x /data/workspace/hooks/security_guard.py
   ls -l /data/workspace/hooks/security_guard.py    # VERIFY it exists before going on
   

   Never reference the script by a relative path (see the ⚠️ box above — it resolves against /app and silently fails open).
4. Add a config entry in workspace/config/shell_hooks.yaml with the absolute command: (/data/workspace/hooks/security_guard.py); add a matcher regex when possible so the script only spawns when relevant.
5. Dry-run it yourself with bash — pipe a sample JSON payload into the script and confirm it prints valid JSON. The payload MUST include the event field — a multi-event script dispatches on it, so leaving it out makes every case fall through to "continue" and you'll wrongly conclude the guard doesn't fire. Test each event the script handles:

   # should BLOCK (note the "event" key):
   echo '{"event":"pre_tool_call","tool_name":"bash","tool_input":{"command":"rm -rf /"}}' \
     | python3 /data/workspace/hooks/security_guard.py
   # should ALLOW (empty output):
   echo '{"event":"pre_tool_call","tool_name":"bash","tool_input":{"command":"ls -la"}}' \
     | python3 /data/workspace/hooks/security_guard.py
   

6. Activate it yourself via the loopback self-approve API (no user paste); command = the exact absolute path from your yaml entry:

   curl -s -X POST http://localhost:8000/internal/runtime/hooks/approve \
     -H 'Content-Type: application/json' \
     -d '{"command": "/data/workspace/hooks/security_guard.py"}'
   

   On {"ok": true} the hook is live. On 404, fall back to handing the user /hooks approve <command> + /hooks on (see "How configuration works").
7. Run /hooks doctor to confirm it actually works — this is the step that catches a wrong path / non-executable / non-JSON script. A guard that shows "mounted" in /hooks list but errors in doctor is a silent no-op (fails open). Only after doctor is clean tell the user it's live and ready to test.

Ready-made scripts (each has ONE clear job)

Five production-grade guards ship in this skill under templates/ (copy + approve as-is). Four single-purpose examples ship with the host under extensions/shell_hooks/examples/ (copy + adapt). No two overlap — pick by the job, not by trial.

Installing from a /hooks number or name

/hooks (empty state) and /hooks help show a numbered ready-made list. The /hooks command itself is static text — it never installs. When the user replies with a number ("1", "1,3"), a name ("security_guard"), or "install all", THAT reply lands on you: resolve it to the template by the name shown next to the number in that list (number→templates/<name>.py), then run the Standard workflow below for each — copy → yaml entry → dry-run → self-approve → doctor. Map by the visible name, never a memorised number→path table (the list may be reordered). If a self-test exists (templates/<name>_selftest.py), run it first.

Production templates (in this skill, templates/)

⚠️ Copy before you edit — for every template here. Always cp a template into /data/workspace/hooks/ and wire your hook at THAT path, then make any changes (rule tweaks, the runtime_footer CONFIG block, etc.) in the copy. Editing a file in place under skills/agent-hooks/templates/ is pointless: the next skill update overwrites it and your changes vanish. The copy in hooks/ is yours and is never touched by updates.

Single-purpose examples (host repo, extensions/shell_hooks/examples/)

Superseded by the templates (don't ship a second, conflicting guard)

The host repo also ships some minimal single-event examples under extensions/shell_hooks/examples/ that overlap the two templates above. They're fine as learning references, but for real use prefer the template — running both just creates two guards with possibly different policies.

Removed outright (orphan duplicates, fully folded into security_guard.py): secret_guard.py (vendor-key block/mask, incl. Bearer) and dangerous_bash_guard.py (destructive-bash block). Want to also block installers / force-push? Tune the guard's DESTRUCTIVE table rather than running a second bash guard with a conflicting policy.

For any rule none of the above covers, write a fresh script — the minimal block example below is the template, and the output protocol above covers every capability.

Minimal block example (pre_tool_call, any language)

#!/usr/bin/env bash
payload="$(cat)"
python3 - "$payload" <<'PY'
import json, sys, re
ev = json.loads(sys.argv[1])
cmd = (ev.get("tool_input") or {}).get("command", "")
if re.search(r"rm\s+-rf\s+/|dd\s+if=|mkfs", cmd):
    print(json.dumps({"decision": "block", "reason": f"This command is irreversible and would erase data, so I've blocked it: {cmd}"}))
else:
    print("{}")   # continue
PY

All-in-one security guard (templates/security_guard.py)

A ready-to-use, self-contained script that wires one file to five events and covers the common "don't leak secrets / don't nuke the box" baseline. First copy it to a stable absolute path, then wire all five events to that same absolute command: in config/shell_hooks.yaml (one block per event), then activate:

cp /data/workspace/skills/agent-hooks/templates/security_guard.py /data/workspace/hooks/
chmod +x /data/workspace/hooks/security_guard.py
curl -s -X POST http://localhost:8000/internal/runtime/hooks/approve \
  -H 'Content-Type: application/json' \
  -d '{"command": "/data/workspace/hooks/security_guard.py"}'

This approves every event that command is wired to and mounts it live — no user paste. (On 404, fall back to /hooks approve <command> + /hooks on.)

Design policy: block only what is both very dangerous and not part of normal work. Common dev actions like curl | bash (installers) and git push --force (rebasing your own feature branch) are intentionally allowed — over-blocking trains users to disable the guard.

Tune the SECRET_PATTERNS, DESTRUCTIVE, and MSG_TOOLS tables at the top of the file for your own rules. templates/security_guard_selftest.py is the self-test (run it after any edit; dangerous strings live there as data only, so the host bash guard can't trip on them).

Anti-hallucination guard (templates/verify_publish_claims.py)

Catches a fabricated success: the agent writes "Published! community.iamstarchild.com/…", "Posted to AgentX /post/…", or "Reminder scheduled" when it never ran the tool. The script checks the reply against ground truth — the previews registry (/data/previews.json), the AgentX post ledger, and the scheduler registry — and either rewrites the reply or forces a redo. It is deliberately low-false-positive: a real published URL or an "offer to publish" (future tense) passes untouched; only a past-tense success claim with no backing trips it.

cp /data/workspace/skills/agent-hooks/templates/verify_publish_claims.py /data/workspace/hooks/
chmod +x /data/workspace/hooks/verify_publish_claims.py
curl -s -X POST http://localhost:8000/internal/runtime/hooks/approve \
  -H 'Content-Type: application/json' \
  -d '{"command": "/data/workspace/hooks/verify_publish_claims.py"}'

Wire it on on_stop for normal chat — that's the only event that makes the agent actually redo a turn instead of just editing the text. The host honors only a decision: block on on_stop / on_completion_claim (a rewrite is ignored on those events), so the hook blocks on both and only rewrites on on_response_end. templates/verify_publish_claims_selftest.py is the self-test (covers the on_stop block path + the loop cap).

Cost/model footer (templates/runtime_footer.py)

A model cannot know its own per-reply cost — and often not even its own model id. That data lives only in the runtime. So if the model types its own footer (e.g. Model: GLM-5.2 | Cost: $0.038), the numbers are invented. And once a real footer is in the chat history, the model's autocomplete starts imitating it — producing a second, fabricated footer. The footer is the runtime's job, not the model's.

runtime_footer.py solves this entirely on one event — on_response_end — which fires once per turn on the final assembled reply: it ① strips any footer the model typed at the reply end, then ② appends the one true footer from the runtime's real model + cost. The strip is the guarantee; nothing per-call is needed.

Why on_response_end alone, not pre_llm_call. There is no event that fires "just before the final response". pre_llm_call fires before every model request (N times/turn when tools are used) and can't know which call is the last — the model decides to use tools dynamically. Wiring the suppression there injects the directive N times/turn (visible as repeated injections in the call trace). It's also redundant: on_response_end already removes the footer post-hoc. So default to on_response_end only. The script does carry a pre_llm_call handler (injects a "don't type a footer" directive) if you want the extra nudge — wire it as a second event — but accept it runs per-call.

The strip is a safety net (FOOTER_STRIP, on by default), deliberately narrow: it only removes a box-drawing ─ … · $N line or a Model: … Cost: $N line, and only on trailing lines — so a "Model:"/"Cost:" sentence in the body, or a shell $VAR, is never touched (an earlier version used an over-broad Model: regex that risked deleting legit prose; this is the tight redo). Set FOOTER_STRIP=0 for pure append-only.

cp /data/workspace/skills/agent-hooks/templates/runtime_footer.py /data/workspace/hooks/
chmod +x /data/workspace/hooks/runtime_footer.py
curl -s -X POST http://localhost:8000/internal/runtime/hooks/approve \
  -H 'Content-Type: application/json' \
  -d '{"command": "/data/workspace/hooks/runtime_footer.py"}'

Wire it in config/shell_hooks.yaml — no matcher, runs every turn:

hooks:
  - event: on_response_end
    command: /data/workspace/hooks/runtime_footer.py
    timeout: 10
  # Optional extra nudge (fires per model-request, N times/turn):
  # - event: pre_llm_call
  #   command: /data/workspace/hooks/runtime_footer.py
  #   timeout: 10

Configure by editing your copy — not env vars. The recommended way to turn options on is the CONFIG block at the top of the script. Edit it in the copy you just made under /data/workspace/hooks/ (NOT in skills/… — that gets overwritten on the next skill update). Hooks run with the server process environment, not your shell, so env vars are awkward to set and invisible in /hooks list; an in-file constant is reliable, visible, and travels with the script:

# ─── CONFIG — edit your copy ───
SHOW_TOKENS = False   # True → append "· N in / N out"
SHOW_CREDIT = False   # True → append "· 💰 $bal"  (1 HTTP call/turn, fail-open)
TEMPLATE    = None    # custom format str: {model} {cost} {input} {output} {credit}
CREDIT_URL  = None    # override credit endpoint for self-hosted setups
STRIP       = True    # strip a model-typed footer at the tail

Each constant also has a matching env override (FOOTER_SHOW_TOKENS, FOOTER_SHOW_CREDIT, FOOTER_TEMPLATE, FOOTER_CREDIT_URL, FOOTER_STRIP, FOOTER_SUPPRESS_TEXT) which wins when set — handy for a one-off without touching the file, but the in-file constant is the durable default.

Default footer is model + cost only (─ z-ai/glm-5.2 · $0.0211). SHOW_TOKENS = True → ─ z-ai/glm-5.2 · $0.0211 · 900 in / 120 out.

Show remaining credit: SHOW_CREDIT = True appends your balance (─ z-ai/glm-5.2 · $0.0211 · 💰 $271.64). Off by default because it adds one internal HTTP call per turn to the credit API — the same endpoint the credit tool reads, authenticated automatically by source IPv6 (no key needed). It's fail-open: a 2s timeout caps the wait, and if the lookup errors or times out the balance is silently omitted (the footer still fires, no dangling separator). Note the model can't see this number unless you wire the hook — it lives only in the runtime, like cost.

Don't double up: runtime_footer is the shell-hook equivalent of the host turn_footer extension — enable one, not both. Same for Telegram's tg_show_usage.

Safety: never blocks. on_response_end appends nothing when the event carries no cost data or the reply is empty (no $0.0000 lie), and only ever strips a narrowly-matched footer at the reply's tail (STRIP = False to disable); the optional pre_llm_call injects nothing on a missing/malformed payload; an unknown event is a no-op. Fail-open on any error. Self-test: templates/runtime_footer_selftest.py (35 cases — both handlers, strip + false-positive guards for mid-body prose and shell $VAR, credit balance + fail-open, in-file CONFIG constants + env-override precedence, dispatch safety).

Claude Code compatibility

Hook scripts written for Claude Code work unchanged — their output is auto-translated into the fields above:

Only the output payload is translated — event NAMES stay ours (pre_tool_call, not PreToolUse). Claude Code's Stop hook maps to our on_stop (block → force a redo); its UserPromptSubmit maps to on_user_message. A Stop script that returns {"decision":"block","reason":…} or exits 2 works unchanged once wired to on_stop.

Troubleshooting "my hook never fires"

1. Is the event one of the 12 above? (a typo is a silent no-op)
2. Is the master switch on? /hooks list shows it. The self-approve API enables it automatically; otherwise /hooks on.
3. Is the hook approved? ✗ NOT approved in /hooks list → re-run the self-approve API for that command (or /hooks approve as fallback).
4. Does the matcher regex actually match? Too narrow = never spawns.
5. Run /hooks doctor — it flags non-executable / tampered / timed-out / non-JSON.
6. Manual test "allows everything"? Your test payload is probably missing the event field — a multi-event script dispatches on it and falls through to "continue" without it. This is a test-harness mistake, not a hook bug; the real runtime always sets event.
7. can't open file '/app/skills/…' / "mounted" but nothing is blocked? The command: is a relative or wrong path. The bridge spawns with the server cwd (/app), so skills/… resolves to the empty /app/skills and every spawn fails — and because the bridge fails OPEN, the guard silently protects nothing. Fix: use the ABSOLUTE path /data/workspace/hooks/<script>.py in both the yaml and the approve call, then re-approve and confirm with /hooks doctor. (/app/skills is not the skills dir; the real one is /data/workspace/skills/.)

Deep reference

Full protocol, security model, and per-event payload detail live in the agent's own docs: config/context/references/agent-hooks.md (read it for edge cases this skill summarizes).