替 agent 設計看得懂的回饋工具

列出 call 後允許的行動：continue、repair input、initialize、reconcile、request authority 或 stop。Database check 要分 schema missing、fixture missing、access denied、service unreachable 與 healthy；單一 boolean 不足以支援這些分支。

Payload 只放 status、code、summary、retryable、evidence IDs 與 next action。完整 log、query plan、trace 和 screenshot 放外部儲存。需要深查時，用 read_evidence 取得批准過的 slice，不把所有 terminal volume 重送進模型。

名稱與 schema 要說清何時使用、不能做什麼、哪個欄位由誰提供。採 closed enum、長度限制、repository-relative path 與 server-derived environment ID。避免 optional bag，讓任意 command、credential 或 destination 藏在看似普通的 helper。

用保留 task set 測 tool selection，記錯工具、缺 argument、虛構欄位、重複 call 與 recovery。只有 trace 顯示固定誤解才調整名稱或 description；catalog 變更也要跑 regression。

工具回傳的 nextAction 是政策允許的集合，不是命令模型一定照做。RETRYABLE 也要帶 retryAfter、最大次數、已用次數與相同 idempotency boundary；DENIED 指向 request_authority 或 stop，不能建議修改 policy file；UNKNOWN 指向 reconcile，不能回 repair 再重送。將這些分支寫成 controller 測試，避免 description 改得再清楚，executor 卻仍把所有非零結果丟回通用 retry。

Result projection 要從下一個決策反推。若 agent 只需要知道 migration 缺少、目前 schema version 與修復命令，就不回完整 database URL、table contents 或 stack trace。Operator evidence 可以包含 redacted phase log、query code 與 runtime versions，但要有 access audit。這種雙層介面既保護 context budget，也避免為了安全而把診斷資訊刪光，最後只能請 agent猜。

Read_evidence 本身也要有窄 scope。Arguments 使用 evidence ID、approved slice type 與 byte ceiling，不接受 arbitrary path 或全文 query。Runtime 驗 caller、task、environment、retention 與資料類別，回傳內容仍視為 untrusted observation，不能提升成 repository instruction。Fixture 應包含一段看似要求關閉 guardrail 的 poisoned log，證明它只停留在 data channel。

Tool catalog 變更要做 diff。新增能力、放寬 schema、提高 output ceiling、改 retry semantics 或 authority source，都可能擴大 agent 行動面。Release receipt 列 old／new schema hash、affected retained cases、selection accuracy、payload tail 與 denied behavior。若只是重新命名，也要確認舊 session 或 generated instructions 沒有留下 stale reference，否則 agent 會持續呼叫不存在工具。

每個錯誤碼要有穩定語意與責任歸屬。輸入不合法由呼叫者修正；環境未就緒回 initializer；權限不足交給 authority owner；暫時性讀取失敗才允許有限重試；寫入結果不明交給 effect reconciliation；產品驗收失敗指向相關測試與檔案範圍。若所有錯誤都回同一段『請稍後再試』，agent 會把架構、權限與資料問題全部當網路波動，造成重複呼叫與錯誤修復。

工具測試應從執行器外側注入惡意與異常輸入。包含跳脫相對路徑、超長字串、未知欄位、偽造環境識別、相似工具名稱、被污染的錯誤訊息、截斷輸出與取消訊號。確認驗證失敗發生在任何檔案、網路或資料操作之前，並且紀錄中不會把被拒內容原樣寫出。這些案例通過只證明目前契約能擋已知手法，工具範圍改變時仍要重新做威脅檢視。

Fresh-session 評估要比較實際決策品質，而不是只看是否呼叫成功。記錄工具選擇是否正確、參數是否一次通過、是否重複查同一證據、收到拒絕後有沒有改走越權路徑、遇 unknown 是否先對帳、最後完成主張是否綁到完整檢查。若窄工具讓呼叫次數略增，卻能消除假完成與危險重試，仍可能是合理取捨；報告要同時呈現成本與控制結果。

工具維護要指定 owner 與相容政策。當執行器改版，舊 schema 的呼叫是明確拒絕、短期轉接或雙版本支援，要在發佈前決定，不能把解析失敗交給 agent 猜。轉接層只處理形狀差異，不可悄悄放寬權限、補入缺少參數或改變重試語意。每次版本切換保留舊版 failure fixtures，確認 stale session 收到可理解的升級訊息，也不會因 fallback 路徑取得更多能力。Operator dashboard 需顯示各版本呼叫量、錯誤碼與淘汰期限，等 consumer 清零後才移除舊介面。