openhands-sdk 1.7.0__py3-none-any.whl → 1.7.1__py3-none-any.whl

openhands/sdk/context/skills/skill.py

@@ -40,6 +40,9 @@ class Skill(BaseModel):
     - None: Always active, for repository-specific guidelines
     - KeywordTrigger: Activated when keywords appear in user messages
     - TaskTrigger: Activated for specific tasks, may require user input
+
+    This model supports both OpenHands-specific fields and AgentSkills standard
+    fields (https://agentskills.io/specification) for cross-platform compatibility.
     """
 
     name: str
@@ -74,6 +77,65 @@ class Skill(BaseModel):
         description="Input metadata for the skill (task skills only)",
     )
 
+    # AgentSkills standard fields (https://agentskills.io/specification)
+    description: str | None = Field(
+        default=None,
+        description=(
+            "A brief description of what the skill does and when to use it. "
+            "AgentSkills standard field (max 1024 characters)."
+        ),
+    )
+    license: str | None = Field(
+        default=None,
+        description=(
+            "The license under which the skill is distributed. "
+            "AgentSkills standard field (e.g., 'Apache-2.0', 'MIT')."
+        ),
+    )
+    compatibility: str | None = Field(
+        default=None,
+        description=(
+            "Environment requirements or compatibility notes for the skill. "
+            "AgentSkills standard field (e.g., 'Requires git and docker')."
+        ),
+    )
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Arbitrary key-value metadata for the skill. "
+            "AgentSkills standard field for extensibility."
+        ),
+    )
+    allowed_tools: list[str] | None = Field(
+        default=None,
+        description=(
+            "List of pre-approved tools for this skill. "
+            "AgentSkills standard field (parsed from space-delimited string)."
+        ),
+    )
+
+    @field_validator("allowed_tools", mode="before")
+    @classmethod
+    def _parse_allowed_tools(cls, v: str | list | None) -> list[str] | None:
+        """Parse allowed_tools from space-delimited string or list."""
+        if v is None:
+            return None
+        if isinstance(v, str):
+            return v.split()
+        if isinstance(v, list):
+            return [str(t) for t in v]
+        raise SkillValidationError("allowed-tools must be a string or list")
+
+    @field_validator("metadata", mode="before")
+    @classmethod
+    def _convert_metadata_values(cls, v: dict | None) -> dict[str, str] | None:
+        """Convert metadata values to strings."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return {str(k): str(val) for k, val in v.items()}
+        raise SkillValidationError("metadata must be a dictionary")
+
     PATH_TO_THIRD_PARTY_SKILL_NAME: ClassVar[dict[str, str]] = {
         ".cursorrules": "cursorrules",
         "agents.md": "agents",
@@ -129,6 +191,9 @@ class Skill(BaseModel):
         """Load a skill from a markdown file with frontmatter.
 
         The agent's name is derived from its path relative to the skill_dir.
+
+        Supports both OpenHands-specific frontmatter fields and AgentSkills
+        standard fields (https://agentskills.io/specification).
         """
         path = Path(path) if isinstance(path, str) else path
 
@@ -162,6 +227,23 @@ class Skill(BaseModel):
         # Use name from frontmatter if provided, otherwise use derived name
         agent_name = str(metadata_dict.get("name", skill_name))
 
+        # Extract AgentSkills standard fields (Pydantic validators handle
+        # transformation). Handle "allowed-tools" to "allowed_tools" key mapping.
+        allowed_tools_value = metadata_dict.get(
+            "allowed-tools", metadata_dict.get("allowed_tools")
+        )
+        agentskills_fields = {
+            "description": metadata_dict.get("description"),
+            "license": metadata_dict.get("license"),
+            "compatibility": metadata_dict.get("compatibility"),
+            "metadata": metadata_dict.get("metadata"),
+            "allowed_tools": allowed_tools_value,
+        }
+        # Remove None values to avoid passing unnecessary kwargs
+        agentskills_fields = {
+            k: v for k, v in agentskills_fields.items() if v is not None
+        }
+
         # Get trigger keywords from metadata
         keywords = metadata_dict.get("triggers", [])
         if not isinstance(keywords, list):
@@ -188,6 +270,7 @@ class Skill(BaseModel):
                 source=str(path),
                 trigger=TaskTrigger(triggers=keywords),
                 inputs=inputs,
+                **agentskills_fields,
             )
 
         elif metadata_dict.get("triggers", None):
@@ -196,6 +279,7 @@ class Skill(BaseModel):
                 content=content,
                 source=str(path),
                 trigger=KeywordTrigger(keywords=keywords),
+                **agentskills_fields,
             )
         else:
             # No triggers, default to None (always active)
