openbox-temporal-sdk-python 1.2.1__tar.gz → 1.3.0__tar.gz

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to OpenBox SDK for Temporal Workflows.
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-07-21
+
+### Added
+
+- **Retryable BLOCK workflow restart:** A governance response carrying `BLOCK` with a valid `retry_plan` (containing `new_input`) now triggers a Continue-As-New restart of the workflow using the replacement input. The restart is event-agnostic (supports WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted, Handoff, hook evaluations, and approval polling) and is bounded by the `max_retryable_block_restarts` configuration (default: 3, minimum: 1). When the bound is exceeded, the workflow fails with a non-retryable `GovernanceRetryLimitExceeded` error. The restart count is tracked across the entire workflow chain via a durable memo counter. Plain BLOCK (without a retry plan), HALT, expired approvals, and malformed plans preserve existing behavior and do not restart.
+
+- **Workflow input capture in `WorkflowStarted`:** The `WorkflowStarted` governance event now carries the Temporal workflow arguments in the `activity_input` field, so OpenBox stores and displays workflow input the same way as activity input. The outer argument list is preserved verbatim (`workflow(a, b)` → `[a, b]`; a single list argument stays nested as `[[...]]`; no arguments → `[]`). Because this changes the `send_governance_event` activity input, it is version-gated by a dedicated patch marker (`openbox-workflow-start-input-v1`): new workflow histories include `activity_input`, while histories created before this change replay their original payload unchanged.
+
+### Changed
+
+- **`openbox-sdk-python` dependency raised to `>=1.1.0`, installed from PyPI.** The retryable-BLOCK restart requires `handle_retryable_block` from base SDK 1.1.0; now that 1.1.0 is published, the dependency resolves from PyPI and the temporary local editable source is removed.
+
 ## [1.2.1] - 2026-07-21
 
 ### Changed

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-temporal-sdk-python
-Version: 1.2.1
+Version: 1.3.0
 Summary: OpenBox SDK - Governance and observability for Temporal workflows
 Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
 Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
@@ -24,7 +24,7 @@ Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: httpx<1,>=0.28.0
 Requires-Dist: mysql-connector-python>=8.0.0
-Requires-Dist: openbox-sdk-python>=1.0.1
+Requires-Dist: openbox-sdk-python>=1.1.0
 Requires-Dist: opentelemetry-api<1.40.0,>=1.38.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg<0.61b0,>=0.59b0
 Requires-Dist: opentelemetry-instrumentation-httpx<0.61b0,>=0.59b0
@@ -227,9 +227,11 @@ OpenBox Core returns a verdict indicating what action the SDK should take.
 | `ALLOW` | Continue execution normally |
 | `CONSTRAIN` | Log constraints, continue |
 | `REQUIRE_APPROVAL` | Pause, poll for human approval |
-| `BLOCK` | Raise error, stop activity |
+| `BLOCK` | Raise error, stop activity; if carrying a `retry_plan`, restart the workflow with replacement input via Continue-As-New (see "Retryable BLOCK" below) |
 | `HALT` | Raise error, terminate workflow |
 
