fix: send hook_config to server in RemoteConversation

examples/02_remote_agent_server/01_convo_with_local_agent_server.py

@@ -4,16 +4,23 @@
 import tempfile
 import threading
 import time
+from pathlib import Path
 
 from pydantic import SecretStr
 
 from openhands.sdk import LLM, Conversation, RemoteConversation, Workspace, get_logger
 from openhands.sdk.event import ConversationStateUpdateEvent
+from openhands.sdk.hooks import HookConfig, HookDefinition, HookMatcher
 from openhands.tools.preset.default import get_default_agent
 
 
 logger = get_logger(__name__)
 
+# Hook script directory - reuse the hook scripts from 33_hooks example
+HOOK_SCRIPTS_DIR = (
+    Path(__file__).parent.parent / "01_standalone_sdk/33_hooks/hook_scripts"
+)
+
 
 def _stream_output(stream, prefix, target_stream):
     """Stream output from subprocess to target stream with prefix."""
@@ -168,10 +175,36 @@ def event_callback(event):
     )
     logger.info(f"Output: {result.stdout}")
 
+    # Configure hooks - demonstrating the hooks system with RemoteConversation
+    # Server-side hooks (PreToolUse, PostToolUse, UserPromptSubmit, Stop) are
+    # executed by the agent server. Client-side hooks (SessionStart, SessionEnd)
+    # are executed locally.
+    log_file = Path("/tmp/tool_usage.log")
+
+    hook_config = HookConfig(
+        # PostToolUse hook - logs all tool usage to a file
+        # Note: This won't work with RemoteConversation (warning will be shown)
+        # but demonstrates how hooks would be configured
+        post_tool_use=[
+            HookMatcher(
+                matcher="*",
+                hooks=[
+                    HookDefinition(
+                        command=(
+                            f"LOG_FILE={log_file} {HOOK_SCRIPTS_DIR / 'log_tools.sh'}"
+                        ),
+                        timeout=5,
+                    )
+                ],
+            )
+        ],
+    )
+
     conversation = Conversation(
         agent=agent,
         workspace=workspace,
         callbacks=[event_callback],
+        hook_config=hook_config,
     )
     assert isinstance(conversation, RemoteConversation)
 

openhands-sdk/openhands/sdk/__init__.py

@@ -22,7 +22,7 @@
     RemoteConversation,
 )
 from openhands.sdk.conversation.conversation_stats import ConversationStats
