{"record":{"id":"07341741cf53c9c0","repo":"rohitg00/ai-engineering-from-scratch","slug":"requires-action-must-reference-known-actionable-ev","errorCode":null,"errorMessage":"requires_action must reference known actionable event IDs","messagePattern":"requires_action must reference known actionable event IDs","errorType":"exception","errorClass":"EventStreamError","httpStatus":null,"severity":"error","filePath":"certifications/claude/lessons/12-claude-agent-sdk-and-hooks/code/main.py","lineNumber":106,"sourceCode":"        elif event_type in {\"agent.custom_tool_use\", \"agent.tool_use\", \"agent.mcp_tool_use\"}:\n            actionable.add(event_id)\n        elif event_type in {\"user.custom_tool_result\", \"user.tool_confirmation\"}:\n            reference = event.get(\"custom_tool_use_id\") or event.get(\"tool_use_id\")\n            if not isinstance(reference, str) or reference not in actionable:\n                raise EventStreamError(\"tool result or confirmation must reference a known action\")\n            pending.discard(reference)\n        elif event_type == \"session.status_idle\":\n            status = \"idle\"\n            reason = event.get(\"stop_reason\")\n            if not isinstance(reason, dict) or reason.get(\"type\") not in {\"requires_action\", \"end_turn\"}:\n                raise EventStreamError(\"idle status needs a supported stop_reason\")\n            stop_reason = reason[\"type\"]\n            if stop_reason == \"requires_action\":\n                event_ids = reason.get(\"event_ids\")\n                if not isinstance(event_ids, list) or not event_ids or not all(\n                    isinstance(item, str) and item in actionable for item in event_ids\n                ):\n                    raise EventStreamError(\"requires_action must reference known actionable event IDs\")\n                pending = set(event_ids)\n            else:\n                pending.clear()\n        elif event_type == \"session.status_terminated\":\n            status = \"terminated\"\n            stop_reason = \"terminated\"\n            pending.clear()\n        elif event_type == \"session.error\":\n            raise EventStreamError(\"session emitted an error event\")\n\n    complete = status == \"terminated\" or (status == \"idle\" and stop_reason == \"end_turn\")\n    return EventSummary(\n        status=status,\n        stop_reason=stop_reason,\n        messages=messages,\n        pending_action_ids=sorted(pending),\n        last_event_id=last_event_id,\n        preview_text=\"\".join(preview_parts),","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/certifications/claude/lessons/12-claude-agent-sdk-and-hooks/code/main.py#L88-L124","documentation":"Raised in consume_managed_events when a requires_action stop_reason lists event_ids that are missing, empty, or not all present in the actionable set of tool-use events seen so far. The terminal state must point only at real outstanding tool actions; otherwise the UI could prompt the user about phantom actions.","triggerScenarios":"Thrown at certifications/claude/lessons/12-claude-agent-sdk-and-hooks/code/main.py:106 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Ensure every id in stop_reason.event_ids matches a previously emitted agent.*_tool_use event id","Do not include ids of actions already resolved by tool results or confirmations","Fix fixtures that reference tool-use ids without emitting the corresponding events"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}