Skip to content

Commit d8e0a76

Browse files
fix: preserve RunState agent ownership across hook state changes (#5362)
* fix: preserve RunState agent ownership across hook state changes * fix: narrow RunState hook identity compatibility failures
1 parent 6fc4ab7 commit d8e0a76

8 files changed

Lines changed: 524 additions & 4 deletions

File tree

‎src/agents/_run_state_agent_identity.py‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,21 @@ def _handoff_identity_signature(handoff_item: Agent[Any] | Handoff[Any, Any]) ->
366366
}
367367

368368

369+
def _hook_identity_signature(hooks: Any) -> Any:
370+
"""Keep the legacy type discriminator, without lifecycle instance state."""
371+
if hooks is None:
372+
return None
373+
# Match the normalization categories used by the legacy capability serializer.
374+
# Keeping their spelling preserves ordering between different hook types.
375+
if callable(hooks):
376+
return {"callable": _callable_identity_name(hooks)}
377+
if dataclasses.is_dataclass(hooks):
378+
return {"dataclass": _identity_type_name(hooks)}
379+
if hasattr(hooks, "model_dump"):
380+
return {"model": _identity_type_name(hooks)}
381+
return {"object": _identity_type_name(hooks)}
382+
383+
369384
def _agent_identity_signature(agent: Agent[Any]) -> str:
370385
signature: dict[str, Any] = {
371386
"agent_type": _identity_type_name(agent),
@@ -375,7 +390,7 @@ def _agent_identity_signature(agent: Agent[Any]) -> str:
375390
"model": _normalize_identity_value(getattr(agent, "model", None)),
376391
"model_settings": _normalize_identity_value(getattr(agent, "model_settings", None)),
377392
"mcp_config": _normalize_capability_identity_value(getattr(agent, "mcp_config", None)),
378-
"hooks": _normalize_capability_identity_value(getattr(agent, "hooks", None)),
393+
"hooks": _hook_identity_signature(agent.hooks),
379394
"input_guardrails": sorted(
380395
_stable_identity_text(_normalize_capability_identity_value(guardrail))
381396
for guardrail in getattr(agent, "input_guardrails", [])
@@ -444,6 +459,36 @@ def _get_ambiguous_agent_ids(initial_agent: Agent[Any]) -> set[int]:
444459
return {agent_id for group in groups.values() if len(group) > 1 for agent_id in group}
445460

446461

462+
def _has_legacy_hook_identity_ambiguity(initial_agent: Agent[Any]) -> bool:
463+
"""Whether old ordinal identities could depend on unrecorded hook state."""
464+
seen_prefixes: set[tuple[str, str]] = set()
465+
for agent in _iter_agent_graph(initial_agent):
466+
# Root priority is independent of its signature and always sorts first.
467+
if agent is initial_agent or agent.hooks is None or callable(agent.hooks):
468+
continue
469+
signature = json.loads(_agent_identity_signature(agent))
470+
# The signature is sorted by JSON field name. Earlier configuration and
471+
# the hook type precede hook instance state, so they cannot be reordered
472+
# by changing that state. Later fields cannot provide this guarantee.
473+
prefix = _stable_identity_text(
474+
{key: value for key, value in signature.items() if key <= "hooks"}
475+
)
476+
key = (agent.name, prefix)
477+
if key in seen_prefixes:
478+
return True
479+
seen_prefixes.add(key)
480+
return False
481+
482+
483+
def _has_ambiguous_hook_identities(initial_agent: Agent[Any]) -> bool:
484+
"""Whether removing hook state leaves an owner dependent on traversal order."""
485+
ambiguous = _get_ambiguous_agent_ids(initial_agent)
486+
return any(
487+
id(agent) in ambiguous and agent.hooks is not None and not callable(agent.hooks)
488+
for agent in _iter_agent_graph(initial_agent)
489+
)
490+
491+
447492
def _build_agent_identity_map(initial_agent: Agent[Any]) -> dict[str, Agent[Any]]:
448493
"""Build a stable identity map that preserves duplicate agent names."""
449494
ordered_agents = list(_iter_agent_graph(initial_agent))

‎src/agents/run_state.py‎

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@
4343
_build_agent_identity_map,
4444
_build_agent_map,
4545
_get_ambiguous_agent_ids,
46+
_has_ambiguous_hook_identities,
47+
_has_legacy_hook_identity_ambiguity,
4648
_iter_agent_graph,
4749
)
4850
from ._tool_identity import (
@@ -242,7 +244,7 @@ def _default_run_state_validation_error(
242244
# 3. to_json() always emits CURRENT_SCHEMA_VERSION.
243245
# 4. Forward compatibility is intentionally fail-fast (older SDKs reject newer or unsupported
244246
# versions).
245-
CURRENT_SCHEMA_VERSION = "1.20"
247+
CURRENT_SCHEMA_VERSION = "1.21"
246248
_PROGRAMMATIC_TOOL_CALLING_MIN_SCHEMA_VERSION = "1.13"
247249
_HOSTED_MCP_APPROVALS_MIN_SCHEMA_VERSION = "1.14"
248250
_CURRENT_RESPONSE_OWNERSHIP_MIN_SCHEMA_VERSION = "1.17"
@@ -300,6 +302,7 @@ def _default_run_state_validation_error(
300302
"Persists the pending tool output guardrail result boundary so a resumed run withholds "
301303
"current-response diagnostics until its terminal guardrails complete."
302304
),
305+
"1.21": "Makes duplicate-agent identity independent of mutable hook instance state.",
303306
}
304307
SUPPORTED_SCHEMA_VERSIONS = frozenset(SCHEMA_VERSION_SUMMARIES)
305308

@@ -1906,13 +1909,23 @@ def to_json(
19061909
A dictionary representation of the run state.
19071910
19081911
Raises:
1909-
UserError: If required state (agent, context) is missing.
1912+
UserError: If required state (agent, context) is missing, or same-name agents
1913+
cannot be distinguished without hook instance attributes. Use unique agent
1914+
names before starting a persistable run in that case.
19101915
"""
19111916
if self._current_agent is None:
19121917
raise UserError("Cannot serialize RunState: No current agent")
19131918
if self._context is None:
19141919
raise UserError("Cannot serialize RunState: No context")
19151920

1921+
if self._starting_agent is not None and _has_ambiguous_hook_identities(
1922+
self._starting_agent
1923+
):
1924+
raise UserError(
1925+
"RunState cannot distinguish same-name agents without hook instance state. "
1926+
"Use unique agent names before starting a persistable run."
1927+
)
1928+
19161929
approvals_dict = self._serialize_approvals()
19171930
tool_invocations = self._serialize_tool_invocations()
19181931
hosted_mcp_approvals = self._serialize_hosted_mcp_approvals()
@@ -2325,6 +2338,12 @@ async def from_string(
23252338
server and apply authorized approval decisions to that server-owned state instead.
23262339
Neither `context_override` nor `strict_context` verifies snapshot integrity.
23272340
2341+
Hook instance attributes do not identify agents in schema 1.21 or later.
2342+
Same-name agents that cannot be distinguished without those attributes are
2343+
rejected. Older snapshots are rejected if hook state could have changed
2344+
their identity ordering. Use unique names before starting new persistable
2345+
runs; renaming agents does not repair an ambiguous existing checkpoint.
2346+
23282347
Executing pending local MCP calls requires recipient bindings written by schema 1.18
23292348
or later.
23302349
Keep the application's MCP server configuration and ordering unchanged when resuming.
@@ -2413,6 +2432,12 @@ async def from_json(
24132432
server and apply authorized approval decisions to that server-owned state instead.
24142433
Neither `context_override` nor `strict_context` verifies snapshot integrity.
24152434
2435+
Hook instance attributes do not identify agents in schema 1.21 or later.
2436+
Same-name agents that cannot be distinguished without those attributes are
2437+
rejected. Older snapshots are rejected if hook state could have changed
2438+
their identity ordering. Use unique names before starting new persistable
2439+
runs; renaming agents does not repair an ambiguous existing checkpoint.
2440+
24162441
Executing pending local MCP calls requires recipient bindings written by schema 1.18
24172442
or later.
24182443
Keep the application's MCP server configuration and ordering unchanged when resuming.
@@ -4167,6 +4192,22 @@ async def _build_run_state_from_json(
41674192
UserError,
41684193
)
41694194

4195+
if (schema_major, schema_minor) < (1, 21) and _has_legacy_hook_identity_ambiguity(
4196+
initial_agent
4197+
):
4198+
raise validation_error_factory(
4199+
"Cannot safely restore legacy duplicate-agent identities with hooks. "
4200+
"Start a new run with unique agent names; the saved hook ordering is unavailable.",
4201+
UserError,
4202+
)
4203+
4204+
if _has_ambiguous_hook_identities(initial_agent):
4205+
raise validation_error_factory(
4206+
"RunState cannot distinguish same-name agents without hook instance state. "
4207+
"Use unique agent names before starting a persistable run.",
4208+
UserError,
4209+
)
4210+
41704211
agent_identity_map = _build_agent_identity_map(initial_agent)
41714212
agent_map = _build_agent_map(initial_agent)
41724213

@@ -5529,6 +5570,14 @@ def _clone_original_input(original_input: str | list[Any]) -> str | list[Any]:
55295570
f"New snapshots are written as version {CURRENT_SCHEMA_VERSION}."
55305571
),
55315572
"Run state agent not found in agent map",
5573+
(
5574+
"RunState cannot distinguish same-name agents without hook instance state. "
5575+
"Use unique agent names before starting a persistable run."
5576+
),
5577+
(
5578+
"Cannot safely restore legacy duplicate-agent identities with hooks. "
5579+
"Start a new run with unique agent names; the saved hook ordering is unavailable."
5580+
),
55325581
"Run state pending_input must be a list",
55335582
"Run state pending Session write is invalid",
55345583
"Invalid tool output guardrail result boundary",
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"$schemaVersion": "1.20",
3+
"auto_previous_response_id": false,
4+
"context": {
5+
"approvals": {},
6+
"context": {},
7+
"context_meta": {
8+
"omitted": false,
9+
"original_type": "mapping",
10+
"requires_deserializer": false,
11+
"serialized_via": "mapping"
12+
},
13+
"tool_invocations": {},
14+
"usage": {
15+
"input_tokens": 0,
16+
"input_tokens_details": [
17+
{
18+
"cache_write_tokens": 0,
19+
"cached_tokens": 0
20+
}
21+
],
22+
"output_tokens": 0,
23+
"output_tokens_details": [
24+
{
25+
"reasoning_tokens": 0
26+
}
27+
],
28+
"request_usage_entries": [],
29+
"requests": 0,
30+
"total_tokens": 0
31+
}
32+
},
33+
"conversation_id": null,
34+
"current_agent": {
35+
"name": "compat-agent"
36+
},
37+
"current_step": null,
38+
"current_turn": 0,
39+
"current_turn_persisted_item_count": 0,
40+
"generated_items": [],
41+
"generated_prompt_cache_key": null,
42+
"generated_session_item_indexes": [],
43+
"input_guardrail_results": [],
44+
"last_model_response": null,
45+
"last_processed_response": {
46+
"apply_patch_actions": [],
47+
"computer_actions": [],
48+
"custom_tool_actions": [],
49+
"functions": [],
50+
"handoffs": [],
51+
"interruptions": [],
52+
"local_shell_actions": [],
53+
"mcp_approval_requests": [],
54+
"mcp_tool_bindings": {},
55+
"new_items": [],
56+
"shell_actions": [],
57+
"tool_output_guardrail_result_start": 0,
58+
"tools_used": []
59+
},
60+
"max_turns": 10,
61+
"model_responses": [],
62+
"nested_history_owned_session_item_refs": [],
63+
"no_active_agent_run": true,
64+
"original_input": "historical input",
65+
"output_guardrail_results": [],
66+
"pending_input": [],
67+
"previous_response_id": null,
68+
"reasoning_item_id_policy": null,
69+
"session_items": [],
70+
"tool_input_guardrail_results": [],
71+
"tool_output_guardrail_results": [],
72+
"tool_use_tracker": {},
73+
"trace": null
74+
}

‎tests/fixtures/run_state/generate_corpus.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
# from main either.
4444
RELEASED_1_18_WRITER = "ce8ae9f368e7e3e2f495fc80a0c44137e88b78c4"
4545
HELD_WRITE_1_19_WRITER = "9303a8f8b8a528f572582ba09743b37b9fd0735c"
46+
GUARDRAIL_1_20_WRITER = "125efa029b4bfd84238bd2c4fd69c3406f802663"
4647

4748
LEGACY_CANONICAL_COMPATIBILITY_NOTE = (
4849
"The release-boundary schema renumbering introduced this reader version without a writer "
@@ -539,6 +540,20 @@ def approval(call_id):
539540
"interpretation; this is not a historical checkpoint from a released version."
540541
),
541542
),
543+
Scenario(
544+
"1.20",
545+
GUARDRAIL_1_20_WRITER,
546+
"tool_output_guardrail_boundary",
547+
"""
548+
from agents.run_internal.run_steps import ProcessedResponse
549+
550+
state._last_processed_response = ProcessedResponse(
551+
new_items=[], handoffs=[], functions=[], computer_actions=[], local_shell_calls=[],
552+
shell_calls=[], apply_patch_calls=[], tools_used=[], mcp_approval_requests=[],
553+
interruptions=[], tool_output_guardrail_result_start=0,
554+
)
555+
""",
556+
),
542557
)
543558

544559

@@ -583,6 +598,7 @@ def approval(call_id):
583598
"minimal payload it emits, not a historical checkpoint from a released version."
584599
),
585600
),
601+
Scenario("1.20", GUARDRAIL_1_20_WRITER, "minimal", ""),
586602
)
587603

588604

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{
2+
"$schemaVersion": "1.20",
3+
"auto_previous_response_id": false,
4+
"context": {
5+
"approvals": {},
6+
"context": {},
7+
"context_meta": {
8+
"omitted": false,
9+
"original_type": "mapping",
10+
"requires_deserializer": false,
11+
"serialized_via": "mapping"
12+
},
13+
"tool_invocations": {},
14+
"usage": {
15+
"input_tokens": 0,
16+
"input_tokens_details": [
17+
{
18+
"cache_write_tokens": 0,
19+
"cached_tokens": 0
20+
}
21+
],
22+
"output_tokens": 0,
23+
"output_tokens_details": [
24+
{
25+
"reasoning_tokens": 0
26+
}
27+
],
28+
"request_usage_entries": [],
29+
"requests": 0,
30+
"total_tokens": 0
31+
}
32+
},
33+
"conversation_id": null,
34+
"current_agent": {
35+
"name": "compat-agent"
36+
},
37+
"current_step": null,
38+
"current_turn": 0,
39+
"current_turn_persisted_item_count": 0,
40+
"generated_items": [],
41+
"generated_prompt_cache_key": null,
42+
"generated_session_item_indexes": [],
43+
"input_guardrail_results": [],
44+
"last_model_response": null,
45+
"last_processed_response": null,
46+
"max_turns": 10,
47+
"model_responses": [],
48+
"nested_history_owned_session_item_refs": [],
49+
"no_active_agent_run": true,
50+
"original_input": "historical input",
51+
"output_guardrail_results": [],
52+
"pending_input": [],
53+
"previous_response_id": null,
54+
"reasoning_item_id_policy": null,
55+
"session_items": [],
56+
"tool_input_guardrail_results": [],
57+
"tool_output_guardrail_results": [],
58+
"tool_use_tracker": {},
59+
"trace": null
60+
}

‎tests/fixtures/run_state/sources.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,13 @@
143143
"note": "The unreleased held-write scenario includes the current-response boundary. The recorded 1.19 writer serializes this canonical scenario payload without interpretation; this is not a historical checkpoint from a released version.",
144144
"provenance": "canonical_compatibility",
145145
"version": "1.19"
146+
},
147+
{
148+
"commit": "125efa029b4bfd84238bd2c4fd69c3406f802663",
149+
"feature": "tool_output_guardrail_boundary",
150+
"fixture": "features/v1_20_tool_output_guardrail_boundary.json",
151+
"provenance": "historical_writer",
152+
"version": "1.20"
146153
}
147154
],
148155
"resume": {
@@ -226,6 +233,10 @@
226233
"commit": "74e8c1e22d7441bd42c58bcd4270937ccc2dca8c",
227234
"fixture": "minimal/v1_2.json"
228235
},
236+
"1.20": {
237+
"commit": "125efa029b4bfd84238bd2c4fd69c3406f802663",
238+
"fixture": "minimal/v1_20.json"
239+
},
229240
"1.3": {
230241
"commit": "6814a54711f591712c893f0a8be1cf56c512ae63",
231242
"fixture": "minimal/v1_3.json"

‎tests/test_run_state.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -981,7 +981,7 @@ async def test_tool_guardrail_boundary_requires_its_schema_version(
981981
]
982982

983983
snapshot = json.loads(state.to_string())
984-
assert snapshot["$schemaVersion"] == "1.20"
984+
assert snapshot["$schemaVersion"] == CURRENT_SCHEMA_VERSION
985985
restored = await RunState.from_json(agent, snapshot)
986986
assert restored._last_processed_response is not None
987987
assert restored._last_processed_response.tool_output_guardrail_result_start == 0
@@ -9005,6 +9005,7 @@ def test_supported_schema_versions_match_released_boundary(self):
90059005
"1.17",
90069006
"1.18",
90079007
"1.19",
9008+
"1.20",
90089009
CURRENT_SCHEMA_VERSION,
90099010
}
90109011
)

0 commit comments

Comments
 (0)