-from openhands.sdk.event import Event, LLMConvertibleEvent
+from openhands.sdk.event import Event, HookExecutionEvent, LLMConvertibleEvent
 from openhands.sdk.event.llm_convertible import MessageEvent
 from openhands.sdk.io import FileStore, LocalFileStore
 from openhands.sdk.llm import (
@@ -99,6 +99,7 @@
     "MCPToolDefinition",
     "MCPToolObservation",
     "MessageEvent",
+    "HookExecutionEvent",
     "create_mcp_tools",
     "get_logger",
     "Conversation",

openhands-sdk/openhands/sdk/agent/agent.py

@@ -203,6 +203,8 @@ def init_state(
             dynamic_context=TextContent(text=dynamic_context)
             if dynamic_context
             else None,
+            # Include hook_config from state for observability
+            hook_config=state.hook_config,
         )
         on_event(event)
 

openhands-sdk/openhands/sdk/conversation/base.py

@@ -30,6 +30,7 @@
 if TYPE_CHECKING:
     from openhands.sdk.agent.base import AgentBase
     from openhands.sdk.conversation.state import ConversationExecutionStatus
+    from openhands.sdk.hooks import HookConfig
 
 
 CallbackType = TypeVar(
@@ -95,6 +96,11 @@ def stats(self) -> ConversationStats:
         """The conversation statistics."""
         ...
 
+    @property
+    def hook_config(self) -> "HookConfig | None":
+        """The hook configuration for this conversation."""
+        ...
+
 
 class BaseConversation(ABC):
     """Abstract base class for conversation implementations.

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -391,6 +391,9 @@ def _ensure_plugins_loaded(self) -> None:
 
         # Set up hook processor with the combined config
         if final_hook_config is not None:
+            # Store final hook_config in state for observability
+            self._state.hook_config = final_hook_config
+
             self._hook_processor, self._on_event = create_hook_callback(
                 hook_config=final_hook_config,
                 working_dir=str(self.workspace.working_dir),

openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py

@@ -46,7 +46,6 @@
 from openhands.sdk.hooks import (
     HookConfig,
     HookEventProcessor,
-    HookEventType,
     HookManager,
 )
 from openhands.sdk.llm import LLM, Message, TextContent
@@ -531,6 +530,15 @@ def stats(self) -> ConversationStats:
         stats_data = info.get("stats", {})
         return ConversationStats.model_validate(stats_data)
 
+    @property
+    def hook_config(self) -> HookConfig | None:
+        """Get hook configuration (fetched from remote)."""
+        info = self._get_conversation_info()
+        hook_config_data = info.get("hook_config")
+        if hook_config_data is not None:
+            return HookConfig.model_validate(hook_config_data)
+        return None
+
     def model_dump(self, **_kwargs):
         """Get a dictionary representation of the remote state."""
         info = self._get_conversation_info()
@@ -654,6 +662,8 @@ def __init__(
                 "tool_module_qualnames": tool_qualnames,
                 # Include plugins to load on server
                 "plugins": [p.model_dump() for p in plugins] if plugins else None,
+                # Include hook_config for server-side hooks
+                "hook_config": hook_config.model_dump() if hook_config else None,
             }
             if stuck_detection_thresholds is not None:
                 # Convert to StuckDetectionThresholds if dict, then serialize
@@ -769,17 +779,9 @@ def run_complete_callback(event: Event) -> None:
 
         self._start_observability_span(str(self._id))
         if hook_config is not None:
-            unsupported = (
-                HookEventType.PRE_TOOL_USE,
-                HookEventType.POST_TOOL_USE,
-                HookEventType.USER_PROMPT_SUBMIT,
-                HookEventType.STOP,
-            )
-            if any(hook_config.has_hooks_for_event(t) for t in unsupported):
-                logger.warning(
-                    "RemoteConversation only supports SessionStart/SessionEnd hooks; "
-                    "other hook types will not be enforced."
-                )
+            # Server-side hooks (PreToolUse, PostToolUse, UserPromptSubmit, Stop)
+            # are handled by the server - we send hook_config in the payload.
+            # Client-side hooks (SessionStart, SessionEnd) are handled locally here.
             hook_manager = HookManager(
                 config=hook_config,
                 working_dir=os.getcwd(),

openhands-sdk/openhands/sdk/conversation/state.py

@@ -17,6 +17,7 @@
 from openhands.sdk.event import ActionEvent, ObservationEvent, UserRejectObservation
 from openhands.sdk.event.base import Event
 from openhands.sdk.event.types import EventID
+from openhands.sdk.hooks import HookConfig
 from openhands.sdk.io import FileStore, InMemoryFileStore, LocalFileStore
 from openhands.sdk.logger import get_logger
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
@@ -164,6 +165,17 @@ class ConversationState(OpenHandsModel):
         "See https://docs.openhands.dev/sdk/guides/convo-persistence#how-state-persistence-works",
     )
 
+    # Hook configuration for the conversation
+    hook_config: HookConfig | None = Field(
+        default=None,
+        description=(
+            "Hook configuration for this conversation. Includes definitions for "
+            "PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, "
+            "and Stop hooks. When set, these hooks are executed at the appropriate "
+            "points during conversation execution."
+        ),
+    )
+
     # ===== Private attrs (NOT Fields) =====
     _fs: FileStore = PrivateAttr()  # filestore for persistence
     _events: EventLog = PrivateAttr()  # now the storage for events

openhands-sdk/openhands/sdk/event/__init__.py

@@ -6,6 +6,7 @@
     CondensationSummaryEvent,
 )
 from openhands.sdk.event.conversation_state import ConversationStateUpdateEvent
+from openhands.sdk.event.hook_execution import HookExecutionEvent
 from openhands.sdk.event.llm_completion_log import LLMCompletionLogEvent
 from openhands.sdk.event.llm_convertible import (
     ActionEvent,
@@ -40,7 +41,19 @@
     "CondensationRequest",
     "CondensationSummaryEvent",
     "ConversationStateUpdateEvent",
+    "HookExecutionEvent",
     "LLMCompletionLogEvent",
     "EventID",
     "ToolCallID",
 ]
+
+
+# Rebuild SystemPromptEvent model to resolve forward reference to HookConfig
+# This must be done after all imports are complete to avoid circular import
+def _rebuild_models() -> None:
+    from openhands.sdk.hooks import HookConfig
+
+    SystemPromptEvent.model_rebuild(_types_namespace={"HookConfig": HookConfig})
+
+
+_rebuild_models()

openhands-sdk/openhands/sdk/event/hook_execution.py

@@ -0,0 +1,129 @@
+"""Hook execution event for observability into hook execution."""
+
+from typing import Any, Literal
+
+from pydantic import Field
+from rich.text import Text
+
+from openhands.sdk.event.base import Event
+from openhands.sdk.event.types import SourceType
+
+
+HookEventType = Literal[
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+]
+
+
+class HookExecutionEvent(Event):
+    """Event emitted when a hook is executed.
+
+    This event provides observability into hook execution, including:
+    - Which hook type was triggered
+    - The command that was run
+    - The result (success/blocked/error)
+    - Any output from the hook
+
+    This allows clients to track hook execution via the event stream.
+    """
+
+    source: SourceType = Field(
+        default="hook", description="Source is always 'hook' for hook execution events"
+    )
+
+    # Hook identification
+    hook_event_type: HookEventType = Field(
+        ..., description="The type of hook event that triggered this execution"
+    )
+    hook_command: str = Field(..., description="The hook command that was executed")
+    tool_name: str | None = Field(
+        default=None,
+        description="Tool name for PreToolUse/PostToolUse hooks",
+    )
+
+    # Execution result
+    success: bool = Field(..., description="Whether the hook executed successfully")
+    blocked: bool = Field(
+        default=False,
+        description="Whether the hook blocked the operation (exit code 2 or deny)",
+    )
+    exit_code: int = Field(..., description="Exit code from the hook command")
+
+    # Output
+    stdout: str = Field(default="", description="Standard output from the hook")
+    stderr: str = Field(default="", description="Standard error from the hook")
+    reason: str | None = Field(
+        default=None, description="Reason provided by hook (for blocking)"
+    )
+    additional_context: str | None = Field(
+        default=None,
+        description="Additional context injected by hook (e.g., for UserPromptSubmit)",
+    )
+    error: str | None = Field(
+        default=None, description="Error message if hook execution failed"
+    )
+
+    # Context
+    action_id: str | None = Field(
+        default=None,
+        description="ID of the action this hook is associated with (PreToolUse/PostToolUse)",  # noqa: E501
+    )
+    message_id: str | None = Field(
+        default=None,
+        description="ID of the message this hook is associated with (UserPromptSubmit)",
+    )
+    hook_input: dict[str, Any] | None = Field(
+        default=None,
+        description="The input data that was passed to the hook",
+    )
+
+    @property
+    def visualize(self) -> Text:
+        """Return Rich Text representation of this hook execution event."""
+        content = Text()
+        content.append("Hook: ", style="bold")
+        content.append(f"{self.hook_event_type}")
+        if self.tool_name:
+            content.append(f" ({self.tool_name})")
+        content.append("\n")
+
+        # Status
+        if self.blocked:
+            content.append("Status: ", style="bold")
+            content.append("BLOCKED", style="bold red")
+            if self.reason:
+                content.append(f" - {self.reason}")
+        elif self.success:
+            content.append("Status: ", style="bold")
+            content.append("SUCCESS", style="bold green")
+        else:
+            content.append("Status: ", style="bold")
+            content.append("FAILED", style="bold red")
+            if self.error:
+                content.append(f" - {self.error}")
+
+        content.append(f"\nExit Code: {self.exit_code}")
+
+        # Output (truncated)
+        if self.stdout:
+            output_preview = self.stdout[:200]
+            if len(self.stdout) > 200:
+                output_preview += "..."
+            content.append(f"\nOutput: {output_preview}")
+
+        if self.additional_context:
+            content.append(f"\nInjected Context: {self.additional_context[:100]}...")
+
+        return content
+
+    def __str__(self) -> str:
+        """Plain text string representation for HookExecutionEvent."""
+        status = (
+            "BLOCKED" if self.blocked else ("SUCCESS" if self.success else "FAILED")
+        )
+        tool_info = f" ({self.tool_name})" if self.tool_name else ""
+        return f"HookExecutionEvent: {self.hook_event_type}{tool_info} - {status}"