tests(hooks): add comprehensive tests for bulk operations API

why: Ensure bulk operations work correctly across all input types
what:
- Add TestBulkOperationsAPI class with 15 tests
- Test get_hook_indices with empty, sequential, and sparse indices
- Test get_hook_values with empty and populated hooks
- Test set_hooks_bulk with dict, list, and SparseArray inputs
- Test clear_hook and append_hook behavior
- Test method chaining support

Author: tony

tests/test_hooks.py

@@ -525,3 +525,277 @@ def test_new_hooks_version_gated(server: Server, test_case: HookTestCase) -> Non
 
     # Cleanup
     session.unset_hook(f"{test_case.hook}[0]")
+
+
+# =============================================================================
+# Bulk Operations API Tests
+# =============================================================================
+
+
+class TestBulkOperationsAPI:
+    """Tests for hook bulk operations API."""
+
+    def test_get_hook_indices_empty(self, server: Server) -> None:
+        """Test get_hook_indices returns empty list when no hooks set."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == []
+
+    def test_get_hook_indices_sequential(self, server: Server) -> None:
+        """Test get_hook_indices with sequential indices."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set hooks at indices 0, 1, 2
+        session.set_hook("session-renamed[0]", "display-message 'hook 0'")
+        session.set_hook("session-renamed[1]", "display-message 'hook 1'")
+        session.set_hook("session-renamed[2]", "display-message 'hook 2'")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 1, 2]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_get_hook_indices_sparse(self, server: Server) -> None:
+        """Test get_hook_indices with sparse (non-sequential) indices."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set hooks at non-sequential indices
+        session.set_hook("session-renamed[0]", "display-message 'hook 0'")
+        session.set_hook("session-renamed[5]", "display-message 'hook 5'")
+        session.set_hook("session-renamed[10]", "display-message 'hook 10'")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 5, 10]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_get_hook_values_empty(self, server: Server) -> None:
+        """Test get_hook_values returns empty SparseArray when no hooks set."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        values = session.get_hook_values("session-renamed")
+        assert isinstance(values, SparseArray)
+        assert len(values) == 0
+        assert values.as_list() == []
+
+    def test_get_hook_values(self, server: Server) -> None:
+        """Test get_hook_values returns SparseArray with correct values."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set hooks
+        session.set_hook("session-renamed[0]", "display-message 'hook 0'")
+        session.set_hook("session-renamed[5]", "display-message 'hook 5'")
+
+        values = session.get_hook_values("session-renamed")
+        assert isinstance(values, SparseArray)
+        assert 0 in values
+        assert 5 in values
+        assert 3 not in values
+        assert "display-message" in values[0]
+        assert "display-message" in values[5]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_get_hook_values_iter(self, server: Server) -> None:
+        """Test iterating over hook values in sorted order."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set hooks at sparse indices
+        session.set_hook("session-renamed[5]", "display-message 'fifth'")
+        session.set_hook("session-renamed[0]", "display-message 'zeroth'")
+        session.set_hook("session-renamed[2]", "display-message 'second'")
+
+        values = session.get_hook_values("session-renamed")
+        value_list = list(values.iter_values())
+
+        # Values should be in sorted index order
+        assert len(value_list) == 3
+        assert "zeroth" in value_list[0]
+        assert "second" in value_list[1]
+        assert "fifth" in value_list[2]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_set_hooks_bulk_with_dict(self, server: Server) -> None:
+        """Test set_hooks_bulk with explicit index dict."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        session.set_hooks_bulk(
+            "session-renamed",
+            {
+                0: "display-message 'hook 0'",
+                1: "display-message 'hook 1'",
+                5: "display-message 'hook 5'",
+            },
+        )
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 1, 5]
+
+        values = session.get_hook_values("session-renamed")
+        assert "hook 0" in values[0]
+        assert "hook 1" in values[1]
+        assert "hook 5" in values[5]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_set_hooks_bulk_with_list(self, server: Server) -> None:
+        """Test set_hooks_bulk with list (sequential indices)."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        session.set_hooks_bulk(
+            "session-renamed",
+            [
+                "display-message 'hook 0'",
+                "display-message 'hook 1'",
+                "display-message 'hook 2'",
+            ],
+        )
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 1, 2]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_set_hooks_bulk_with_sparse_array(self, server: Server) -> None:
+        """Test set_hooks_bulk with SparseArray."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        sparse: SparseArray[str] = SparseArray()
+        sparse.add(0, "display-message 'from sparse 0'")
+        sparse.add(10, "display-message 'from sparse 10'")
+
+        session.set_hooks_bulk("session-renamed", sparse)
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 10]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_set_hooks_bulk_clear_existing(self, server: Server) -> None:
+        """Test set_hooks_bulk with clear_existing=True."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set initial hooks
+        session.set_hooks_bulk(
+            "session-renamed",
+            {0: "display-message 'old 0'", 1: "display-message 'old 1'"},
+        )
+
+        # Replace with new hooks
+        session.set_hooks_bulk(
+            "session-renamed",
+            {0: "display-message 'new 0'"},
+            clear_existing=True,
+        )
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0]
+
+        values = session.get_hook_values("session-renamed")
+        assert "new 0" in values[0]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_clear_hook(self, server: Server) -> None:
+        """Test clear_hook removes all indexed values."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set multiple hooks
+        session.set_hooks_bulk(
+            "session-renamed",
+            {0: "display-message 'hook 0'", 5: "display-message 'hook 5'"},
+        )
+
+        # Verify they exist
+        assert session.get_hook_indices("session-renamed") == [0, 5]
+
+        # Clear all
+        session.clear_hook("session-renamed")
+
+        # Verify cleared
+        assert session.get_hook_indices("session-renamed") == []
+
+    def test_append_hook_to_empty(self, server: Server) -> None:
+        """Test append_hook when no hooks exist (starts at index 0)."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        session.append_hook("session-renamed", "display-message 'appended'")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0]
+
+        values = session.get_hook_values("session-renamed")
+        assert "appended" in values[0]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_append_hook_sequential(self, server: Server) -> None:
+        """Test append_hook adds at next sequential index."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set initial hook
+        session.set_hook("session-renamed[0]", "display-message 'initial'")
+
+        # Append
+        session.append_hook("session-renamed", "display-message 'appended'")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 1]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_append_hook_after_sparse(self, server: Server) -> None:
+        """Test append_hook adds at max+1 even with sparse indices."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Set hooks at sparse indices
+        session.set_hook("session-renamed[0]", "display-message 'at 0'")
+        session.set_hook("session-renamed[10]", "display-message 'at 10'")
+
+        # Append should be at index 11
+        session.append_hook("session-renamed", "display-message 'appended'")
+
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 10, 11]
+
+        values = session.get_hook_values("session-renamed")
+        assert "appended" in values[11]
+
+        # Cleanup
+        session.clear_hook("session-renamed")
+
+    def test_method_chaining(self, server: Server) -> None:
+        """Test that bulk operations support method chaining."""
+        session = server.new_session(session_name="test_bulk_ops")
+
+        # Chain operations
+        result = (
+            session.set_hooks_bulk(
+                "session-renamed",
+                ["display-message 'hook 0'"],
+            )
+            .append_hook("session-renamed", "display-message 'hook 1'")
+            .append_hook("session-renamed", "display-message 'hook 2'")
+        )
+
+        # Should return the session
+        assert result is session
+
+        # Verify all hooks set
+        indices = session.get_hook_indices("session-renamed")
+        assert indices == [0, 1, 2]
+
+        # Cleanup
+        session.clear_hook("session-renamed")