LIFECYCLE HOOKS

VALIDATION, LOGGING, AND APPROVAL HOOKS Three kinds of hooks deserve special attention. Validation hooks check that something is correct before the run goes further. They check the shape and content of tool arguments. For example, a validation hook might ensure that a date argument is really a date, that a file path is inside the allowed folder, or that a number is within a sensible range. They can also check the model's output, such as confirming that a response asked to be in a particular data format really is valid in that format. If validation fails, the hook sends the error back to the model so it can correct itself, which often fixes the problem automatically. Logging hooks record what is happening. They write structured entries about each model call, tool call, decision, and error. Structured means in a consistent machine-readable format, which Chapter 29 will explain. Logging hooks give you the raw material for tracing, dashboards, and debugging. Because they are automatic, the records are complete and consistent, which is impossible to guarantee if you rely on the model to write its own logs. Approval hooks pause the run and ask a human to decide. They are used for actions that are risky or irreversible, such as transferring money, deleting a production database table, sending a message to many customers, or changing security settings. The harness tags tools or actions by risk level. When the agent tries a high-risk action, the approval hook suspends the run, sends the details to a human reviewer, and waits. The reviewer can approve, deny, or modify the request. The run then resumes accordingly. This pattern is often called human-in-the-loop, meaning a person is a required participant in important decisions. Good approval hooks present clear information. They show what the agent wants to do, why, with what exact values, and what the consequences could be, so the reviewer can decide quickly and accurately. They should also have timeouts, so a run does not hang forever waiting, and a safe default, which is usually to deny if no answer arrives. Be careful about approval fatigue. If a reviewer must approve hundreds of trivial requests, they will start clicking yes without reading. Reserve approval for the actions that truly warrant it.