@@ -208,6 +292,7 @@ class Skill(BaseModel):
                 source=str(path),
                 trigger=None,
                 mcp_tools=mcp_tools,
+                **agentskills_fields,
             )
 
     # Field-level validation for mcp_tools

openhands/sdk/context/view.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
+from collections import defaultdict
 from collections.abc import Sequence
+from functools import cached_property
 from logging import getLogger
 from typing import overload
 
-from pydantic import BaseModel
+from pydantic import BaseModel, computed_field
 
 from openhands.sdk.event import (
     Condensation,
@@ -21,6 +25,48 @@ from openhands.sdk.event.types import ToolCallID
 logger = getLogger(__name__)
 
 
+class ActionBatch(BaseModel):
+    """Represents a batch of ActionEvents grouped by llm_response_id.
+
+    This is a utility class used to help detect and manage batches of ActionEvents
+    that share the same llm_response_id, which indicates they were generated together
+    by the LLM. This is important for ensuring atomicity when manipulating events
+    in a View, such as during condensation.
+    """
+
+    batches: dict[EventID, list[EventID]]
+    """dict mapping llm_response_id to list of ActionEvent IDs"""
+
+    action_id_to_response_id: dict[EventID, EventID]
+    """dict mapping ActionEvent ID to llm_response_id"""
+
+    action_id_to_tool_call_id: dict[EventID, ToolCallID]
+    """dict mapping ActionEvent ID to tool_call_id"""
+
+    @staticmethod
+    def from_events(
+        events: Sequence[Event],
+    ) -> ActionBatch:
+        """Build a map of llm_response_id -> list of ActionEvent IDs."""
+        batches: dict[EventID, list[EventID]] = defaultdict(list)
+        action_id_to_response_id: dict[EventID, EventID] = {}
+        action_id_to_tool_call_id: dict[EventID, ToolCallID] = {}
+
+        for event in events:
+            if isinstance(event, ActionEvent):
+                llm_response_id = event.llm_response_id
+                batches[llm_response_id].append(event.id)
+                action_id_to_response_id[event.id] = llm_response_id
+                if event.tool_call_id is not None:
+                    action_id_to_tool_call_id[event.id] = event.tool_call_id
+
+        return ActionBatch(
+            batches=batches,
+            action_id_to_response_id=action_id_to_response_id,
+            action_id_to_tool_call_id=action_id_to_tool_call_id,
+        )
+
+
 class View(BaseModel):
     """Linearly ordered view of events.
 
@@ -66,6 +112,161 @@ class View(BaseModel):
                 return event
         return None
 
+    @computed_field  # type: ignore[prop-decorator]
+    @cached_property
+    def manipulation_indices(self) -> list[int]:
+        """Return cached manipulation indices for this view's events.
+
+        These indices represent boundaries between atomic units where events can be
+        safely manipulated (inserted or forgotten). An atomic unit is either:
+        - A tool loop: a sequence of batches starting with thinking blocks and
+          continuing through all subsequent batches until a non-batch event
+        - A batch of ActionEvents with the same llm_response_id and their
+          corresponding ObservationBaseEvents (when not part of a tool loop)
+        - A single event that is neither an ActionEvent nor an ObservationBaseEvent
+
+        Tool loops are identified by thinking blocks and must remain atomic to
+        preserve Claude API requirements that the final assistant message must
+        have thinking blocks when thinking is enabled.
+
+        The returned indices can be used for:
+        - Inserting new events: any returned index is safe
+        - Forgetting events: select a range between two consecutive indices
+
+        Consecutive indices define atomic units that must stay together:
+        - events[indices[i]:indices[i+1]] is an atomic unit
+
+        Returns:
+            Sorted list of indices representing atomic unit boundaries. Always
+            includes 0 and len(events) as boundaries.
+        """
+        if not self.events:
+            return [0]
+
+        # Build mapping of llm_response_id -> list of event indices
+        batches: dict[EventID, list[int]] = {}
+        for idx, event in enumerate(self.events):
+            if isinstance(event, ActionEvent):
+                llm_response_id = event.llm_response_id
+                if llm_response_id not in batches:
+                    batches[llm_response_id] = []
+                batches[llm_response_id].append(idx)
+
+        # Build mapping of tool_call_id -> observation indices
+        observation_indices: dict[ToolCallID, int] = {}
+        for idx, event in enumerate(self.events):
+            if (
+                isinstance(event, ObservationBaseEvent)
+                and event.tool_call_id is not None
+            ):
+                observation_indices[event.tool_call_id] = idx
+
+        # For each batch, find the range of indices that includes all actions
+        # and their corresponding observations, and track if batch has thinking blocks
+        batch_ranges: list[tuple[int, int, bool]] = []
+        for llm_response_id, action_indices in batches.items():
+            min_idx = min(action_indices)
+            max_idx = max(action_indices)
+
+            # Check if this batch has thinking blocks (only first action has them)
+            first_action = self.events[min_idx]
+            has_thinking = (
+                isinstance(first_action, ActionEvent)
+                and len(first_action.thinking_blocks) > 0
+            )
+
+            # Extend the range to include all corresponding observations
+            for action_idx in action_indices:
+                action_event = self.events[action_idx]
+                if (
+                    isinstance(action_event, ActionEvent)
+                    and action_event.tool_call_id is not None
+                ):
+                    if action_event.tool_call_id in observation_indices:
+                        obs_idx = observation_indices[action_event.tool_call_id]
+                        max_idx = max(max_idx, obs_idx)
+
+            batch_ranges.append((min_idx, max_idx, has_thinking))
+
+        # Sort batch ranges by start index for tool loop detection
+        batch_ranges.sort(key=lambda x: x[0])
+
+        # Identify tool loops: A tool loop starts with a batch that has thinking
+        # blocks and continues through all subsequent batches until we hit a
+        # non-ActionEvent/ObservationEvent (like a user MessageEvent).
+        tool_loop_ranges: list[tuple[int, int]] = []
+        if batch_ranges:
+            i = 0
+            while i < len(batch_ranges):
+                min_idx, max_idx, has_thinking = batch_ranges[i]
+
+                # If this batch has thinking blocks, start a tool loop
+                if has_thinking:
+                    loop_start = min_idx
+                    loop_end = max_idx
+
+                    # Continue through ALL subsequent batches until we hit
+                    # a non-batch event
+                    j = i + 1
+                    while j < len(batch_ranges):
+                        next_min, next_max, _ = batch_ranges[j]
+
+                        # Check if there's a non-batch event between current
+                        # and next batch
+                        has_non_batch_between = False
+                        for k in range(loop_end + 1, next_min):
+                            event = self.events[k]
+                            if not isinstance(
+                                event, (ActionEvent, ObservationBaseEvent)
+                            ):
+                                has_non_batch_between = True
+                                break
+
+                        if has_non_batch_between:
+                            # Tool loop ends before this non-batch event
+                            break
+
+                        # Include this batch in the tool loop
+                        loop_end = max(loop_end, next_max)
+                        j += 1
+
+                    tool_loop_ranges.append((loop_start, loop_end))
+                    i = j
+                else:
+                    i += 1
+
+        # Merge batch ranges that are part of tool loops
+        # Create a mapping of batch index ranges to whether they're in a tool loop
+        merged_ranges: list[tuple[int, int]] = []
+
+        if tool_loop_ranges:
+            # Add tool loop ranges as atomic units
+            merged_ranges.extend(tool_loop_ranges)
+
+            # Add non-tool-loop batch ranges
+            tool_loop_indices = set()
+            for loop_start, loop_end in tool_loop_ranges:
+                tool_loop_indices.update(range(loop_start, loop_end + 1))
+
+            for min_idx, max_idx, has_thinking in batch_ranges:
+                # Only add if not already covered by a tool loop
+                if min_idx not in tool_loop_indices:
+                    merged_ranges.append((min_idx, max_idx))
+        else:
+            # No tool loops, just use regular batch ranges
+            merged_ranges = [(min_idx, max_idx) for min_idx, max_idx, _ in batch_ranges]
+
+        # Start with all possible indices (subtractive approach)
+        result_indices = set(range(len(self.events) + 1))
+
+        # Remove indices inside merged ranges (keep only boundaries)
+        for min_idx, max_idx in merged_ranges:
+            # Remove interior indices, keeping min_idx and max_idx+1 as boundaries
+            for idx in range(min_idx + 1, max_idx + 1):
+                result_indices.discard(idx)
+
+        return sorted(result_indices)
+
     # To preserve list-like indexing, we ideally support slicing and position-based
     # indexing. The only challenge with that is switching the return type based on the
     # input type -- we can mark the different signatures for MyPy with `@overload`
@@ -88,35 +289,6 @@ class View(BaseModel):
         else:
             raise ValueError(f"Invalid key type: {type(key)}")
 
-    @staticmethod
-    def _build_action_batches(
-        events: Sequence[Event],
-    ) -> tuple[
-        dict[EventID, list[EventID]], dict[EventID, EventID], dict[EventID, ToolCallID]
-    ]:
-        """Build a map of llm_response_id -> list of ActionEvent IDs.
-
-        Returns:
-            A tuple of:
-            - batches: dict mapping llm_response_id to list of ActionEvent IDs
-            - action_id_to_response_id: dict mapping ActionEvent ID to llm_response_id
-            - action_id_to_tool_call_id: dict mapping ActionEvent ID to tool_call_id
-        """
-        batches: dict[EventID, list[EventID]] = {}
-        action_id_to_response_id: dict[EventID, EventID] = {}
-        action_id_to_tool_call_id: dict[EventID, ToolCallID] = {}
-
-        for event in events:
-            if isinstance(event, ActionEvent):
-                llm_response_id = event.llm_response_id
-                if llm_response_id not in batches:
-                    batches[llm_response_id] = []
-                batches[llm_response_id].append(event.id)
-                action_id_to_response_id[event.id] = llm_response_id
-                action_id_to_tool_call_id[event.id] = event.tool_call_id
-
-        return batches, action_id_to_response_id, action_id_to_tool_call_id
-
     @staticmethod
     def _enforce_batch_atomicity(
         events: Sequence[Event],
@@ -136,14 +308,14 @@ class View(BaseModel):
             Updated set of event IDs that should be removed (including all
             ActionEvents in batches where any ActionEvent was removed)
         """
-        batches, action_id_to_response_id, _ = View._build_action_batches(events)
+        action_batch = ActionBatch.from_events(events)
 
-        if not batches:
+        if not action_batch.batches:
             return removed_event_ids
 
         updated_removed_ids = set(removed_event_ids)
 
-        for llm_response_id, batch_event_ids in batches.items():
+        for llm_response_id, batch_event_ids in action_batch.batches.items():
             # Check if any ActionEvent in this batch is being removed
             if any(event_id in removed_event_ids for event_id in batch_event_ids):
                 # If so, remove all ActionEvents in this batch
@@ -171,7 +343,7 @@ class View(BaseModel):
         observation_tool_call_ids = View._get_observation_tool_call_ids(events)
 
         # Build batch info for batch atomicity enforcement
-        _, _, action_id_to_tool_call_id = View._build_action_batches(events)
+        action_batch = ActionBatch.from_events(events)
 
         # First pass: identify which events would NOT be kept based on matching
         removed_event_ids: set[EventID] = set()
@@ -190,8 +362,10 @@ class View(BaseModel):
         # due to batch atomicity
         tool_call_ids_to_remove: set[ToolCallID] = set()
         for action_id in removed_event_ids:
-            if action_id in action_id_to_tool_call_id:
-                tool_call_ids_to_remove.add(action_id_to_tool_call_id[action_id])
+            if action_id in action_batch.action_id_to_tool_call_id:
+                tool_call_ids_to_remove.add(
+                    action_batch.action_id_to_tool_call_id[action_id]
+                )
 
         # Filter out removed events
         result = []
@@ -242,8 +416,31 @@ class View(BaseModel):
         else:
             return True
 
+    def find_next_manipulation_index(self, threshold: int, strict: bool = False) -> int:
+        """Find the smallest manipulation index greater than (or equal to) a threshold.
+
+        This is a helper method for condensation logic that needs to find safe
+        boundaries for forgetting events. Uses the cached manipulation_indices property.
+
+        Args:
+            threshold: The threshold value to compare against
+            strict: If True, finds index > threshold. If False, finds index >= threshold
+
+        Returns:
+            The smallest manipulation index that satisfies the condition, or the
+            threshold itself if no such index exists
+        """
+        for idx in self.manipulation_indices:
+            if strict:
+                if idx > threshold:
+                    return idx
+            else:
+                if idx >= threshold:
+                    return idx
+        return threshold
+
     @staticmethod
-    def from_events(events: Sequence[Event]) -> "View":
+    def from_events(events: Sequence[Event]) -> View:
         """Create a view from a list of events, respecting the semantics of any
         condensation events.
         """

openhands/sdk/conversation/conversation.py

@@ -14,6 +14,7 @@ from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
 )
