port: sync with @openrouter/agent 0.8.0 (680bceb)

Generated by the Upstreamer pipeline in this PR, run locally end to end
(scripts/upstream --ref @openrouter/agent@0.8.0). Both gates passed:
mechanical verifier === PASS: 0 failures ===, parity eval PASS WITH
WARNINGS on the second pass (.upstreamer/eval-report.md).

Ports the 0.7.2 -> 0.8.0 delta: lifecycle hooks system (HooksManager +
nine built-in hooks), versioned conversation-state serialization,
awaiting_client_tools for unresolved manual tool calls, default-on
allow_final_response with DEFAULT_FINAL_RESPONSE_DIRECTIVE,
strict_final_response / empty-final-retry tolerance, and MCP tool-result
source discrimination. state.yaml advances to 680bceb, so the first CI
run after merge is a no-op until the next upstream release.

First-pass eval FAILed on three real findings (Stop-hook force_resume
was not a zero-cost retry, MCP branding surface missing, thin hooks test
coverage); all three fixed and re-verified in the second pass — see the
eval report for the traced evidence.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: LukasParke

.upstreamer/eval-report.md

@@ -1,6 +1,10 @@
 # Last upstream commit successfully ported AND verified AND eval-passed.
-# Seeded at @openrouter/agent@0.7.2 (commit adc7939), the release these ports
-# were generated from, so the first run is an incremental 0.7.2 -> 0.8.0 delta
-# rather than a full from-scratch regeneration.
+# 680bceb ported the 0.7.2 -> 0.8.0 delta: the lifecycle hooks system
+# (HooksManager, PreToolUse/PostToolUse/PostToolUseFailure/UserPromptSubmit/
+# Stop/PermissionRequest/SessionStart/SessionEnd/PostModelCall), versioned
+# ConversationState serialization, awaiting_client_tools for unresolved
+# manual tool calls, default-on allow_final_response with
+# DEFAULT_FINAL_RESPONSE_DIRECTIVE, strict_final_response / empty-final-retry
+# tolerance, and MCP tool-result source discrimination.
 # Only scripts/upstream runs should change this.
-upstream_commit: adc7939f4b7ed85b1a060d13433b8be6063cff73
+upstream_commit: 680bceb4598f228d3e2ec58e2416e4335cdff059

.upstreamer/state.yaml

@@ -136,6 +136,10 @@ web = server_tool({"type": "web_search_2025_08_26", "max_results": 5})
 
 Use `require_approval` on a tool or `require_approval` on the request to pause sensitive calls before execution. Approval resume requires a state accessor with async `load()` and `save()` methods.
 
+Manual tools (`execute=False`, no `on_tool_called`) pause the loop with status `"awaiting_client_tools"` when the model calls them, instead of silently dropping the call. Read the unresolved calls via `get_pending_tool_calls()` / `get_state()`, execute them yourself, and continue by calling `call_model` again with `function_call_output` items in `input`.
+
+For durable cross-process storage, serialize state with `serialize_conversation_state` / `deserialize_conversation_state` rather than storing raw dataclass fields. The wire format is versioned (`CONVERSATION_STATE_VERSION`); a version mismatch raises `UnsupportedStateVersionError` and malformed JSON raises `InvalidStateError`, so a store can never silently misinterpret a future shape.
+
 Tool context is kept outside the model transcript. Provide a context mapping with per-tool keys and optional `shared` state. Tool execution receives `ctx["local"]`, `ctx["shared"]`, `ctx["set_context"]`, and `ctx["set_shared_context"]`.
 
 ```python
@@ -151,6 +155,22 @@ result = call_model(
 )
 ```
 
