CLAUDE CODE AGENTS: ADVANCED ORCHESTRATION - Chapter 2, Exercise 2
Tool Runner vs. Manual Loop: A Worked Trade-Off
====================================================================================

QUESTION:
Explain the trade-off between using the Tool Runner and writing a manual
tool-use loop, and give an example of when the manual loop's extra control
would genuinely be worth its extra code.

SOLUTION / EXPLANATION:

The Tool Runner automates the entire repeat-until-done cycle - sending a
message, letting the model request a tool call, executing that tool,
sending the result back, and repeating until a final answer with no further
tool calls is produced. This is genuinely convenient: you register the
available tools and hand off the conversation, without writing the loop
logic yourself. The trade-off is that this convenience comes at the cost of
visibility and control over what happens between each individual step,
since the Tool Runner manages that internally on your behalf.

A manual tool-use loop trades that convenience away deliberately, in
exchange for full control at every single step of the cycle. A concrete
example where this control is genuinely worth the extra code: an agent
running in a context where every tool call needs to be logged to an audit
system BEFORE it's actually executed - for instance, a compliance
requirement that every file-editing action taken by an agent must be
recorded with a timestamp and the exact parameters used, independently of
whether that action later succeeds or fails. The Tool Runner's automatic
loop doesn't give you a clean point to inject that logging call before each
tool actually runs; a manual loop, where you write each step of the cycle
yourself, gives you an explicit place to add that audit-logging call
immediately before invoking the tool, with full certainty about exactly
when in the sequence it happens.

In this case, the extra code the manual loop requires is genuinely worth
it, because the audit requirement is a hard constraint the Tool Runner's
automated convenience can't satisfy on its own.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It states the trade-off precisely (convenience vs. step-by-step visibility
and control), and grounds the "when it's worth it" half of the question in
a specific, realistic requirement (mandatory pre-execution audit logging)
that the Tool Runner's automated loop cannot satisfy, rather than a vague
"sometimes you need more control."