+from openhands.sdk.hooks import HookConfig
 from openhands.sdk.logger import get_logger
 from openhands.sdk.secret import SecretValue
 from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
@@ -56,6 +57,7 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
@@ -76,6 +78,7 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
@@ -96,6 +99,7 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
@@ -123,6 +127,7 @@ class Conversation:
                 conversation_id=conversation_id,
                 callbacks=callbacks,
                 token_callbacks=token_callbacks,
+                hook_config=hook_config,
                 max_iteration_per_run=max_iteration_per_run,
                 stuck_detection=stuck_detection,
                 stuck_detection_thresholds=stuck_detection_thresholds,
@@ -136,6 +141,7 @@ class Conversation:
             conversation_id=conversation_id,
             callbacks=callbacks,
             token_callbacks=token_callbacks,
+            hook_config=hook_config,
             max_iteration_per_run=max_iteration_per_run,
             stuck_detection=stuck_detection,
             stuck_detection_thresholds=stuck_detection_thresholds,

openhands/sdk/conversation/impl/local_conversation.py

@@ -31,6 +31,7 @@ from openhands.sdk.event import (
     UserRejectObservation,
 )
 from openhands.sdk.event.conversation_error import ConversationErrorEvent
+from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_callback
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.llm.llm_registry import LLMRegistry
 from openhands.sdk.logger import get_logger
