|
43 | 43 | _build_agent_identity_map, |
44 | 44 | _build_agent_map, |
45 | 45 | _get_ambiguous_agent_ids, |
| 46 | + _has_ambiguous_hook_identities, |
| 47 | + _has_legacy_hook_identity_ambiguity, |
46 | 48 | _iter_agent_graph, |
47 | 49 | ) |
48 | 50 | from ._tool_identity import ( |
@@ -242,7 +244,7 @@ def _default_run_state_validation_error( |
242 | 244 | # 3. to_json() always emits CURRENT_SCHEMA_VERSION. |
243 | 245 | # 4. Forward compatibility is intentionally fail-fast (older SDKs reject newer or unsupported |
244 | 246 | # versions). |
245 | | -CURRENT_SCHEMA_VERSION = "1.20" |
| 247 | +CURRENT_SCHEMA_VERSION = "1.21" |
246 | 248 | _PROGRAMMATIC_TOOL_CALLING_MIN_SCHEMA_VERSION = "1.13" |
247 | 249 | _HOSTED_MCP_APPROVALS_MIN_SCHEMA_VERSION = "1.14" |
248 | 250 | _CURRENT_RESPONSE_OWNERSHIP_MIN_SCHEMA_VERSION = "1.17" |
@@ -300,6 +302,7 @@ def _default_run_state_validation_error( |
300 | 302 | "Persists the pending tool output guardrail result boundary so a resumed run withholds " |
301 | 303 | "current-response diagnostics until its terminal guardrails complete." |
302 | 304 | ), |
| 305 | + "1.21": "Makes duplicate-agent identity independent of mutable hook instance state.", |
303 | 306 | } |
304 | 307 | SUPPORTED_SCHEMA_VERSIONS = frozenset(SCHEMA_VERSION_SUMMARIES) |
305 | 308 |
|
@@ -1906,13 +1909,23 @@ def to_json( |
1906 | 1909 | A dictionary representation of the run state. |
1907 | 1910 |
|
1908 | 1911 | 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. |
1910 | 1915 | """ |
1911 | 1916 | if self._current_agent is None: |
1912 | 1917 | raise UserError("Cannot serialize RunState: No current agent") |
1913 | 1918 | if self._context is None: |
1914 | 1919 | raise UserError("Cannot serialize RunState: No context") |
1915 | 1920 |
|
| 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 | + |
1916 | 1929 | approvals_dict = self._serialize_approvals() |
1917 | 1930 | tool_invocations = self._serialize_tool_invocations() |
1918 | 1931 | hosted_mcp_approvals = self._serialize_hosted_mcp_approvals() |
@@ -2325,6 +2338,12 @@ async def from_string( |
2325 | 2338 | server and apply authorized approval decisions to that server-owned state instead. |
2326 | 2339 | Neither `context_override` nor `strict_context` verifies snapshot integrity. |
2327 | 2340 |
|
| 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 | +
|
2328 | 2347 | Executing pending local MCP calls requires recipient bindings written by schema 1.18 |
2329 | 2348 | or later. |
2330 | 2349 | Keep the application's MCP server configuration and ordering unchanged when resuming. |
@@ -2413,6 +2432,12 @@ async def from_json( |
2413 | 2432 | server and apply authorized approval decisions to that server-owned state instead. |
2414 | 2433 | Neither `context_override` nor `strict_context` verifies snapshot integrity. |
2415 | 2434 |
|
| 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 | +
|
2416 | 2441 | Executing pending local MCP calls requires recipient bindings written by schema 1.18 |
2417 | 2442 | or later. |
2418 | 2443 | Keep the application's MCP server configuration and ordering unchanged when resuming. |
@@ -4167,6 +4192,22 @@ async def _build_run_state_from_json( |
4167 | 4192 | UserError, |
4168 | 4193 | ) |
4169 | 4194 |
|
| 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 | + |
4170 | 4211 | agent_identity_map = _build_agent_identity_map(initial_agent) |
4171 | 4212 | agent_map = _build_agent_map(initial_agent) |
4172 | 4213 |
|
@@ -5529,6 +5570,14 @@ def _clone_original_input(original_input: str | list[Any]) -> str | list[Any]: |
5529 | 5570 | f"New snapshots are written as version {CURRENT_SCHEMA_VERSION}." |
5530 | 5571 | ), |
5531 | 5572 | "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 | + ), |
5532 | 5581 | "Run state pending_input must be a list", |
5533 | 5582 | "Run state pending Session write is invalid", |
5534 | 5583 | "Invalid tool output guardrail result boundary", |
|
0 commit comments