autoresearch-hooks

Optional scripts that run at iteration boundaries in an autoresearch session. Two hooks, both transparent to the loop-running agent, their effect is a file on disk or a steer message.

.auto/hooks/
  before.sh    # fires before each iteration (prospective)
  after.sh     # fires after each log_experiment (retrospective)

Both files are optional. Files without the executable bit are silently ignored.

---

Contract

Stdin, before.sh

One JSON line. Parse with jq. Realistic example:

{
  "event": "before",
  "cwd": "/path/to/workdir",
  "next_run": 6,
  "last_run": {
    "run": 5,
    "status": "discard",
    "metric": 42.1,
    "description": "Simplified to sorted(arr), copy cost dominates",
    "asi": {
      "hypothesis": "Built-in sort avoids Python overhead",
      "next_focus": "list copy avoidance"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 5,
    "goal": "optimize sort speed"
  }
}

Field	Notes
last_run	The most recent run entry. null on a fresh session.
session.direction	"lower" or "higher", which end of the scale wins.
session.baseline_metric	First run of the current segment. null until one run exists.
session.best_metric	Optimal metric across kept runs only. null until one is kept.
session.goal	The session name set by init_experiment.
session.run_count	Total runs logged so far (any status).

Stdin, after.sh