docs(examples): add force_tool_first_turn hook example

[gold-silver-copper]

Summary

Adds a runnable example, examples/force_tool_first_turn, that demonstrates a real per-turn RequestPatch footgun in the hook system and its fix.

The pattern

A hook can force the model to call a tool by returning Flow::patch_request(RequestPatch::new().tool_choice(ToolChoice::Required)) on StepEvent::CompletionCall. But RequestPatch is per-turn and non-sticky — CompletionCall re-fires on every turn — so applying Required unconditionally forces a tool call on every turn. The model never reaches a turn where it can stop calling tools and write the final answer, so the run loops until max_turns and fails with PromptError::MaxTurnsError.

The fix is to gate the patch on the turn index:

if matches!(event, StepEvent::CompletionCall { .. }) && ctx.turn() == 1 {
    return Flow::patch_request(RequestPatch::new().tool_choice(ToolChoice::Required));
}
Flow::cont()

The example runs the footgun first (and catches the resulting MaxTurnsError), then runs the fix, so the difference is visible end-to-end.

Changes

• examples/force_tool_first_turn/{Cargo.toml,src/main.rs} — the example (auto-registered via the examples/* workspace glob).
• examples/README.md — one table row for the new example.
• Cargo.lock — the new package entry.

No production code changes.

Validation

• cargo check -p force_tool_first_turn — clean.
• cargo clippy -p force_tool_first_turn — clean.
• cargo fmt -p force_tool_first_turn — clean.

Requires OPENAI_API_KEY to run (an example, not a test).