autoresearch-hooks

autoresearch-hooks

autoresearch セッションの反復境界で実行されるオプションのスクリプトです。2 つのフックがあり、どちらもループを実行するエージェントからは見えません。効果はディスク上のファイル、またはステアメッセージとして現れます。

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

どちらのファイルも任意です。実行ビットが設定されていないファイルは、通知なしで無視されます。

---

コントラクト

標準入力 — before.sh

JSON を 1 行で受け取ります。jq で解析します。実際的な例：

{
  "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"
  }
}

フィールド	説明
last_run	直近の実行エントリーです。新しいセッションでは null です。
session.direction	"lower" または "higher"。尺度のどちら側を優先するかを示します。
session.baseline_metric	現在のセグメントの最初の実行です。実行が 1 回もない間は null です。
session.best_metric	保持された実行のみを対象とした最適なメトリックです。保持された実行がない間は null です。
session.goal	init_experiment で設定されたセッション名です。
session.run_count	これまでに記録された実行の合計数です（ステータスを問いません）。

標準入力 — after.sh

{
  "event": "after",
  "cwd": "/path/to/workdir",
  "run_entry": {
    "run": 6,
    "status": "discard",
    "metric": 38.9,
    "description": "Timsort hybrid slower on random",
    "asi": {
      "hypothesis": "Partial-sort heuristic on input distribution",
      "learned": "Overhead dominates on random arrays"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 6,
    "goal": "optimize sort speed"
  }
}

フィールド	説明
run_entry	直前に記録された実行です。常に存在します。
session	before.sh と同じ形式で、実行後の状態を反映します。

出力

• 標準出力（最大 8 KB）— 次のターンにステアメッセージとしてエージェントに渡されます。空の場合は何も通知されません。
• 標準エラー出力 + ゼロ以外の終了コード — エラーステアとして通知されます。
• タイムアウト — 30 秒で強制終了され、可観測性エントリーに記録されます。

保持

.auto/** は自動取り消し後も保持されます。.auto/ フォルダー全体が保存されます。（進行中のセッションのため、従来の autoresearch.* パスも引き続き保持されます。）

---

例

実行可能なリファレンススクリプトは、このスキルの examples/ ディレクトリにあります。パターンごとに 1 ファイルです。パスはスキルディレクトリ（SKILL.md の親ディレクトリ）を基準に解決されます。参考にご覧ください。これらはポリシーではありません。

• examples/before/ — 外部検索、qmd ドキュメント検索、過剰な変更の防止、アイデアのローテーション、仮説の振り返り、コンテキストのローテーション
• examples/after/ — 学びの記録、新しい最良結果が出たときの macOS 通知、勝利したコミットへの自動タグ付け

各例は、名前付き定数、短いヘルパー関数、ガード節、意図が伝わる名前を備えた、完全に自己完結したスクリプトです。目的はヘッダーコメントを読んで確認し、.auto/hooks/<stage>.sh にコピーして調整してください。

---

フックを追加する手順

1. セッションを把握します。 .auto/prompt.md を読んで目的とメトリックを確認し、.auto/measure.sh に目を通してワークロードを把握します。フックはループを補完するものであり、重複するものではありません。

2. ユーザーの意図を明確にします。 どの境界で何を実行するべきでしょうか？ 事前の調査／事後の記録／成功時の通知／過剰な変更への介入などを検討します。

3. examples/ にある意図に最も近い例から始めます（スキルディレクトリを基準に解決します）。適切な例がなければ、同じスタイル（名前付き定数、短い関数、ガード節、jq で解析する JSON 標準入力）に従って一から作成します。過去を振り返る処理と将来に備える処理を組み合わせる場合は、片方に詰め込まず、before.sh と after.sh の両方を使います。

4. コピーして調整し、実行可能にします。

   mkdir -p .auto/hooks
   cp "<skill-dir>/examples/before/external-search.sh" .auto/hooks/before.sh
   # ... adapt the script ...
   chmod +x .auto/hooks/before.sh
   

5. ループで使う前に、パイプでモック入力を渡して動作確認します。

   jq -n '
     {
       event: "before",
       cwd: ".",
       next_run: 1,
       last_run: null,
       session: {
         metric_name: "total_ms",
         metric_unit: "ms",
         direction: "lower",
         baseline_metric: null,
         best_metric: null,
         run_count: 0,
         goal: "test"
       }
     }
   ' | ./.auto/hooks/before.sh
   

   after.sh の場合は、last_run: null を run_entry オブジェクトに置き換えます（スキーマは上記を参照）。

6. 他のセッションファイルと一緒にフックをコミットします。 .auto/ 配下にあるため、取り消し後も保持されます。

---

経験則

• エージェントが自然に書き込むフィールドを読み取ります — asi.hypothesis、asi.next_focus、asi.learned、description。独自に「フック入力」フィールドを作り、エージェントに入力するよう指示してはいけません。これは透明性の原則に反します。

• 何も出力しないのがデフォルトです。 エージェントにとって有用な情報がある場合にのみ、stdout に出力します。stdout が空なら、誘導はありません。

• 早期終了でガードします。 [ -z "$query" ] && exit 0 は、すべてを if で囲むより効率的で明快です。

• スクリプトごとに扱う関心事は1つにします。 調査と学習内容の両方を扱うなら、別々のファイル（before.sh と after.sh）に記述します。まとめてはいけません。

• 環境変数は使いません。 すべて stdin から取得します。jq で cwd（およびその他の値）を取り出します。$AUTORESEARCH_WORK_DIR はありません。