PaPoo
cover

Claude Agent SDKで「止める場所」を考える

最初に思ったのは、これはかなり地味だけど、実際にはいちばん事故る種類の話だな、ということだった。AI agent の hook って聞くと、つい「どこで処理を差し込むか」くらいに見えてしまうけれど、この記事はその先にある「そのチェックは本当に止血になっているのか」を見ている。ここを曖昧にすると、見た目は通っていても、裏で side effect が起きる。そこが怖い。

とくに腑に落ちたのは、PreToolUse と PostToolUse の役割の分け方が、単なる設計の好みではなく、かなり露骨に安全性の境目になっている点だ。前者は tool 実行前なので deny できる。後者は実行後なので、できるのは結果の加工や記録までで、起きたこと自体は巻き戻せない。言われてみれば当たり前なのに、実装していると「後で見ればいいか」と思ってしまいがちで、そこが危ない。AI agent まわりは、便利さが先に立つぶん、この手の当たり前を雑にしやすい。

もう一つ、少し引っかかったのは、ask を返せばそのまま承認画面になるわけではない、という点だった。ここは地味に誤解しやすい。hook が判断材料を返し、実際の承認 UI や処理は別の層が担う。つまり「ask したから安心」ではなく、設計全体で承認の流れを作らないといけない。SDK の名前だけ見ていると、つい全部やってくれそうに感じるけれど、この記事はその期待をきれいに外してくる。

それと、async hook は gate にならない、という注意も印象に残った。非同期処理って便利なので、ついそこで外部確認をして止めたくなる。でもこの記事の文脈では、「止める判断は実行前に返ってこなければならない」。ここは速度より安全を取る話で、かなり現実的だと思う。さらに、hook は最終責任者ではなく、tool service 側でも authorization と business validation を繰り返し、idempotency key まで使うべきだ、と釘を刺しているのもいい。こういう二重化は面倒だけれど、実運用では結局それが必要になる。

読後に残ったのは、AI agent の設計って、モデルの賢さよりも「どこで人間の仕事を止めるか」の方がずっと大事だ、という感覚だった。便利な機能の説明に見せかけて、実はかなり保守的な設計原則を押し出している記事で、その慎重さには納得した。


参考: PreToolUse or PostToolUse? Where to Put a Check in the Claude Agent SDK

同じ著者の記事