+**Retryable BLOCK:** When a `BLOCK` verdict includes a `retry_plan` with `new_input`, the SDK restarts the workflow using the corrected input instead of failing permanently. The restart chain is bounded by `max_retryable_block_restarts` (default: 3). See [Retryable BLOCK Restart Configuration](./docs/configuration.md#retryable-block-restart) for semantics and **critical idempotency requirements**.
+
 **v1.0 Backward Compatibility:**
 - `"continue"` → `ALLOW`
 - `"stop"` → `HALT`

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/README.md

@@ -178,9 +178,11 @@ OpenBox Core returns a verdict indicating what action the SDK should take.
 | `ALLOW` | Continue execution normally |
 | `CONSTRAIN` | Log constraints, continue |
 | `REQUIRE_APPROVAL` | Pause, poll for human approval |
-| `BLOCK` | Raise error, stop activity |
+| `BLOCK` | Raise error, stop activity; if carrying a `retry_plan`, restart the workflow with replacement input via Continue-As-New (see "Retryable BLOCK" below) |
 | `HALT` | Raise error, terminate workflow |
 
+**Retryable BLOCK:** When a `BLOCK` verdict includes a `retry_plan` with `new_input`, the SDK restarts the workflow using the corrected input instead of failing permanently. The restart chain is bounded by `max_retryable_block_restarts` (default: 3). See [Retryable BLOCK Restart Configuration](./docs/configuration.md#retryable-block-restart) for semantics and **critical idempotency requirements**.
+
 **v1.0 Backward Compatibility:**
 - `"continue"` → `ALLOW`
 - `"stop"` → `HALT`

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/docs/configuration.md

@@ -31,6 +31,55 @@
 | `hitl_enabled` | `bool` | `True` | Enable approval polling for `REQUIRE_APPROVAL` |
 | `hitl_poll_interval_ms` | `int` | `5000` | Polling interval in milliseconds for approval status |
 
+## Retryable BLOCK Restart
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `max_retryable_block_restarts` | `int` | `3` | Maximum Continue-As-New restarts triggered by a BLOCK with `retry_plan`. Minimum value: `1`. Applies uniformly across all governance event origins. When the count would exceed this limit, the workflow fails with a non-retryable `GovernanceRetryLimitExceeded` error. |
+
+### Semantics
+
+A governance response carrying `BLOCK` with a valid `retry_plan` (containing `new_input`) will:
+
+1. **Stop the current execution path** with a non-retryable error signal
+2. **Not retry** the blocked activity with the same input (Temporal activity retry is bypassed)
+3. **Restart the workflow via Continue-As-New** using `retry_plan.new_input` as replacement input
+   - If `new_input` is `null`, all arguments of the current run are reused exactly
+   - If `new_input` is a non-null value, it is passed as one workflow argument
+4. **Keep the same Workflow ID** — the previous run closes as `ContinuedAsNew`; a new Run ID is issued for the restarted execution
+5. **Track restarts across the chain** — a global counter (per workflow ID) increments with each restart and is bounded by `max_retryable_block_restarts` to prevent infinite loops
+
+This behavior is **event-agnostic**. The following governance event types all support retryable BLOCK:
+
+- `WorkflowStarted`
+- `WorkflowCompleted`
+- `WorkflowFailed`
+- `SignalReceived`
+- `ActivityStarted`
+- `ActivityCompleted`
+- `Handoff`
+- Started and completed hooks
+- Approval polling responses
+
+**Origins that do NOT restart:** `HALT`, expired approvals, malformed plans, and plain BLOCK (without a valid `retry_plan`) use existing behavior.
+
+### Critical: Idempotency and Side Effects
+
+**This is the most important user-facing hazard.** A retry plan may be produced *after* side effects have already occurred:
+
+- A policy may return a retry plan in response to `ActivityCompleted` — after your activity already ran and may have modified external state
+- A completed hook may return a retry plan — after the operation has occurred
+- `WorkflowCompleted` or `WorkflowFailed` may return a retry plan — after your workflow has executed and potentially caused side effects
+
+**You are responsible for ensuring safety:**
+
+- **Activities must remain idempotent.** If an activity is executed, rolls back or completes, and then the workflow restarts with corrected input, the activity must be safe to re-execute (or be designed to avoid re-execution for the same business key).
+- **External writes should use stable business idempotency keys**, not the Temporal Run ID (which changes across Continue-As-New). For example, if writing to an external system, use your application's stable resource identifier, not `workflow.get_info().run_id`.
+- **Policy authors and governance integrators own emitting safe replacement input.** The SDK does not validate that `new_input` is safe; it assumes the governance policy has vetted the input and the consequences of re-execution.
+- **The SDK adds no source-specific restrictions.** You have full control and full responsibility.
+
+Log any external state changes with identifiers your team can use to trace and reconcile retries. Monitor governance restart counts to detect policy bugs that cause repeated retries.
+
 ## Identity & Signing (AIP DID)
 
 When provided, every request to OpenBox Core is signed locally with Ed25519 and

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/docs/system-architecture.md

@@ -289,32 +289,17 @@ OpenBoxError (base)
 
 #### TemporalGovernanceState
 
-**Responsibility:** Hold the small amount of Temporal semantics that must survive past a base-SDK hook callback — signal verdicts, HITL pending markers, and the completed-hook stop bridge. Workflow-safe, thread-safe, and shared by both interceptors.
+**Responsibility:** Hold the small amount of Temporal semantics that must survive past a base-SDK hook callback — signal verdicts, HITL pending markers, completed-hook stop bridge, and retryable-BLOCK requests. Workflow-safe, thread-safe, and shared by both interceptors.
 
 The base SDK (`openbox_core`) owns hook context, hook payload building, hook evaluation, and the within-activity abort short-circuit (its `ContextStore`). This object holds only the effects the base runtime cannot express itself. All keys are **run-scoped**: state from a prior run with the same `workflow_id` is ignored and cleared.
 
-**Methods:**
-```python
-class TemporalGovernanceState:
-    # Signal verdicts (workflow interceptor → next activity)
-    def set_signal_verdict(self, workflow_id, run_id, verdict, reason=None) -> None
-    def get_signal_verdict(self, workflow_id, run_id) -> Optional[(Verdict, reason)]  # clears stale run
-    def clear_signal_verdict(self, workflow_id) -> None
-
-    # HITL pending-approval markers
-    def mark_pending_approval(self, workflow_id, run_id, activity_id) -> None
-    def has_pending_approval(self, workflow_id, run_id, activity_id) -> bool
-    def clear_pending_approval(self, workflow_id, run_id, activity_id) -> None
+**Code Location:** `openbox/governance_state.py`
 
-    # Completed-hook stop bridge (adapter → activity interceptor)
-    def record_completed_stop(self, workflow_id, run_id, activity_id, verdict, reason=None) -> None
-    def take_completed_stop(self, workflow_id, run_id, activity_id) -> Optional[(Verdict, reason)]
+**Retryable BLOCK Restart Bridge:** The workflow interceptor receives retryable-BLOCK requests from governance responses (activity results, signals, hooks, approval polls) and submits them to a run-local `RetryableBlockCoordinator`. The coordinator stores the first request (first-wins semantics); the inbound workflow boundary later reads it, validates the restart budget (incrementing a memo counter bounded by `max_retryable_block_restarts`), and calls `continue_as_new(new_input, memo=...)` with the replacement input and updated counter.
 
-    # Cleanup
-    def cleanup_run(self, workflow_id, run_id) -> None
-```
+**Versioned Error Transport:** Activity-side retry requests use a stable, non-retryable `ApplicationError` with type `"GovernanceRetryableBlock"` carrying a versioned request envelope. The workflow boundary extracts and validates the envelope before attempting a restart. Unknown versions fail safely as plain BLOCK; Temporal-level failures (replay, malformed detail) do not trigger a Workflow Task loop.
 
-**Code Location:** `openbox/governance_state.py`
+**Replay Safety (Patch Marker `"openbox-retryable-block-v1"`):** The Continue-As-New command is protected by a Temporal patch marker so old histories (pre-feature) skip the new branch and replay unchanged. New histories take the retryable-BLOCK path deterministically.
 
 ---
 
@@ -635,6 +620,71 @@ Authorization: Bearer {api_key}
 └────────────┘          └──────────────┘   └──────────────┘
 ```
 
+### Retryable BLOCK Restart Flow
+
+```
+┌──────────────────────────────────────────┐
+│ Governance response from any event type  │
+│ (activity, signal, hook, approval, etc)  │
+└────────────┬─────────────────────────────┘
+             │
+             ▼
+┌──────────────────────────────────────────┐
+│ Base SDK handle_retryable_block() helper │
+│ (checks for valid BLOCK + retry_plan)    │
+└────────────┬─────────────────────────────┘
+             │
+      ┌──────┴──────────┐
+      │                 │
+      ▼                 ▼
+  ┌────────┐        ┌─────────────────┐
+  │No plan │        │RetryDirective   │
+  └────────┘        │(new_input)      │
+     │              └────────┬────────┘
+     ▼                       │
+Existing BLOCK/HALT    ┌─────┴────────────────┐
+behavior               │                      │
+                       ▼                      ▼
+                  Activity/hook      Workflow event/signal
+                  context            context
+                       │                      │
+                       ▼                      ▼
+              Non-retryable         Submit to run-local
+              ApplicationError      RetryableBlockCoordinator
+              (transport signal)    (first-wins)
+                       │                      │
+                       └──────┬───────────────┘
+                              │
+                              ▼
+                    Workflow inbound boundary
+                              │
+                    ┌─────────┴────────────┐
+                    │                      │
+              ┌─────▼──────┐      ┌─────────────┐
+              │Read memo   │      │Read request │
+              │counter     │      │from coord   │
+              └─────┬──────┘      └──────┬──────┘
+                    │                   │
+          ┌─────────┴───────────────────┤
+          │ Increment and validate cap  │
+          └─────────┬───────────────────┘
+                    │
+         ┌──────────┴──────────┐
+         │                     │
+    ┌────▼────┐        ┌──────▼──────┐
+    │ Over    │        │ Under limit  │
+    │ limit   │        │              │
+    └────┬────┘        └──────┬───────┘
+         │                    │
+         ▼                    ▼
+    ApplicationError   Continue-As-New
+    (GovernanceRetry   (same Workflow ID,
+    LimitExceeded)     new Run ID, fresh
+                       history)
+```
+
+**Code Location:** `openbox/workflow_interceptor.py`, `openbox/retry_coordinator.py`
+
 ### Hook-Level Governance Flow
 
 Hook detection, payload building, and evaluation are owned by the `openbox_core` base runtime. The Temporal SDK provides the activity-context bridge (`core_activity_scope`) and maps the resulting verdict onto Temporal-native effects (`TemporalFrameworkAdapter`).

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/openbox/__init__.py

@@ -6,45 +6,43 @@
 # it crashes the workflow sandbox as a circular import, lazily it recurses
 # unboundedly from build_auth_headers on every evaluate. Keep in sync with
 # pyproject.toml on release.
-__version__ = "1.2.1"
-
-from .worker import create_openbox_worker
-
-from .config import (
-    initialize,
-    get_global_config,
-    GovernanceConfig,
-)
+__version__ = "1.3.0"
 
+from .config import GovernanceConfig, get_global_config, initialize
 from .errors import (
-    OpenBoxError,
-    OpenBoxConfigError,
-    OpenBoxAuthError,
-    OpenBoxNetworkError,
-    OpenBoxInsecureURLError,
-    OpenBoxSigningError,
-    GovernanceBlockedError,
-    GovernanceHaltError,
-    GovernanceAPIError,
-    GuardrailsValidationError,
     ApprovalExpiredError,
     ApprovalRejectedError,
     ApprovalTimeoutError,
+    GovernanceAPIError,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
+    OpenBoxAuthError,
+    OpenBoxConfigError,
+    OpenBoxError,
+    OpenBoxInsecureURLError,
+    OpenBoxNetworkError,
+    OpenBoxSigningError,
     extract_governance_error,
     map_signing_error,
 )
 
-from .types import (
-    Verdict,
-    WorkflowEventType,
-    GovernanceVerdictResponse,
-    GuardrailsCheckResult,
-)
-
 # Multi-agent primitives (sandbox-safe — only imports temporalio.workflow eagerly;
 # signing/HTTP routed lazily through the governance activity).
 from .multi_agent import emit_handoff
 
+# Retryable-BLOCK restart envelope (sandbox-safe: pure stdlib + base contracts).
+from .retryable_block import (
+    GOVERNANCE_RETRYABLE_BLOCK_SCHEMA_VERSION,
+    RetryableBlockRequest,
+)
+from .types import (
+    GovernanceVerdictResponse,
+    GuardrailsCheckResult,
+    Verdict,
+    WorkflowEventType,
+)
+from .worker import create_openbox_worker
 from .workflow_interceptor import GovernanceInterceptor
 
 try:
@@ -54,11 +52,9 @@ try:
 except ImportError:
     pass  # temporalio < 1.23.0, plugin not available
 
-from .verdict_handler import enforce_verdict, VerdictEnforcementResult
-
-from .hitl import handle_approval_response, raise_approval_pending, should_skip_hitl
-
 from .client import GovernanceClient
+from .hitl import handle_approval_response, raise_approval_pending, should_skip_hitl
+from .verdict_handler import VerdictEnforcementResult, enforce_verdict
 
 # NOTE: ActivityGovernanceInterceptor is NOT imported here because it imports
 # OpenTelemetry which uses importlib_metadata -> os.stat, causing sandbox issues.
@@ -114,6 +110,8 @@ __all__ = [
     "WorkflowEventType",
     "GovernanceVerdictResponse",
     "GuardrailsCheckResult",
+    "RetryableBlockRequest",
+    "GOVERNANCE_RETRYABLE_BLOCK_SCHEMA_VERSION",
     "emit_handoff",
     "GovernanceInterceptor",
     "enforce_verdict",

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/openbox/activities.py

@@ -21,18 +21,16 @@ executes. This ensures timestamps are generated in activity context (non-determi
 code allowed) rather than workflow context (must be deterministic).
 """
 
-import httpx
 import logging
 from datetime import datetime, timezone
-from typing import Dict, Any, Optional
-
-
-from .types import rfc3339_now as _rfc3339_now
+from typing import Any, Dict, Optional
 
+import httpx
 from temporalio import activity
 from temporalio.exceptions import ApplicationError
 
-from .types import Verdict
+from .types import GovernanceVerdictResponse, Verdict
+from .types import rfc3339_now as _rfc3339_now
 
 logger = logging.getLogger(__name__)
 
@@ -201,12 +199,26 @@ class GovernanceActivities:
                     )
 
                 data = response.json()
-                verdict = Verdict.from_string(
-                    data.get("verdict") or data.get("action", "continue")
-                )
-                reason = data.get("reason")
-                policy_id = data.get("policy_id")
-                risk_score = data.get("risk_score", 0.0)
+                parsed = GovernanceVerdictResponse.from_dict(data)
+                verdict = parsed.verdict
+                reason = parsed.reason
+                policy_id = parsed.policy_id
+                risk_score = parsed.risk_score
+
+                # A BLOCK carrying a valid retry plan restarts the workflow run
+                # instead of merely failing this activity — check for it before
+                # the plain BLOCK/HALT stop handling below ever sees the verdict.
+                from .errors import GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE
+                from .retryable_block import retryable_block_request
+
+                retry_req = retryable_block_request(parsed, event_type=event_type)
+                if retry_req is not None:
+                    raise ApplicationError(
+                        "Governance requested workflow restart",
+                        retry_req.to_dict(),
+                        type=GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+                        non_retryable=True,
+                    )
 
                 if verdict.should_stop():
                     result = await _handle_stop_verdict(

{openbox_temporal_sdk_python-1.2.1 → openbox_temporal_sdk_python-1.3.0}/openbox/activity_interceptor.py

@@ -11,12 +11,11 @@ IMPORTANT: Activities CAN use datetime/time and make HTTP calls directly.
 This is different from workflow interceptors which must maintain determinism.
 """
 
-from typing import Optional, Any, List
 import dataclasses
-from dataclasses import asdict, is_dataclass, fields
-import time
 import json
-
+import time
+from dataclasses import asdict, fields, is_dataclass
+from typing import Any, List, NoReturn, Optional
 
 from .types import rfc3339_now as _rfc3339_now
 
@@ -63,27 +62,44 @@ def _update_list_items(current_list: list, new_list: list, _logger=None) -> None
             current_list[i] = new_item
 
 
+from opentelemetry import trace
 from temporalio import activity
 from temporalio.worker import (
-    Interceptor,
     ActivityInboundInterceptor,
     ExecuteActivityInput,
+    Interceptor,
 )
-from opentelemetry import trace
 
+from .activities import _terminate_workflow_for_halt
+from .client import GovernanceClient
 from .config import GovernanceConfig
 from .core_adapter import core_activity_scope, get_core_context_store
-from .governance_state import TemporalGovernanceState
-from .types import (
-    WorkflowEventType,
-    GovernanceVerdictResponse,
-    Verdict,
+from .errors import (
+    GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
 )
+from .governance_state import TemporalGovernanceState
 from .multi_agent import read_session_from_header
-from .activities import _terminate_workflow_for_halt
+from .retryable_block import RetryableBlockRequest, retryable_block_request
+from .types import GovernanceVerdictResponse, Verdict, WorkflowEventType
 from .verdict_handler import enforce_verdict
-from .errors import GovernanceBlockedError, GovernanceHaltError, GuardrailsValidationError
-from .client import GovernanceClient
+
+
+def _raise_retryable_block(req: RetryableBlockRequest) -> NoReturn:
+    """Raise the stable, versioned ``GovernanceRetryableBlock`` ApplicationError
+    for a valid retryable-BLOCK directive. Non-retryable — the workflow
+    interceptor catches this stable type and Continue-As-News with the
+    replacement input."""
+    from temporalio.exceptions import ApplicationError
+
+    raise ApplicationError(
+        "Governance requested workflow restart",
+        req.to_dict(),
+        type=GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+        non_retryable=True,
+    )
 
 
 def _serialize_value(value: Any) -> Any:
@@ -94,6 +110,12 @@ def _serialize_value(value: Any) -> Any:
         return value
     if isinstance(value, bytes):
         return _serialize_bytes(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        try:
+            return model_dump(mode="json")
+        except Exception:
+            pass
     if is_dataclass(value) and not isinstance(value, type):
         return asdict(value)
     if isinstance(value, (list, tuple)):
@@ -111,6 +133,7 @@ def _serialize_bytes(value: bytes) -> str:
         return value.decode("utf-8")
     except Exception:
         import base64
+
         return base64.b64encode(value).decode("ascii")
 
 
@@ -238,35 +261,56 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             )
         except Exception:
             # The activity (or a hook) raised, so _handle_completion is skipped. A
-            # completed-hook HALT recorded during user code is a kill-switch and
-            # must STILL reach the terminate path — failing the activity does not
-            # halt the workflow. Consume the completed-stop here too (also clears
-            # it, so it can never strand/leak on the exception path).
+            # completed-hook stop recorded during user code must still be enforced:
+            # HALT reaches the terminate path and raises GovernanceHalt, and a
+            # retryable request raises GovernanceRetryableBlock — either REPLACES
+            # the original exception (completed-hook priority HALT > retryable >
+            # original exception). A plain completed BLOCK is a no-op, so the
+            # `raise` below re-propagates the original exception unchanged. Consume
+            # the completed-stop either way (also clears it, so it can never
+            # strand/leak on the exception path).
             await self._consume_completed_halt(info)
             raise
 
         result = await self._handle_completion(
-            info, status, error, start_time, end_time,
-            activity_input, activity_output, result,
+            info,
+            status,
+            error,
+            start_time,
+            end_time,
+            activity_input,
+            activity_output,
+            result,
             session_id,
         )
 
         return result
 
     async def _consume_completed_halt(self, info) -> None:
-        """Exception-path safety net: a completed-hook HALT recorded during user
-        code must terminate the workflow even when the activity itself raised.
-        Clears the completed-stop and the base abort flag so nothing strands."""
+        """Exception-path safety net: a completed-hook stop recorded during user
+        code must still be enforced even though the activity itself raised, so
+        _handle_completion (the success path) never runs. Priority: HALT raises
+        GovernanceHalt (terminating the workflow and REPLACING the original
+        exception); a retryable request raises GovernanceRetryableBlock (also
+        replacing the original exception with the restart request); a plain
+        completed BLOCK is a no-op here, so the caller's re-raise propagates the
+        original exception unchanged. Clears the completed-stop and the base abort
+        flag so nothing strands."""
         stop = self._state.take_completed_stop(
             info.workflow_id, info.workflow_run_id, info.activity_id
         )
         get_core_context_store().clear_activity_aborted(
             info.workflow_id, info.activity_id
         )
-        if stop is not None and stop[0] is Verdict.HALT:
+        if stop is None:
+            return
+        if stop.verdict is Verdict.HALT:
             await _terminate_workflow_for_halt(
-                info.workflow_id, stop[1] or "Governance halt"
+                info.workflow_id, stop.reason or "Governance halt"
             )
+            return
+        if stop.request is not None:
+            _raise_retryable_block(stop.request)
 
     async def _check_pending_verdicts(self, info) -> None:
         """Enforce a SignalReceived BLOCK/HALT recorded for this run by the
@@ -292,6 +336,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             await _terminate_workflow_for_halt(workflow_id, reason)
         else:
             from temporalio.exceptions import ApplicationError
+
             raise ApplicationError(
                 f"Governance blocked: {reason}",
                 type="GovernanceBlock",
@@ -329,9 +374,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             info.activity_id,
         )
         if approved:
-            activity.logger.info(
-                f"Approval granted for workflow_id={info.workflow_id}"
-            )
+            activity.logger.info(f"Approval granted for workflow_id={info.workflow_id}")
             self._state.clear_pending_approval(
                 info.workflow_id, info.workflow_run_id, info.activity_id
             )
@@ -362,7 +405,21 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         self, verdict_response: GovernanceVerdictResponse, info, context: str
     ) -> None:
         """Enforce a governance verdict (HITL, BLOCK, HALT, guardrails)."""
-        from .hitl import should_skip_hitl, raise_approval_pending
+        from .hitl import raise_approval_pending, should_skip_hitl
+
+        # An exact BLOCK with a valid retry plan requests a workflow restart and
+        # takes priority over the generic BLOCK/HALT/guardrails mapping below —
+        # checked before enforce_verdict() so it is never first converted to a
+        # plain GovernanceBlockedError. These are REAL activity-lifecycle events
+        # (not hooks), so hook_trigger stays the default False.
+        event_type = (
+            WorkflowEventType.ACTIVITY_STARTED.value
+            if context == "activity_start"
+            else WorkflowEventType.ACTIVITY_COMPLETED.value
+        )
+        req = retryable_block_request(verdict_response, event_type=event_type)
+        if req is not None:
+            _raise_retryable_block(req)
 
         try:
             verdict_result = enforce_verdict(verdict_response, context)
@@ -384,6 +441,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             await _terminate_workflow_for_halt(info.workflow_id, str(e))
         except GovernanceBlockedError as e:
             from temporalio.exceptions import ApplicationError
+
             raise ApplicationError(
                 f"Governance blocked: {e.reason}",
                 type="GovernanceBlock",
@@ -391,6 +449,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             )
         except GuardrailsValidationError as e:
             from temporalio.exceptions import ApplicationError
+
             activity.logger.info(f"Guardrails validation failed: {e}")
             raise ApplicationError(
                 f"Guardrails validation failed: {e}",
@@ -510,8 +569,16 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         return result, status, error, activity_output, end_time
 
     async def _handle_completion(
-        self, info, status, error, start_time, end_time,
-        activity_input, activity_output, result, multi_agent_session_id=None,
+        self,
+        info,
+        status,
+        error,
+        start_time,
+        end_time,
+        activity_input,
+        activity_output,
+        result,
+        multi_agent_session_id=None,
     ) -> Any:
         """Send ActivityCompleted, enforce verdict, apply output redaction."""
         store = get_core_context_store()
@@ -525,10 +592,16 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         base_aborted = store.is_activity_aborted(info.workflow_id, info.activity_id)
         store.clear_activity_aborted(info.workflow_id, info.activity_id)
 
-        if completed_stop is not None and completed_stop[0] is Verdict.HALT:
-            await _terminate_workflow_for_halt(
-                info.workflow_id, completed_stop[1] or "Governance halt"
-            )
+        if completed_stop is not None:
+            if completed_stop.verdict is Verdict.HALT:
+                await _terminate_workflow_for_halt(
+                    info.workflow_id, completed_stop.reason or "Governance halt"
+                )
+            elif completed_stop.request is not None:
+                # A retryable request outranks the plain skip-completed-event
+                # behavior below — raise the restart request now that user code
+                # has already returned.
+                _raise_retryable_block(completed_stop.request)
 
         was_aborted = base_aborted or completed_stop is not None