@@ -56,6 +57,7 @@ class LocalConversation(BaseConversation):
     _stuck_detector: StuckDetector | None
     llm_registry: LLMRegistry
     _cleanup_initiated: bool
+    _hook_processor: HookEventProcessor | None
 
     def __init__(
         self,
@@ -65,6 +67,7 @@ class LocalConversation(BaseConversation):
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
         stuck_detection_thresholds: (
@@ -89,6 +92,7 @@ class LocalConversation(BaseConversation):
                       suffix their persistent filestore with this ID.
             callbacks: Optional list of callback functions to handle events
             token_callbacks: Optional list of callbacks invoked for streaming deltas
+            hook_config: Optional hook configuration to auto-wire session hooks
             max_iteration_per_run: Maximum number of iterations per run
             visualizer: Visualization configuration. Can be:
                        - ConversationVisualizerBase subclass: Class to instantiate
@@ -136,7 +140,20 @@ class LocalConversation(BaseConversation):
         def _default_callback(e):
             self._state.events.append(e)
 
-        composed_list = (callbacks if callbacks else []) + [_default_callback]
+        self._hook_processor = None
+        hook_callback = None
+        if hook_config is not None:
+            self._hook_processor, hook_callback = create_hook_callback(
+                hook_config=hook_config,
+                working_dir=str(self.workspace.working_dir),
+                session_id=str(desired_id),
+            )
+
+        callback_list = list(callbacks) if callbacks else []
+        if hook_callback is not None:
+            callback_list.insert(0, hook_callback)
+
+        composed_list = callback_list + [_default_callback]
         # Handle visualization configuration
         if isinstance(visualizer, ConversationVisualizerBase):
             # Use custom visualizer instance
@@ -183,6 +200,10 @@ class LocalConversation(BaseConversation):
         else:
             self._stuck_detector = None
 
+        if self._hook_processor is not None:
+            self._hook_processor.set_conversation_state(self._state)
+            self._hook_processor.run_session_start()
+
         with self._state:
             self.agent.init_state(self._state, on_event=self._on_event)
 
@@ -458,16 +479,25 @@ class LocalConversation(BaseConversation):
 
     def close(self) -> None:
         """Close the conversation and clean up all tool executors."""
-        if self._cleanup_initiated:
+        # Use getattr for safety - object may be partially constructed
+        if getattr(self, "_cleanup_initiated", False):
             return
         self._cleanup_initiated = True
         logger.debug("Closing conversation and cleaning up tool executors")
+        hook_processor = getattr(self, "_hook_processor", None)
+        if hook_processor is not None:
+            hook_processor.run_session_end()
         try:
             self._end_observability_span()
         except AttributeError:
             # Object may be partially constructed; span fields may be missing.
             pass
-        for tool in self.agent.tools_map.values():
+        try:
+            tools_map = self.agent.tools_map
+        except (AttributeError, RuntimeError):
+            # Agent not initialized or partially constructed
+            return
+        for tool in tools_map.values():
             try:
                 executable_tool = tool.as_executable()
                 executable_tool.executor.close()

openhands/sdk/conversation/impl/remote_conversation.py

@@ -33,6 +33,12 @@ from openhands.sdk.event.conversation_state import (
     ConversationStateUpdateEvent,
 )
 from openhands.sdk.event.llm_completion_log import LLMCompletionLogEvent
+from openhands.sdk.hooks import (
+    HookConfig,
+    HookEventProcessor,
+    HookEventType,
+    HookManager,
+)
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.logger import DEBUG, get_logger
 from openhands.sdk.observability.laminar import observe
@@ -430,6 +436,8 @@ class RemoteConversation(BaseConversation):
     max_iteration_per_run: int
     workspace: RemoteWorkspace
     _client: httpx.Client
+    _hook_processor: HookEventProcessor | None
+    _cleanup_initiated: bool
 
     def __init__(
         self,
@@ -442,6 +450,7 @@ class RemoteConversation(BaseConversation):
         stuck_detection_thresholds: (
             StuckDetectionThresholds | Mapping[str, int] | None
         ) = None,
+        hook_config: HookConfig | None = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -462,6 +471,7 @@ class RemoteConversation(BaseConversation):
                       a dict with keys: 'action_observation', 'action_error',
                       'monologue', 'alternating_pattern'. Values are integers
                       representing the number of repetitions before triggering.
+            hook_config: Optional hook configuration for session hooks
             visualizer: Visualization configuration. Can be:
                        - ConversationVisualizerBase subclass: Class to instantiate
                          (default: ConversationVisualizer)
@@ -475,6 +485,8 @@ class RemoteConversation(BaseConversation):
         self.max_iteration_per_run = max_iteration_per_run
         self.workspace = workspace
         self._client = workspace.client
+        self._hook_processor = None
+        self._cleanup_initiated = False
 
         if conversation_id is None:
             payload = {
@@ -570,6 +582,25 @@ class RemoteConversation(BaseConversation):
             self.update_secrets(secret_values)
 
         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."
+                )
+            hook_manager = HookManager(
+                config=hook_config,
+                working_dir=os.getcwd(),
+                session_id=str(self._id),
+            )
+            self._hook_processor = HookEventProcessor(hook_manager=hook_manager)
+            self._hook_processor.run_session_start()
 
     def _create_llm_completion_log_callback(self) -> ConversationCallbackType:
         """Create a callback that writes LLM completion logs to client filesystem."""
@@ -866,6 +897,11 @@ class RemoteConversation(BaseConversation):
         The workspace owns the client and will close it during its own cleanup.
         Closing it here would prevent the workspace from making cleanup API calls.
         """
+        if self._cleanup_initiated:
+            return
+        self._cleanup_initiated = True
+        if self._hook_processor is not None:
+            self._hook_processor.run_session_end()
         try:
             # Stop WebSocket client if it exists
             if self._ws_client: