Writing autoresearch hooks
The loop runs before (each benchmark) and after (each log_experiment) hooks from .auto/hooks/. Hooks are plain scripts: use them for anything the agent shouldn't be trusted to do on its own, or that should run deterministically every iteration.
Contract
|
before.sh |
after.sh |
| when |
before each benchmark |
after each log_experiment |
| stdin (one JSON line) |
{event:"before", cwd, next_run, last_run, session} |
{event:"after", cwd, run_entry, session} |
| stdout |
returned to the agent as before_steer (advisory) |
returned as after_steer (advisory) |
| constraints |
exit within 30s (killed otherwise); stdout ≤8KB; fail-open (errors never block the loop, but failures surface as *_steer, e.g. [before hook exited 3] … / [before hook timed out after 30s]) |
same |
session = {metric_name, direction, baseline_metric, best_metric, run_count}.
last_run (before) = previous run or null: {run, status, metric, description, asi}. run_entry (after) = the run just logged: {run, status, metric, description, commit, asi}. asi carries the Actionable Side Information the agent recorded (hypothesis, next_action_hint, rollback, …); mine it, don't require it.
Every fire (success or failure) appends a {type:"hook", stage, exit_code, duration_ms, stdout_bytes, timed_out} entry to .auto/log.jsonl for observability.
Rules of thumb:
- Silence is the default: print nothing unless you have something worth saying.
- One hook, one concern: a reminder hook vs a journal hook are different files.
- No environment variables; everything comes from stdin.
Scenario selection
Ask: does this hook remind (before, produce steer) or do work (after, side effect)?
- remind before a run →
before:
- repeated failures → anti-thrash guard (see
hooks/examples/before/anti-thrash.sh)
- need to try other directions → idea pool (see
idea-rotator.sh)
- force a hypothesis → reflection (see
hypothesis-reflection.sh)
- external lookup before changing code → read docs/web then print a steer
- do work after a run →
after:
- keep a human diary → journal (see
learnings-journal.sh)
- notify on completion → macOS notification (see
macos-notify.sh)
- mark new bests → git tag (see
auto-tag-winners.sh)
- anything the loop should record but the agent shouldn't be trusted to do
Steps
- Read
.auto/prompt.md and .auto/measure.sh to understand the session.
- Pick the closest example from
plugin/hooks/examples/ (or write from scratch).
- Parse stdin with node (available everywhere): read the payload, act, print only what should be a steer.
- Smoke-test with a mock payload before committing:
printf '%s\n' '{"event":"before","cwd":".","next_run":1,"last_run":null,"session":{"run_count":0}}' \
| bash .auto/hooks/before.sh
For an after hook, replace with an {"event":"after","cwd":".","run_entry":{...},"session":{...}} payload.
chmod +x .auto/hooks/before.sh (or after.sh) and commit; the loop picks it up immediately.
Guidelines
- Steer is advisory: the agent may ignore it; keep messages short and actionable.
- Hooks run every iteration: no interactive prompts, no long work (30s cap).
- The hook directory lives in
.auto/, which is exempt from discard rollback, so hook state survives.
- If a hook is broken, the loop continues (fail-open) and the failure comes back as a
*_steer like [before hook exited 3] <stderr>; the stderr tail is included, so fix the hook.
1---2name: autoresearch-hooks3description: "Teach how to write iteration hooks (before/after scripts) for the autoresearch plugin: contract, scenario selection, mock testing, and guidelines. Use when the user wants to add a custom hook, extend the loop with external logic (lookups, notifications, journals, guards), or understand the .auto/hooks mechanism."4metadata:5 source: https://skillmd.com/skills/zai-org/autoresearch-hooks6---78# Writing autoresearch hooks910The loop runs `before` (each benchmark) and `after` (each `log_experiment`) hooks from `.auto/hooks/`. Hooks are plain scripts: use them for anything the agent shouldn't be trusted to do on its own, or that should run deterministically every iteration.1112## Contract1314| | before.sh | after.sh |15| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |16| when | before each benchmark | after each `log_experiment` |17| stdin (one JSON line) | `{event:"before", cwd, next_run, last_run, session}` | `{event:"after", cwd, run_entry, session}` |18| stdout | returned to the agent as `before_steer` (advisory) | returned as `after_steer` (advisory) |19| constraints | exit within 30s (killed otherwise); stdout ≤8KB; **fail-open** (errors never block the loop, but failures surface as `*_steer`, e.g. `[before hook exited 3] …` / `[before hook timed out after 30s]`) | same |2021`session` = `{metric_name, direction, baseline_metric, best_metric, run_count}`.22`last_run` (before) = previous run or `null`: `{run, status, metric, description, asi}`. `run_entry` (after) = the run just logged: `{run, status, metric, description, commit, asi}`. `asi` carries the Actionable Side Information the agent recorded (`hypothesis`, `next_action_hint`, `rollback`, …); mine it, don't require it.2324Every fire (success or failure) appends a `{type:"hook", stage, exit_code, duration_ms, stdout_bytes, timed_out}` entry to `.auto/log.jsonl` for observability.2526Rules of thumb:2728- **Silence is the default**: print nothing unless you have something worth saying.29- **One hook, one concern**: a reminder hook vs a journal hook are different files.30- No environment variables; everything comes from stdin.3132## Scenario selection3334Ask: does this hook **remind** (before, produce steer) or **do work** (after, side effect)?3536- remind before a run → `before`:37 - repeated failures → anti-thrash guard (see `hooks/examples/before/anti-thrash.sh`)38 - need to try other directions → idea pool (see `idea-rotator.sh`)39 - force a hypothesis → reflection (see `hypothesis-reflection.sh`)40 - external lookup before changing code → read docs/web then print a steer41- do work after a run → `after`:42 - keep a human diary → journal (see `learnings-journal.sh`)43 - notify on completion → macOS notification (see `macos-notify.sh`)44 - mark new bests → git tag (see `auto-tag-winners.sh`)45 - anything the loop should record but the agent shouldn't be trusted to do4647## Steps48491. Read `.auto/prompt.md` and `.auto/measure.sh` to understand the session.502. Pick the closest example from `plugin/hooks/examples/` (or write from scratch).513. Parse stdin with node (available everywhere): read the payload, act, print only what should be a steer.524. Smoke-test with a mock payload before committing:53 ```bash54 printf '%s\n' '{"event":"before","cwd":".","next_run":1,"last_run":null,"session":{"run_count":0}}' \55 | bash .auto/hooks/before.sh56 ```57 For an after hook, replace with an `{"event":"after","cwd":".","run_entry":{...},"session":{...}}` payload.585. `chmod +x .auto/hooks/before.sh` (or `after.sh`) and commit; the loop picks it up immediately.5960## Guidelines6162- Steer is **advisory**: the agent may ignore it; keep messages short and actionable.63- Hooks run **every** iteration: no interactive prompts, no long work (30s cap).64- The hook directory lives in `.auto/`, which is exempt from discard rollback, so hook state survives.65- If a hook is broken, the loop continues (fail-open) and the failure comes back as a `*_steer` like `[before hook exited 3] <stderr>`; the stderr tail is included, so fix the hook.