feat(lifecycle): add on_turn_start / on_turn_end hooks with TurnControl

[adityasingh2400]

Summary

Adds turn-level lifecycle hooks to RunHooksBase and AgentHooksBase, addressing #2671.

What's new

• on_turn_start(context, agent, turn_number) — fires before the LLM is called for each turn
• on_turn_end(context, agent, turn_number) — fires after all tool calls for a turn complete
• TurnControl return type for on_turn_start: returning "stop" halts the run gracefully (raises MaxTurnsExceeded) before the model is called; returning None or "continue" proceeds normally

Addressing reviewer feedback

Hooks can raise an exception if something wrong but they do not affect the agent loop orchestration in a more granular way many developers wish.
— @seratch

on_turn_start now returns TurnControl ("stop" | "continue" | None), giving callers direct control over the loop — not just observation. This allows patterns like:

class BudgetHooks(RunHooks):
    def __init__(self, max_turns: int):
        self.max_turns = max_turns

    async def on_turn_start(self, context, agent, turn_number) -> TurnControl:
        if turn_number > self.max_turns:
            return "stop"  # halts before the LLM call
        return None

    async def on_turn_end(self, context, agent, turn_number):
        print(f"Turn {turn_number} complete. Tokens used: {context.usage.total_tokens}")

When "stop" is returned, MaxTurnsExceeded is raised — consistent with the existing max_turns limit, so callers handle it the same way.

Files changed

File	Change
src/agents/lifecycle.py	on_turn_start return type → Union[TurnControl, None]; docstrings updated
src/agents/run.py	Non-streaming loop checks return value; raises MaxTurnsExceeded on "stop"
src/agents/run_internal/run_loop.py	Streaming loop checks return value; enqueues QueueCompleteSentinel on "stop"
src/agents/__init__.py	Exports TurnControl, RunHooksBase, AgentHooksBase
tests/test_turn_lifecycle_hooks.py	10 tests (6 existing + 4 new TurnControl cases)

Closes #2671

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 05a4f15d77

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Defer turn-end hook until interrupted turn actually completes

In the sync runner, on_turn_end is fired immediately after run_single_turn returns, even when next_step is NextStepInterruption (tool approval pending). In that path the turn has not actually finished—resolve_interrupted_turn continues the same turn later—so this reports a false turn completion and the hook is never re-fired at the real end. Any hook that compacts state, records per-turn metrics, or enforces turn-level cancellation will run too early for approval-based workflows.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid emitting turn-end for paused streaming turns

The streaming loop has the same premature on_turn_end call before branching on turn_result.next_step. If the turn pauses with NextStepInterruption, the hook still fires even though approvals and remaining tool execution happen only after resume, so observers get an incorrect "turn complete" signal and never receive a true completion callback for that turn.

Useful? React with 👍 / 👎.

[seratch]

Adding more hooks may be worth considering, but I don't think this could be a solution for the mentioned issue. Hooks can raise an exception if something wrong but they do not affect the agent loop orchestration in a more granular way many developers wish.

[adityasingh2400]

Thanks for the feedback @seratch! You're right — pure observation hooks don't solve the orchestration-control use case.

I've updated this PR so that on_turn_start now returns a TurnControl value ("stop" | "continue" | None). Returning "stop" halts the run before the LLM is called for that turn, raising MaxTurnsExceeded (consistent with the existing max_turns behaviour). Returning None or "continue" proceeds as before.

This gives callers actual control over the loop — e.g. a custom turn budget, an external kill-switch, or circuit-breaking based on context.usage. All 10 tests pass including 4 new TurnControl cases.

[seratch]

Thanks for the update. However, this is still not the direction we'd like to pursue, so let us close this now. Also, all the PRs you're sending to this repo have conflicts with the latest main branch. If you're interested in sending further PRs to this project, please make sure those do not have conflicts.