+## Lifecycle Hooks
+
+Pass a `HooksManager` (or an inline `{hook_name: [HookEntry(...)]}` dict of built-in hooks) via `hooks=` to observe or intervene in a run: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`, `Stop`, `PermissionRequest`, `SessionStart`, `SessionEnd`, and `PostModelCall`. Handlers receive a validated payload dict and a `LifecycleHookContext` (`session_id`, `hook_name`, `cancel_event`).
+
+```python
+from openrouter_agent import HookEntry, HookName, HooksManager
+
+hooks = HooksManager()
+hooks.on(HookName.PreToolUse.value, HookEntry(handler=lambda payload, ctx: None, matcher="delete_file"))
+hooks.on(HookName.SessionEnd.value, HookEntry(handler=lambda payload, ctx: print(payload["total_usage"])))
+
+result = call_model(client, {"model": model, "input": prompt, "tools": tools, "hooks": hooks})
+```
+
+`SessionStart` fires once per run with a config summary; `SessionEnd` fires once with aggregated `total_usage` (summed across every `PostModelCall`) and is guaranteed to fire — and any pending async hook work drained — even when a no-tools stream raises. `PreToolUse` can block a call (`{"block": "reason"}`) or mutate its input (`{"mutated_input": {...}}`); `PermissionRequest` can pre-empt the approval gate with `{"decision": "allow" | "deny" | "ask_user"}`; `Stop` can force the loop to keep going past a `stop_when` hit with `{"force_resume": True, "append_prompt": "..."}`. A `HooksManager` instance is safe to share across concurrent `call_model` runs — session identity is threaded per emit, not stored as manager-level mutable state.
+
 ## Stop Conditions
 
 The built-ins mirror the TypeScript package and OR together when provided as a list:
@@ -161,7 +181,7 @@ The built-ins mirror the TypeScript package and OR together when provided as a l
 - `max_cost(dollars)`
 - `finish_reason_is(reason)`
 
-Set `allow_final_response=True` or a string to ask for one final no-tools turn when a stop condition fires on a tool-call turn.
+When a stop condition fires while the model is still emitting tool calls, `call_model` makes one more turn with `tool_choice="none"` by default (tools stay in the request so the prompt-cache prefix survives) so the run ends with a natural-language answer. `allow_final_response` tunes this: `True` or omitted appends `DEFAULT_FINAL_RESPONSE_DIRECTIVE` as a user message, a non-empty string replaces the wording, `""` appends nothing, and `False` disables the extra turn entirely.
 
 ## Format Compatibility
 

README.md

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openrouter-agent"
-version = "0.7.2"
+version = "0.8.0"
 description = "Python port of @openrouter/agent: OpenRouter tool orchestration, streaming, state, and format compatibility."
 readme = "README.md"
 requires-python = ">=3.9.2"

pyproject.toml

@@ -65,15 +65,54 @@
 from .claude_constants import ClaudeContentBlockType, NonClaudeMessageRole
 from .claude_type_guards import is_claude_style_messages
 from .conversation_state import (
+    CONVERSATION_STATE_VERSION,
+    InvalidStateError,
+    UnsupportedStateVersionError,
     append_to_messages,
     create_initial_state,
     create_rejected_result,
     create_unsent_result,
+    deserialize_conversation_state,
     generate_conversation_id,
     partition_tool_calls,
+    serialize_conversation_state,
     tool_requires_approval,
     update_state,
 )
+from .hooks_manager import HooksManager
+from .hooks_schemas import (
+    HookDefinition,
+    HookName,
+    HookRegistry,
+    ModelCallUsage,
+    PermissionRequestPayload,
+    PermissionRequestResult,
+    PostModelCallPayload,
+    PostToolUseFailurePayload,
+    PostToolUsePayload,
+    PreToolUsePayload,
+    PreToolUseResult,
+    SessionEndPayload,
+    SessionStartPayload,
+    SessionUsageTotals,
+    StopPayload,
+    StopResult,
+    UserPromptSubmitPayload,
+    UserPromptSubmitResult,
+)
+from .hooks_types import (
+    DEFAULT_ASYNC_TIMEOUT_MS,
+    HOOK_BEHAVIOR,
+    AsyncOutput,
+    EmitResult,
+    HookBehavior,
+    HookEntry,
+    HookHandler,
+    InlineHookConfig,
+    LifecycleHookContext,
+    ToolMatcher,
+    is_async_output,
+)
 from .item_types import (
     AssistantMessageItem,
     CallFileSearchItem,
@@ -90,7 +129,7 @@
     SystemMessageItem,
     UserMessageItem,
 )
-from .model_result import GetResponseOptions, ModelResult
+from .model_result import DEFAULT_FINAL_RESPONSE_DIRECTIVE, GetResponseOptions, ModelResult
 from .next_turn_params import (
     apply_next_turn_params_to_request,
     build_next_turn_params_context,
@@ -111,7 +150,7 @@
     get_unsupported_content_summary,
     has_unsupported_content,
 )
-from .tool import server_tool, tool
+from .tool import mark_mcp, server_tool, tool
 from .tool_context import ContextInput, ToolContextStore, build_tool_execute_context
 from .tool_event_broadcaster import ToolEventBroadcaster
 from .tool_types import (
@@ -129,6 +168,7 @@
     InferToolOutput,
     InferToolOutputsUnion,
     ManualTool,
+    McpBranded,
     NextTurnParamsContext,
     NextTurnParamsFunctions,
     ParsedToolCall,
@@ -172,6 +212,7 @@
     is_generator_tool,
     is_hitl_tool,
     is_manual_tool,
+    is_mcp_tool,
     is_regular_execute_tool,
     is_server_tool,
     is_tool_call_output_event,
@@ -202,11 +243,13 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "AfterSuccessContext",
     "AfterSuccessHook",
     "AssistantMessageItem",
+    "AsyncOutput",
     "BaseInputsUnion",
     "BeforeCreateRequestContext",
     "BeforeCreateRequestHook",
     "BeforeRequestContext",
     "BeforeRequestHook",
+    "CONVERSATION_STATE_VERSION",
     "CallFileSearchItem",
     "CallFunctionToolItem",
     "CallImageGenerationItem",
@@ -220,11 +263,14 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "ClientTool",
     "ConversationState",
     "ConversationStatus",
+    "DEFAULT_ASYNC_TIMEOUT_MS",
+    "DEFAULT_FINAL_RESPONSE_DIRECTIVE",
     "DeveloperMessageItem",
     "EasyInputMessage",
     "EasyInputMessageContentInputImage",
     "EasyInputMessageContentUnion1",
     "EasyInputMessageRoleUnion",
+    "EmitResult",
     "EnhancedResponseStreamEvent",
     "ErrorEvent",
     "ErrorItem",
@@ -235,23 +281,36 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "GetResponseOptions",
     "HITLTool",
     "HITLToolFunction",
+    "HOOK_BEHAVIOR",
     "HasApprovalTools",
     "Hook",
+    "HookBehavior",
     "HookContext",
+    "HookDefinition",
+    "HookEntry",
+    "HookHandler",
+    "HookName",
+    "HookRegistry",
+    "HooksManager",
     "InferToolEvent",
     "InferToolEventsUnion",
     "InferToolInput",
     "InferToolOutput",
     "InferToolOutputsUnion",
+    "InlineHookConfig",
     "InputAudio",
     "InputFile",
     "InputImage",
     "InputMessageItem",
     "InputText",
     "InputVideo",
     "InputsUnion",
+    "InvalidStateError",
     "Item",
+    "LifecycleHookContext",
     "ManualTool",
+    "McpBranded",
+    "ModelCallUsage",
     "ModelResult",
     "NewUserMessageItem",
     "NextTurnParamsContext",
@@ -272,6 +331,13 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "OutputWebSearchCallItem",
     "ParsedToolCall",
     "PartialResponse",
+    "PermissionRequestPayload",
+    "PermissionRequestResult",
+    "PostModelCallPayload",
+    "PostToolUseFailurePayload",
+    "PostToolUsePayload",
+    "PreToolUsePayload",
+    "PreToolUseResult",
     "ReasoningItem",
     "RequestOptions",
     "ResolvedCallModelInput",
@@ -286,9 +352,14 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "ServerToolConfig",
     "ServerToolResultItem",
     "ServerToolType",
+    "SessionEndPayload",
+    "SessionStartPayload",
+    "SessionUsageTotals",
     "StateAccessor",
     "StepResult",
     "StopCondition",
+    "StopPayload",
+    "StopResult",
     "StopWhen",
     "StreamEvents",
     "StreamableOutputItem",
@@ -303,6 +374,7 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "ToolExecutionResult",
     "ToolExecutionResultUnion",
     "ToolHasApproval",
+    "ToolMatcher",
     "ToolOutputContentItem",
     "ToolPreliminaryResultEvent",
     "ToolResultEvent",
@@ -317,8 +389,11 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "TypedToolCall",
     "TypedToolCallUnion",
     "UnsentToolResult",
+    "UnsupportedStateVersionError",
     "Usage",
     "UserMessageItem",
+    "UserPromptSubmitPayload",
+    "UserPromptSubmitResult",
     "Warning",
     "append_to_messages",
     "apply_next_turn_params_to_request",
@@ -329,6 +404,7 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "create_initial_state",
     "create_rejected_result",
     "create_unsent_result",
+    "deserialize_conversation_state",
     "execute_next_turn_params_functions",
     "extract_unsupported_content",
     "finish_reason_is",
@@ -341,12 +417,14 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "has_execute_function",
     "has_tool_call",
     "has_unsupported_content",
+    "is_async_output",
     "is_auto_resolvable_tool",
     "is_client_tool",
     "is_claude_style_messages",
     "is_generator_tool",
     "is_hitl_tool",
     "is_manual_tool",
+    "is_mcp_tool",
     "is_regular_execute_tool",
     "is_server_tool",
     "is_stop_condition_met",
@@ -355,11 +433,13 @@ def before_create_request(self, hook_ctx: BeforeCreateRequestContext, request: A
     "is_tool_result_event",
     "is_turn_end_event",
     "is_turn_start_event",
+    "mark_mcp",
     "max_cost",
     "max_tokens_used",
     "normalize_input_to_array",
     "partition_tool_calls",
     "resolve_async_functions",
+    "serialize_conversation_state",
     "server_tool",
     "step_count_is",
     "to_chat_message",

src/openrouter_agent/__init__.py

@@ -19,6 +19,8 @@ class CallModelInput(TypedDict, total=False):
     context: Mapping[str, Any]
     shared_context_schema: Any
     allow_final_response: Any
+    strict_final_response: bool
+    hooks: Any
 
 
 CallModelInputWithState = CallModelInput
@@ -42,6 +44,8 @@ class ResolvedCallModelInput(TypedDict, total=False):
     "on_turn_start",
     "on_turn_end",
     "allow_final_response",
+    "strict_final_response",
+    "hooks",
 }
 
 

src/openrouter_agent/async_params.py

@@ -2,6 +2,7 @@
 
 from typing import Any, Mapping, Optional
 
+from .hooks_resolve import resolve_hooks
 from .model_result import ModelResult
 from .tool_executor import convert_tools_to_api_format
 
@@ -21,6 +22,8 @@ def call_model(client: Any, request: Mapping[str, Any], options: Optional[Mappin
         "on_turn_start",
         "on_turn_end",
         "allow_final_response",
+        "strict_final_response",
+        "hooks",
     ):
         final_request.pop(key, None)
     if tools is not None:
@@ -45,5 +48,7 @@ def call_model(client: Any, request: Mapping[str, Any], options: Optional[Mappin
             "on_turn_start": request.get("on_turn_start"),
             "on_turn_end": request.get("on_turn_end"),
             "allow_final_response": request.get("allow_final_response"),
+            "strict_final_response": request.get("strict_final_response"),
+            "hooks": resolve_hooks(request.get("hooks")),
         }
     )