nighthawk-python 0.16.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

nighthawk/backends/mcp_boundary.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 import tiktoken
 from opentelemetry import context as otel_context
@@ -29,6 +29,9 @@ from ._text_fallback import (
 )
 from .tool_bridge import ToolHandler
 
+if TYPE_CHECKING:
+    from mcp.types import CallToolResult
+
 _logger = logging.getLogger("nighthawk")
 
 
@@ -187,27 +190,51 @@ def tool_handler_result_to_low_level_mcp_content(
         return [mcp_types.TextContent(type="text", text=render_preview())]
 
 
+def tool_handler_result_to_low_level_mcp_result(
+    *,
+    tool_name: str,
+    tool_handler_result: ToolHandlerResult,
+    rendering_policy: ToolResultRenderingPolicy | None = None,
+) -> CallToolResult:
+    from mcp import types as mcp_types
+
+    content = tool_handler_result_to_low_level_mcp_content(
+        tool_name=tool_name, tool_handler_result=tool_handler_result, rendering_policy=rendering_policy
+    )
+    error = tool_handler_result["tool_outcome"]["error"] if tool_handler_result["kind"] == "tool_result" else None
+    return mcp_types.CallToolResult(
+        content=cast(list[mcp_types.ContentBlock], content),
+        is_error=tool_handler_result["kind"] != "tool_result" or error is not None,
+        structured_content={"error": dict(error)} if error is not None else None,
+    )
+
+
 def _tool_handler_result_to_claude_code_sdk_content(
     *,
     tool_name: str,
     tool_handler_result: ToolHandlerResult,
     rendering_policy: ToolResultRenderingPolicy | None = None,
 ) -> dict[str, object]:
-    content_block_list = tool_handler_result_to_low_level_mcp_content(
+    result = tool_handler_result_to_low_level_mcp_result(
         tool_name=tool_name,
         tool_handler_result=tool_handler_result,
         rendering_policy=rendering_policy,
     )
 
     dumped_content_block_list: list[dict[str, object]] = []
-    for content_block in content_block_list:
+    for content_block in result.content:
         model_dump = getattr(content_block, "model_dump", None)
         if callable(model_dump):
             dumped_content_block_list.append(cast(dict[str, object], model_dump(mode="json", by_alias=True, exclude_none=True)))
             continue
         raise TypeError(f"Unsupported MCP content block: {type(content_block).__name__}")
 
-    return {"content": dumped_content_block_list}
+    response: dict[str, object] = {"content": dumped_content_block_list}
+    if result.is_error:
+        response["isError"] = True
+    if result.structured_content is not None:
+        response["structuredContent"] = result.structured_content
+    return response
 
 
 async def _get_tool_handler_result(
@@ -252,14 +279,14 @@ async def call_tool_for_low_level_mcp_server(
     tool_handler: ToolHandler,
     parent_otel_context: OtelContext,
     rendering_policy: ToolResultRenderingPolicy | None = None,
-) -> list[object]:
+) -> CallToolResult:
     tool_handler_result = await _get_tool_handler_result(
         tool_name=tool_name,
         arguments=arguments,
         tool_handler=tool_handler,
         parent_otel_context=parent_otel_context,
     )
-    return tool_handler_result_to_low_level_mcp_content(
+    return tool_handler_result_to_low_level_mcp_result(
         tool_name=tool_name,
         tool_handler_result=tool_handler_result,
         rendering_policy=rendering_policy,

nighthawk/backends/mcp_server.py

@@ -8,7 +8,7 @@ import time
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from contextvars import copy_context
-from typing import Any, cast
+from typing import Any
 
 from opentelemetry import context as otel_context
 from pydantic_ai.exceptions import UnexpectedModelBehavior
@@ -19,7 +19,7 @@ from ..runtime.step_context import (
     resolve_tool_result_rendering_policy,
 )
 from ..tools.contracts import ToolHandlerResult, ToolOutcome, build_tool_result_observation
-from .mcp_boundary import call_tool_for_low_level_mcp_server, tool_handler_result_to_low_level_mcp_content
+from .mcp_boundary import call_tool_for_low_level_mcp_server, tool_handler_result_to_low_level_mcp_result
 from .tool_bridge import get_current_step_run_context_required
 
 
@@ -95,21 +95,19 @@ class McpServer:
                     "error": {"kind": "resolution", "message": f"Unknown tool: {name}", "guidance": "Choose a visible tool name and retry."},
                 }
                 tool_handler_result: ToolHandlerResult = build_tool_result_observation(tool_outcome=tool_outcome)
-                content_block_list = tool_handler_result_to_low_level_mcp_content(
+                return tool_handler_result_to_low_level_mcp_result(
                     tool_name=name,
                     tool_handler_result=tool_handler_result,
                     rendering_policy=self._tool_result_rendering_policy,
                 )
-                return mcp_types.CallToolResult(content=cast(list[mcp_types.ContentBlock], content_block_list))
 
-            content_block_list = await call_tool_for_low_level_mcp_server(
+            return await call_tool_for_low_level_mcp_server(
                 tool_name=name,
                 arguments=arguments,
                 tool_handler=handler,
                 parent_otel_context=self._parent_otel_context,
                 rendering_policy=self._tool_result_rendering_policy,
             )
-            return mcp_types.CallToolResult(content=cast(list[mcp_types.ContentBlock], content_block_list))
 
         mcp_server = McpLowLevelServer(
             "nighthawk",

nighthawk/backends/tool_bridge.py

@@ -154,8 +154,10 @@ async def execute_tool_call(
         try:
             value = await manager.handle_call(ToolCallPart(tool_name, arguments, tool_call_id), wrap_validation_errors=False)
         except ValidationError as exception:
-            if run_context.deps.operation_failure is exception:
-                raise
+            if run_context.deps.operation_failure is not None:
+                raise run_context.deps.operation_failure from run_context.deps.operation_failure.__cause__
+            if observed_toolset.outcome is not None and (observed_toolset.outcome["error"] or {}).get("status") == "rejected":
+                return build_tool_result_observation(tool_outcome=observed_toolset.outcome)
             retry_text = RetryPromptPart(
                 tool_name=tool_name,
                 content=exception.errors(include_url=False, include_context=False),
@@ -163,9 +165,20 @@ async def execute_tool_call(
             ).model_response()
             return _build_retry_prompt_observation(retry_text=retry_text)
         except ModelRetry as exception:
+            if run_context.deps.operation_failure is not None:
+                raise run_context.deps.operation_failure from run_context.deps.operation_failure.__cause__
+            if observed_toolset.outcome is not None and (observed_toolset.outcome["error"] or {}).get("status") == "rejected":
+                return build_tool_result_observation(tool_outcome=observed_toolset.outcome)
             return _build_retry_prompt_observation(retry_text=exception.message)
 
-        if isinstance(value, ToolDenied):
+        if run_context.deps.operation_failure is not None:
+            raise run_context.deps.operation_failure
+        recorded_error = observed_toolset.outcome["error"] if observed_toolset.outcome is not None else None
+        if recorded_error is not None and recorded_error.get("status") == "rejected":
+            # A capability may replace a return value, but cannot turn a refused body into a success.
+            assert observed_toolset.outcome is not None
+            tool_outcome = observed_toolset.outcome
+        elif isinstance(value, ToolDenied):
             tool_outcome: ToolOutcome = {"payload": None, "error": {"kind": "oversight", "message": value.message, "guidance": None}}
         elif observed_toolset.outcome is not None and value is observed_toolset.return_value:
             tool_outcome = observed_toolset.outcome

nighthawk/lifecycle.py

@@ -31,7 +31,7 @@ type FailureStage = Literal[
     "return_validation",
     "commit_inspection",
     "rewrite_validation",
-    "oversight_rejection",
+    "oversight_abort",
     "raise_construction",
     "binding_assignment",
 ]
@@ -82,7 +82,7 @@ class StepFailed(_StepFinished):
     attempted_outcome: StepResult | None = None
     validated_binding_name_to_value: Mapping[str, object] | None = None
     inspection_subject: Literal["step_commit", "operation"] | None = None
-    rejection_reason: str | None = None
+    abort_reason: str | None = None
     kind: Literal["failed"] = field(default="failed", init=False)
 
 

nighthawk/oversight.py

@@ -18,8 +18,8 @@ def _reference_mapping(name_to_value: Mapping[str, object]) -> Mapping[str, obje
     return MappingProxyType(dict(name_to_value))
 
 
-class OversightRejectedError(NighthawkError):
-    """Raised when oversight explicitly rejects an execution boundary."""
+class StepAbortedError(NighthawkError):
+    """An explicit host decision ending the inspected step, without rollback."""
 
     def __init__(self, reason: str, *, subject: str = "operation") -> None:
         self.reason = reason
@@ -75,9 +75,29 @@ class Accept:
 
 
 @dataclass(frozen=True)
-class Reject:
+class RejectOperation:
+    """Do not execute this operation; expose reason and guidance to its caller or model."""
+
+    reason: str
+    guidance: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.reason, str) or not self.reason.strip():
+            raise ValueError("RejectOperation requires a nonempty string reason")
+        if self.guidance is not None and not isinstance(self.guidance, str):
+            raise TypeError("RejectOperation guidance must be a string or None")
+
+
+@dataclass(frozen=True)
+class AbortStep:
+    """End the current step; catching its exception cannot authorize completion."""
+
     reason: str
 
+    def __post_init__(self) -> None:
+        if not isinstance(self.reason, str) or not self.reason.strip():
+            raise ValueError("AbortStep requires a nonempty string reason")
+
 
 @dataclass(frozen=True)
 class Rewrite:
@@ -106,12 +126,13 @@ class Rewrite:
             raise ValueError("Rewrite Raise cannot include output bindings")
 
 
-type StepCommitDecision = Accept | Reject | Rewrite
+type OperationDecision = Accept | RejectOperation | AbortStep
+type StepCommitDecision = Accept | Rewrite | AbortStep
 
 
 @dataclass(frozen=True)
 class Oversight:
-    inspect_operation: Callable[[OperationRequest], Accept | Reject | Awaitable[Accept | Reject]] | None = None
+    inspect_operation: Callable[[OperationRequest], OperationDecision | Awaitable[OperationDecision]] | None = None
     inspect_step_commit: Callable[[StepCommit], StepCommitDecision | Awaitable[StepCommitDecision]] | None = None
 
 
@@ -153,9 +174,11 @@ __all__ = [
     "Raise",
     "StepResult",
     "Accept",
+    "AbortStep",
+    "OperationDecision",
     "Oversight",
-    "OversightRejectedError",
-    "Reject",
+    "RejectOperation",
+    "StepAbortedError",
     "Rewrite",
     "StepCommit",
     "StepCommitDecision",

nighthawk/runtime/__init__.py

@@ -18,7 +18,14 @@ if TYPE_CHECKING:
     from .environment import StepEnvironment
     from .expression import eval_expression, eval_expression_async
     from .inspection import inspect_value
-    from .operation_contract import OperationError, OperationFinished, OperationRequest
+    from .operation_contract import (
+        OperationDeliveryError,
+        OperationError,
+        OperationFinished,
+        OperationRejectedError,
+        OperationRejection,
+        OperationRequest,
+    )
     from .step_definition import StepDefinition
     from .step_request import StepCandidate, StepRequest
     from .step_result import Break, Continue, Pass, Raise, Return, StepResult
@@ -48,6 +55,9 @@ _name_to_module = {
     "StepEnvironment": "environment",
     "inspect_value": "inspection",
     "OperationError": "operation_contract",
+    "OperationDeliveryError": "operation_contract",
+    "OperationRejectedError": "operation_contract",
+    "OperationRejection": "operation_contract",
     "OperationFinished": "operation_contract",
     "OperationRequest": "operation_contract",
     "Pass": "step_result",
@@ -82,6 +92,9 @@ __all__ = [
     "StepEnvironment",
     "inspect_value",
     "OperationError",
+    "OperationDeliveryError",
+    "OperationRejectedError",
+    "OperationRejection",
     "OperationFinished",
     "OperationRequest",
     "Pass",

nighthawk/runtime/model_response.py

@@ -0,0 +1,43 @@
+"""A response-local rejection barrier, independent of model retry budgets."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from .operation_contract import OperationRejection
+from .step_context import StepContext
+
+
+@dataclass
+class ModelResponseExecution:
+    step_context: StepContext
+    rejection: OperationRejection | None = None
+
+
+_model_response_execution: ContextVar[ModelResponseExecution | None] = ContextVar("nighthawk_model_response_execution", default=None)
+
+
+@contextmanager
+def model_response_scope(step_context: StepContext, *, reuse: bool = False) -> Iterator[ModelResponseExecution]:
+    current = _model_response_execution.get()
+    if reuse and current is not None and current.step_context is step_context:
+        yield current
+        return
+    execution = ModelResponseExecution(step_context)
+    token = _model_response_execution.set(execution)
+    try:
+        yield execution
+    finally:
+        _model_response_execution.reset(token)
+
+
+def get_response_rejection(step_context: StepContext) -> OperationRejection | None:
+    execution = _model_response_execution.get()
+    return execution.rejection if execution is not None and execution.step_context is step_context else None
+
+
+def record_response_rejection(step_context: StepContext, rejection: OperationRejection) -> None:
+    execution = _model_response_execution.get()
+    if execution is not None and execution.step_context is step_context:
+        execution.rejection = rejection

nighthawk/runtime/operation_contract.py

@@ -11,8 +11,9 @@ from ..errors import NighthawkError
 from ..tools.contracts import ToolBoundaryError
 from .execution_reference import ExecutionReference
 
-type OperationKind = Literal["evaluation", "assignment", "return", "native_tool", "inspection"]
+type OperationKind = Literal["evaluation", "assignment", "return", "native_tool", "inspection", "output"]
 type OperationPhase = Literal["admission", "inspection", "evaluation", "target_resolution", "validation", "assignment", "completed"]
+type OperationStatus = Literal["succeeded", "rejected", "aborted", "skipped", "failed", "interrupted"]
 
 
 class OperationRequest(BaseModel):
@@ -33,14 +34,44 @@ class OperationRequest(BaseModel):
         return MappingProxyType(dict(value))
 
 
+@dataclass(frozen=True)
+class OperationRejection:
+    """One refused operation and the host's deliberately model-visible feedback."""
+
+    request: OperationRequest
+    reason: str
+    guidance: str | None = None
+
+    def model_feedback(self) -> dict[str, object]:
+        """Expose correlation and feedback, without serializing live arguments or diagnostics."""
+        return {
+            "status": "rejected",
+            "operation_id": self.request.operation_id,
+            "step_execution_id": self.request.execution_reference.step_execution_id,
+            "reason": self.reason,
+            "guidance": self.guidance,
+            "evaluation_started": False,
+        }
+
+
+class OperationRejectedError(NighthawkError):
+    """The operation did not start; the same step can perform a different operation."""
+
+    def __init__(self, rejection: OperationRejection) -> None:
+        self.rejection = rejection
+        super().__init__(rejection.reason)
+
+
 @dataclass(frozen=True)
 class OperationFinished:
     request: OperationRequest
-    status: Literal["succeeded", "rejected", "failed", "interrupted"]
+    status: OperationStatus
     phase: OperationPhase
     evaluation_started: bool
     value: object = None
     original_exception: BaseException | None = None
+    rejection: OperationRejection | None = None
+    blocked_by_operation_id: str | None = None
 
 
 class OperationError(ToolBoundaryError):

nighthawk/runtime/operations.py

@@ -10,11 +10,21 @@ from dataclasses import dataclass
 from pydantic_ai.exceptions import ApprovalRequired, CallDeferred, ModelRetry
 
 from ..errors import NighthawkError
-from ..oversight import Accept, OversightRejectedError, Reject, record_oversight_decision
+from ..oversight import AbortStep, Accept, RejectOperation, StepAbortedError, record_oversight_decision
 from ..ulid import generate_ulid
 from .interruption import chain_cleanup_errors
 from .notifications import await_notification
-from .operation_contract import OperationDeliveryError, OperationError, OperationFinished, OperationKind, OperationPhase, OperationRequest
+from .operation_contract import (
+    OperationDeliveryError,
+    OperationError,
+    OperationFinished,
+    OperationKind,
+    OperationPhase,
+    OperationRejectedError,
+    OperationRejection,
+    OperationRequest,
+    OperationStatus,
+)
 from .step_context import StepContext
 
 _active_operation_context: ContextVar[StepContext | None] = ContextVar("nighthawk_active_operation_context", default=None)
@@ -34,6 +44,7 @@ async def execute_operation_async(
     admit: Callable[[], None],
     execute: Callable[[OperationExecution], Awaitable[object]],
     recoverable_admission_error: BaseException | None = None,
+    blocked_by: OperationRejection | None = None,
 ) -> object:
     from .scoping import _lifecycle_var, _oversight_var
 
@@ -46,52 +57,71 @@ async def execute_operation_async(
         token = _active_operation_context.set(step_context)
         outcome: object = None
         original_exception: BaseException | None = None
-        status = "succeeded"
+        status: OperationStatus = "succeeded"
+        rejection_error: OperationRejectedError | None = None
+        abort_error: StepAbortedError | None = None
         try:
             try:
-                admit()
+                if blocked_by is not None:
+                    status = "skipped"
+                else:
+                    admit()
                 execution.phase = "inspection"
                 oversight = _oversight_var.get()
-                if oversight is not None and oversight.inspect_operation is not None:
+                if blocked_by is None and oversight is not None and oversight.inspect_operation is not None:
                     decision = oversight.inspect_operation(request)
                     if inspect.isawaitable(decision):
                         decision = await decision
-                    if not isinstance(decision, (Accept, Reject)):
-                        raise NighthawkError("Operation inspection must return Accept or Reject")
+                    if not isinstance(decision, (Accept, RejectOperation, AbortStep)):
+                        raise NighthawkError("Operation inspection must return Accept, RejectOperation, or AbortStep")
                     record_oversight_decision(
                         subject="operation",
-                        verdict="reject" if isinstance(decision, Reject) else "accept",
+                        verdict="reject" if isinstance(decision, RejectOperation) else "abort" if isinstance(decision, AbortStep) else "accept",
                         execution_reference=request.execution_reference,
                         tool_name=request.tool_name,
                         reason=decision.reason,
                     )
-                    if isinstance(decision, Reject):
-                        raise OversightRejectedError(decision.reason, subject="operation")
-                execution.phase = "evaluation"
-                execution.evaluation_started = True
-                outcome = await execute(execution)
-                execution.phase = "completed"
+                    if isinstance(decision, RejectOperation):
+                        rejection_error = OperationRejectedError(OperationRejection(request, decision.reason, decision.guidance))
+                        raise rejection_error
+                    if isinstance(decision, AbortStep):
+                        abort_error = StepAbortedError(decision.reason, subject="operation")
+                        step_context.operation_abort = abort_error
+                        raise abort_error
+                if blocked_by is None:
+                    execution.phase = "evaluation"
+                    execution.evaluation_started = True
+                    outcome = await execute(execution)
+                    execution.phase = "completed"
+                else:
+                    execution.phase = "admission"
             except BaseException as exception:
                 original_exception = exception
-                if isinstance(exception, OversightRejectedError):
+                if exception is rejection_error:
                     status = "rejected"
+                elif exception is abort_error:
+                    status = "aborted"
                 elif isinstance(exception, Exception):
                     status = "failed"
                 else:
                     status = "interrupted"
                 recoverable_admission = execution.phase == "admission" and exception is recoverable_admission_error
-                if not recoverable_admission and (
-                    not isinstance(exception, (OperationError, ModelRetry, ApprovalRequired, CallDeferred)) or execution.phase == "inspection"
+                if (
+                    exception is not rejection_error
+                    and not recoverable_admission
+                    and (not isinstance(exception, (OperationError, ModelRetry, ApprovalRequired, CallDeferred)) or execution.phase == "inspection")
                 ):
                     step_context.operation_failure = exception
                     step_context.operation_failure_stage = "operation_inspection" if execution.phase == "inspection" else "operation_execution"
             finished = OperationFinished(
                 request=request,
-                status=status,  # type: ignore[arg-type]
-                phase=execution.phase,  # type: ignore[arg-type]
+                status=status,
+                phase=execution.phase,
                 evaluation_started=execution.evaluation_started,
                 value=outcome,
                 original_exception=original_exception,
+                rejection=rejection_error.rejection if rejection_error is not None else None,
+                blocked_by_operation_id=blocked_by.request.operation_id if blocked_by is not None else None,
             )
             lifecycle = _lifecycle_var.get()
             if lifecycle is not None and lifecycle.on_operation_finished is not None:

nighthawk/runtime/runner.py

@@ -15,10 +15,10 @@ from ..composition import UnsetType
 from ..errors import ExecutionError, NighthawkError
 from ..lifecycle import FailureStage, StepCompleted, StepFailed, StepFinished, StepInterrupted, StepLifecycle, StepRaised, StepStarted
 from ..oversight import (
+    AbortStep,
     Accept,
-    OversightRejectedError,
-    Reject,
     Rewrite,
+    StepAbortedError,
     StepCommit,
     record_oversight_decision,
 )
@@ -103,6 +103,7 @@ class Runner:
         self.attempted_outcome: StepResult | None = None
         self.outcome: StepResult | None = None
         self.raise_exception: BaseException | None = None
+        self.commit_abort: StepAbortedError | None = None
         self.context_stack = ExitStack()
 
     @contextmanager
@@ -130,19 +131,25 @@ class Runner:
             self.failure_stage = self.preparation.step_context.operation_failure_stage
         finished: StepFinished
         if isinstance(original_exception, Exception):
-            rejection = original_exception if isinstance(original_exception, OversightRejectedError) else None
+            operation_abort = self.preparation.step_context.operation_abort if self.preparation is not None else None
+            rejection = (
+                original_exception
+                if isinstance(original_exception, StepAbortedError)
+                and (original_exception is operation_abort or original_exception is self.commit_abort)
+                else None
+            )
             finished = StepFailed(
                 execution_reference=execution_reference,
                 processed_natural_program=self.preparation_state.processed_natural_program,
                 input_binding_name_to_value=self.preparation_state.input_binding_name_to_value,
                 allowed_step_kinds=self.preparation_state.allowed_step_kinds,
                 assigned_binding_name_to_value=self.assigned_binding_name_to_value,
-                failure_stage="oversight_rejection" if rejection else self.failure_stage,
+                failure_stage="oversight_abort" if rejection else self.failure_stage,
                 original_exception=original_exception,
                 attempted_outcome=self.attempted_outcome,
                 validated_binding_name_to_value=self.validated_binding_name_to_value,
                 inspection_subject=cast(typing.Literal["step_commit", "operation"], rejection.subject) if rejection else None,
-                rejection_reason=rejection.reason if rejection else None,
+                abort_reason=rejection.reason if rejection else None,
             )
             _record_internal_step_failure(step_span=step_span, exception=original_exception)
         elif original_exception is not None:
@@ -201,6 +208,8 @@ class Runner:
                 raise delivery_exception from original_exception
             raise
         if isinstance(finished, StepFailed):
+            if finished.original_exception is self.commit_abort:
+                raise finished.original_exception
             if self.preparation is not None and self.preparation.step_context.operation_failure is finished.original_exception:
                 raise finished.original_exception
             raise ExecutionError(finished, description=self.failure_description) from finished.original_exception
@@ -341,14 +350,15 @@ class Runner:
         if inspect.isawaitable(decision):
             decision = await decision
 
-        if isinstance(decision, Reject):
+        if isinstance(decision, AbortStep):
             record_oversight_decision(
                 subject="step_commit",
-                verdict="reject",
+                verdict="abort",
                 execution_reference=execution_reference,
                 reason=decision.reason,
             )
-            raise OversightRejectedError(decision.reason, subject="step_commit")
+            self.commit_abort = StepAbortedError(decision.reason, subject="step_commit")
+            raise self.commit_abort
 
         if isinstance(decision, Accept):
             record_oversight_decision(
@@ -360,7 +370,7 @@ class Runner:
             return outcome, bindings
 
         if not isinstance(decision, Rewrite):
-            raise NighthawkError("Oversight inspect_step_commit must return Accept, Reject, or Rewrite")
+            raise NighthawkError("Oversight inspect_step_commit must return Accept, Rewrite, or AbortStep")
 
         record_oversight_decision(
             subject="step_commit",

nighthawk/runtime/step_context.py

@@ -15,6 +15,7 @@ from .execution_reference import ExecutionReference
 
 if TYPE_CHECKING:
     from ..lifecycle import FailureStage
+    from ..oversight import StepAbortedError
 
 _MISSING: object = object()
 """Sentinel indicating a name could not be resolved. Distinct from None."""
@@ -72,6 +73,7 @@ class StepContext:
     operation_lock: asyncio.Lock = field(default_factory=asyncio.Lock, init=False, repr=False)
     operation_failure: BaseException | None = field(default=None, init=False, repr=False)
     operation_failure_stage: FailureStage | None = field(default=None, init=False)
+    operation_abort: StepAbortedError | None = field(default=None, init=False, repr=False)
 
     def __post_init__(self, task_name_to_value: Mapping[str, object]) -> None:
         self.binding_name_to_type = MappingProxyType(dict(self.binding_name_to_type))

nighthawk/runtime/step_executor.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import json
 from typing import Any, Protocol, cast, runtime_checkable
 
 from pydantic import TypeAdapter
 from pydantic_ai import Agent, RunContext, StructuredDict
 from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.exceptions import ModelRetry
 from pydantic_ai.messages import UserContent
 from pydantic_ai.models import ModelRequestContext
+from pydantic_ai.output import OutputContext
 from pydantic_ai.settings import ModelSettings
 from pydantic_ai.toolsets.function import FunctionToolset
 
@@ -20,6 +23,8 @@ from ..tools.execution import ToolResultWrapperToolset
 from .async_bridge import run_coroutine_synchronously
 from .context import DefaultContextBuilder, build_context_content, build_context_request
 from .model_candidate import resolve_model_candidate
+from .model_response import get_response_rejection, record_response_rejection
+from .operation_contract import OperationRejectedError
 from .prompt import build_system_prompt, extract_references_and_program, resolve_step_system_prompt_template_text
 from .scoping import (
     _context_builder_var,
@@ -54,10 +59,45 @@ class _OperationFailureGuard(AbstractCapability[StepContext]):
         # Pydantic AI can classify a body ValidationError as retryable or let a capability supply a substitute result.
         # Neither clears our operation failure, and neither may cause another model request for this step.
         if ctx.deps.operation_failure is not None:
-            raise ctx.deps.operation_failure
+            raise ctx.deps.operation_failure from ctx.deps.operation_failure.__cause__
         return request_context
 
 
+class _StepOutputBoundary(_OperationFailureGuard):
+    """Resolve candidate operations while the agent can still receive feedback."""
+
+    def __init__(self, request: StepRequest) -> None:
+        super().__init__()
+        self.request = request
+
+    async def after_output_process(self, ctx: RunContext[StepContext], *, output_context: OutputContext, output: Any) -> Any:
+        if ctx.partial_output:
+            return output
+        if ctx.deps.operation_failure is not None:
+            raise ctx.deps.operation_failure from ctx.deps.operation_failure.__cause__
+        rejection = get_response_rejection(ctx.deps)
+        if rejection is not None:
+            raise ModelRetry(json.dumps(rejection.model_feedback(), ensure_ascii=False))
+        try:
+            return await resolve_model_candidate(self.request, _parse_step_outcome(output))
+        except OperationRejectedError as exception:
+            if ctx.deps.operation_failure is not None:
+                raise ctx.deps.operation_failure from ctx.deps.operation_failure.__cause__
+            record_response_rejection(ctx.deps, exception.rejection)
+            raise ModelRetry(json.dumps(exception.rejection.model_feedback(), ensure_ascii=False)) from exception
+
+
+def _parse_step_outcome(raw_output: Any) -> StepOutcome:
+    try:
+        if isinstance(raw_output, StepFinalResult):
+            return raw_output.result
+        if isinstance(raw_output, dict) and "result" in raw_output:
+            return TypeAdapter(StepOutcome).validate_python(raw_output["result"])
+        return TypeAdapter(StepOutcome).validate_python(raw_output)
+    except Exception as exception:
+        raise ExecutionError(f"Step produced invalid step outcome: {exception}") from exception
+
+
 @runtime_checkable
 class AsyncExecutionAgent(Protocol):
     async def run(self, *args: Any, **kwargs: Any) -> Any: ...
@@ -236,7 +276,7 @@ class AgentStepExecutor:
         self,
         *,
         user_prompt: tuple[UserContent, ...],
-        step_context: StepContext,
+        request: StepRequest,
         toolset: ToolResultWrapperToolset,
         structured_output_type: object,
     ) -> Any:
@@ -246,12 +286,13 @@ class AgentStepExecutor:
         normalized_user_prompt: str | tuple[UserContent, ...] = (
             user_prompt[0] if len(user_prompt) == 1 and isinstance(user_prompt[0], str) else user_prompt
         )
-        capabilities = [*_current_capabilities(), _OperationFailureGuard(), ToolAdmissionCapability()]
+        # First means last for after_output_process: resolve the output after application hooks.
+        capabilities = [_StepOutputBoundary(request), *_current_capabilities(), ToolAdmissionCapability()]
 
         if isinstance(self.agent, AsyncExecutionAgent):
             return await self.agent.run(
                 normalized_user_prompt,
-                deps=step_context,
+                deps=request.step_context,
                 toolsets=[toolset],
                 output_type=structured_output_type,
                 capabilities=capabilities,
@@ -260,7 +301,7 @@ class AgentStepExecutor:
         if isinstance(self.agent, SyncExecutionAgent):
             return self.agent.run_sync(
                 normalized_user_prompt,
-                deps=step_context,
+                deps=request.step_context,
                 toolsets=[toolset],
                 output_type=structured_output_type,
                 capabilities=capabilities,
@@ -313,20 +354,6 @@ class AgentStepExecutor:
 
         return structured_output_type, step_system_prompt_fragment
 
-    def _parse_agent_result(
-        self,
-        result: Any,
-    ) -> StepOutcome:
-        try:
-            raw_output = result.output
-            if isinstance(raw_output, StepFinalResult):
-                return raw_output.result
-            if isinstance(raw_output, dict) and "result" in raw_output:
-                return TypeAdapter(StepOutcome).validate_python(raw_output["result"])
-            return TypeAdapter(StepOutcome).validate_python(raw_output)
-        except Exception as e:
-            raise ExecutionError(f"Step produced invalid step outcome: {e}") from e
-
     async def run_step_async(
         self,
         *,
@@ -361,7 +388,7 @@ class AgentStepExecutor:
             try:
                 result = await self._run_agent(
                     user_prompt=user_prompt,
-                    step_context=step_context,
+                    request=request,
                     toolset=toolset,
                     structured_output_type=structured_output_type,
                 )
@@ -373,14 +400,16 @@ class AgentStepExecutor:
                 raise failure from failure.__cause__
 
         if step_context.operation_failure is not None:
-            raise step_context.operation_failure
+            raise step_context.operation_failure from step_context.operation_failure.__cause__
 
         usage_meter = get_usage_meter()
         if usage_meter is not None and hasattr(result, "usage"):
             usage_meter.record(result.usage, kind="step")
 
-        step_outcome = self._parse_agent_result(result)
-        return await resolve_model_candidate(request, step_outcome)
+        if isinstance(result.output, StepCandidate):
+            return result.output
+        # Protocol agents that do not execute Pydantic AI capabilities own their model loop.
+        return await resolve_model_candidate(request, _parse_step_outcome(result.output))
 
     def run_step(
         self,

nighthawk/tools/_ordering.py

@@ -1,30 +1,40 @@
-"""Keep Pydantic AI argument validation inside ordered model-tool dispatch.
+"""Keep validation and refusal barriers inside ordered model-tool dispatch.
 
 Pydantic AI 2.37 validates function batches before its execution barriers.
-These scoped compatibility hooks delegate validation, execution, retries,
-deferrals, and output selection to Pydantic AI; they only move validation to
-the corresponding sequential dispatch. Ordinary Pydantic AI runs are unchanged.
+These scoped compatibility hooks move validation to sequential dispatch,
+stop later calls after a refusal, and discard candidates from that response.
+Pydantic AI still owns execution, retry limits, and output selection among
+permitted candidates. Ordinary Pydantic AI runs are unchanged.
 """
 
 from __future__ import annotations
 
+import json
 from collections.abc import AsyncIterator, Iterator
 from contextlib import contextmanager
 from contextvars import ContextVar
 from typing import Any
 
-from pydantic_ai import _tool_execution
+from pydantic_ai import _agent_graph, _tool_execution
 from pydantic_ai.exceptions import UnexpectedModelBehavior
-from pydantic_ai.messages import FunctionToolCallEvent, HandleResponseEvent, ToolCallPart
+from pydantic_ai.messages import FunctionToolCallEvent, FunctionToolResultEvent, HandleResponseEvent, RetryPromptPart, ToolCallPart, ToolReturnPart
 from pydantic_ai.tool_manager import ToolManager, ValidatedToolCall
 from pydantic_ai.tools import ToolApproved
 
+from ..runtime.model_response import get_response_rejection, model_response_scope
+from ..runtime.operations import OperationExecution, execute_operation_async, new_operation_request
 from ..runtime.step_context import StepContext
 
 _ordered_dispatch: ContextVar[bool] = ContextVar("nighthawk_ordered_model_dispatch", default=False)
 _original_function_calls = _tool_execution._ToolCallProcessor._run_function_calls
 _original_validation = _tool_execution._ExhaustiveProcessor._validate_function_calls
 _original_call_tool = _tool_execution._ExhaustiveProcessor._call_tool
+_original_run = _tool_execution._ToolCallProcessor.run
+_original_output_call = _tool_execution._ToolCallProcessor._run_output_tool_call
+_original_run_output = _tool_execution._ToolCallProcessor._run_output
+_original_finalize_deferred = _tool_execution._ToolCallProcessor._finalize_deferred
+_original_early_strategy = _tool_execution._EarlyProcessor._run_strategy
+_original_handle_tool_calls = _agent_graph.CallToolsNode._handle_tool_calls
 
 
 def _requires_ordered_validation(processor: Any) -> bool:
@@ -32,13 +42,157 @@ def _requires_ordered_validation(processor: Any) -> bool:
     return _ordered_dispatch.get() and context is not None and isinstance(context.deps, StepContext)
 
 
+def _rejection(processor: Any) -> Any:
+    return get_response_rejection(processor.tool_manager.ctx.deps) if _requires_ordered_validation(processor) else None
+
+
+async def _skip_call(processor: Any, call: ToolCallPart, *, output: bool = False) -> ToolReturnPart:
+    context = processor.tool_manager.ctx.deps
+    rejection = get_response_rejection(context)
+    assert rejection is not None
+    tool_definition = processor.tool_manager.get_tool_def(call.tool_name)
+    kind = (tool_definition.metadata or {}).get("nighthawk.operation_kind") if tool_definition is not None else None
+    arguments = call.args if isinstance(call.args, dict) else {"unvalidated_arguments": call.args}
+    expression = arguments.get("expression")
+    target_path = arguments.get("target_path")
+    request = new_operation_request(
+        context,
+        kind="output" if output else kind if kind in ("evaluation", "assignment", "inspection") else "native_tool",
+        tool_name=call.tool_name,
+        argument_name_to_value=arguments,
+        expression=expression if isinstance(expression, str) else None,
+        target_path=target_path if isinstance(target_path, str) else None,
+    )
+
+    async def unreachable(execution: OperationExecution) -> object:
+        raise AssertionError("A skipped operation cannot execute")
+
+    await execute_operation_async(context, request, admit=lambda: None, execute=unreachable, blocked_by=rejection)
+    return ToolReturnPart(
+        tool_name=call.tool_name,
+        tool_call_id=call.tool_call_id,
+        outcome="failed",
+        content={
+            "status": "skipped",
+            "operation_id": request.operation_id,
+            "step_execution_id": request.execution_reference.step_execution_id,
+            "blocked_by_operation_id": rejection.request.operation_id,
+            "evaluation_started": False,
+            "message": "Not executed after an operation rejection. Choose the next operations in a new response.",
+        },
+    )
+
+
+async def _run(self: Any) -> AsyncIterator[HandleResponseEvent]:
+    if not _requires_ordered_validation(self):
+        async for event in _original_run(self):
+            yield event
+        return
+    with model_response_scope(self.tool_manager.ctx.deps, reuse=True) as execution:
+        if execution.rejection is not None:
+            # Native output under `early` was inspected before tool dispatch.
+            # Pydantic AI suppresses its retry; preserve both feedback and accounting.
+            self.ctx.state.consume_output_retry(self.ctx.deps.max_output_retries)
+            self.output_parts.append(RetryPromptPart(content=json.dumps(execution.rejection.model_feedback())))
+        async for event in _original_run(self):
+            yield event
+        if execution.rejection is not None:
+            # An earlier accepted output cannot mask a later refusal in the same response.
+            self.final_result = None
+            if self.winning_output_part is not None:
+                self.winning_output_part.content = {
+                    "status": "discarded",
+                    "blocked_by_operation_id": execution.rejection.request.operation_id,
+                }
+
+
+async def _handle_tool_calls(
+    self: Any, ctx: Any, tool_calls: list[ToolCallPart], *, response_output: Any = None
+) -> AsyncIterator[HandleResponseEvent]:
+    if _ordered_dispatch.get() and isinstance(ctx.deps.user_deps, StepContext):
+        with model_response_scope(ctx.deps.user_deps):
+            async for event in _original_handle_tool_calls(self, ctx, tool_calls, response_output=response_output):
+                yield event
+    else:
+        async for event in _original_handle_tool_calls(self, ctx, tool_calls, response_output=response_output):
+            yield event
+
+
 async def _run_function_calls(self: Any, calls: list[ToolCallPart]) -> AsyncIterator[HandleResponseEvent]:
     batches = ([call] for call in calls) if _requires_ordered_validation(self) else (calls,)
     for batch in batches:
+        if _rejection(self) is not None:
+            for call in batch:
+                part = await _skip_call(self, call)
+                self.output_parts.append(part)
+                yield FunctionToolCallEvent(call, args_valid=None)
+                yield FunctionToolResultEvent(part)
+            continue
         async for event in _original_function_calls(self, batch):
             yield event
 
 
+async def _call_tool(self: Any, tool_call: Any, *, tool_call_result: Any) -> Any:
+    before = _rejection(self)
+    result = await _original_call_tool(self, tool_call, tool_call_result=tool_call_result)
+    if _requires_ordered_validation(self):
+        context = self.tool_manager.ctx.deps
+        if context.operation_failure is not None:
+            raise context.operation_failure
+        rejection = get_response_rejection(context)
+        if before is None and rejection is not None:
+            call = tool_call.call if isinstance(tool_call, ValidatedToolCall) else tool_call
+            return [
+                ToolReturnPart(tool_name=call.tool_name, tool_call_id=call.tool_call_id, content=rejection.model_feedback(), outcome="denied")
+            ], None
+    return result
+
+
+async def _run_output_tool_call(self: Any, call: ToolCallPart) -> Any:
+    if _rejection(self) is not None:
+        part = await _skip_call(self, call, output=True)
+        # No output validator or retry budget is consumed by an unattempted candidate.
+        return _tool_execution._OutputCallResult(
+            call=call,
+            retry_part=RetryPromptPart(tool_name=call.tool_name, tool_call_id=call.tool_call_id, content=json.dumps(part.content)),
+        )
+    result = await _original_output_call(self, call)
+    if _rejection(self) is not None and result.raise_exc is not None:
+        # Exhaustive output settlement must not hide exhausted retry limits behind an earlier candidate.
+        raise result.raise_exc
+    return result
+
+
+async def _run_output(self: Any, call: ToolCallPart) -> AsyncIterator[HandleResponseEvent]:
+    if _rejection(self) is not None:
+        part = await _skip_call(self, call, output=True)
+        for event in self._record_output_part(call, part, args_valid=None):
+            yield event
+        return
+    async for event in _original_run_output(self, call):
+        yield event
+
+
+async def _finalize_deferred(self: Any) -> AsyncIterator[HandleResponseEvent]:
+    if _rejection(self) is not None:
+        settled = {part.tool_call_id for part in self.output_parts if isinstance(part, (ToolReturnPart, RetryPromptPart))}
+        for call in self.tool_calls:
+            if call.tool_call_id not in settled:
+                part = await _skip_call(self, call)
+                self.output_parts.append(part)
+                yield FunctionToolCallEvent(call, args_valid=None)
+                yield FunctionToolResultEvent(part)
+        return
+    async for event in _original_finalize_deferred(self):
+        yield event
+
+
+async def _run_early_strategy(self: Any) -> AsyncIterator[HandleResponseEvent]:
+    strategy = _tool_execution._GracefulProcessor._run_strategy if _requires_ordered_validation(self) else _original_early_strategy
+    async for event in strategy(self):
+        yield event
+
+
 async def _validate_exhaustive_calls(
     self: Any, calls: list[ToolCallPart], *, validated_calls: dict[str, ValidatedToolCall[Any]]
 ) -> AsyncIterator[HandleResponseEvent]:
@@ -54,6 +208,9 @@ async def _validate_exhaustive_calls(
 
 
 async def _call_exhaustive_tool(self: Any, tool_call: Any, *, tool_call_result: Any) -> Any:
+    if _rejection(self) is not None:
+        call = tool_call.call if isinstance(tool_call, ValidatedToolCall) else tool_call
+        return [await _skip_call(self, call)], None
     if (
         _requires_ordered_validation(self)
         and isinstance(tool_call, ToolCallPart)
@@ -68,14 +225,21 @@ async def _call_exhaustive_tool(self: Any, tool_call: Any, *, tool_call_result:
         except UnexpectedModelBehavior:
             self.ctx.state.check_incomplete_tool_call()
             raise
-    return await _original_call_tool(self, tool_call, tool_call_result=tool_call_result)
+    return await _call_tool(self, tool_call, tool_call_result=tool_call_result)
 
 
 # Install dispatchers once under Python's import lock. Context variables scope
 # their behavior across asynchronous tasks and supported thread bridges.
 _tool_execution._ToolCallProcessor._run_function_calls = _run_function_calls
+_tool_execution._ToolCallProcessor.run = _run
+_tool_execution._ToolCallProcessor._call_tool = _call_tool
+_tool_execution._ToolCallProcessor._run_output_tool_call = _run_output_tool_call
+_tool_execution._ToolCallProcessor._run_output = _run_output
+_tool_execution._ToolCallProcessor._finalize_deferred = _finalize_deferred
+_tool_execution._EarlyProcessor._run_strategy = _run_early_strategy
 _tool_execution._ExhaustiveProcessor._validate_function_calls = _validate_exhaustive_calls
 _tool_execution._ExhaustiveProcessor._call_tool = _call_exhaustive_tool
+_agent_graph.CallToolsNode._handle_tool_calls = _handle_tool_calls
 
 
 @contextmanager

nighthawk/tools/contracts.py

@@ -23,6 +23,9 @@ class ToolError(TypedDict):
     guidance: str | None
     phase: NotRequired[str]
     evaluation_started: NotRequired[bool]
+    operation_id: NotRequired[str]
+    step_execution_id: NotRequired[str | None]
+    status: NotRequired[Literal["rejected", "skipped"]]
 
 
 class ToolOutcome(TypedDict):
@@ -77,6 +80,9 @@ def render_tool_handler_result_preview_text(
 ) -> str:
     if tool_handler_result["kind"] == "tool_result":
         tool_outcome = tool_handler_result["tool_outcome"]
+        if tool_outcome["error"] is not None and tool_outcome["error"].get("status") in ("rejected", "skipped"):
+            # Control feedback is not a lossy value preview. Preserve its identity and host-supplied reason.
+            return json.dumps({"value": None, "error": tool_outcome["error"]}, ensure_ascii=False)
         return render_tool_result_json_text(
             value=tool_outcome["payload"],
             error=tool_outcome["error"],

nighthawk/tools/execution.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 from collections.abc import Awaitable, Callable
 from typing import Any
 
@@ -9,6 +10,7 @@ from pydantic import TypeAdapter
 from pydantic_ai import RunContext
 from pydantic_ai.exceptions import ApprovalRequired, CallDeferred, ModelRetry
 from pydantic_ai.messages import CachePoint, TextContent, ToolReturnContent, is_multi_modal_content
+from pydantic_ai.tools import ToolDenied
 from pydantic_ai.toolsets.abstract import ToolsetTool
 from pydantic_ai.toolsets.wrapper import WrapperToolset
 from pydantic_core import PydanticSerializationError
@@ -16,7 +18,8 @@ from pydantic_core import PydanticSerializationError
 from ..json_renderer import project_discovery_value, to_jsonable_value
 from ..runtime._user_content import is_top_level_sequence_payload
 from ..runtime.discovery import DiscoveryResult, contains_discovery_result, map_discovery_containers
-from ..runtime.operation_contract import OperationError
+from ..runtime.model_response import record_response_rejection
+from ..runtime.operation_contract import OperationError, OperationRejectedError, OperationRejection
 from ..runtime.operations import OperationExecution, execute_operation_async, new_operation_request
 from ..runtime.step_context import StepContext
 from .contracts import ErrorKind, ToolError, ToolOutcome
@@ -77,20 +80,45 @@ def _normalize_tool_failure(*, kind: ErrorKind, message: str, guidance: str | No
 def _build_standard_tool_return_value(*, tool_outcome: ToolOutcome) -> object:
     if tool_outcome["error"] is None:
         return tool_outcome["payload"]
+    if tool_outcome["error"].get("status") == "rejected":
+        return ToolDenied(json.dumps(tool_outcome["error"], ensure_ascii=False))
     return {
         "value": tool_outcome["payload"],
         "error": tool_outcome["error"],
     }
 
 
-async def _run_tool_and_normalize(tool_call: Callable[[], Awaitable[object]]) -> ToolOutcome:
+def rejection_tool_outcome(rejection: OperationRejection) -> ToolOutcome:
+    return {
+        "payload": None,
+        "error": {
+            "kind": "oversight",
+            "status": "rejected",
+            "operation_id": rejection.request.operation_id,
+            "step_execution_id": rejection.request.execution_reference.step_execution_id,
+            "message": rejection.reason,
+            "guidance": rejection.guidance,
+            "phase": "inspection",
+            "evaluation_started": False,
+        },
+    }
+
+
+async def _run_tool_and_normalize(tool_call: Callable[[], Awaitable[object]], step_context: StepContext) -> ToolOutcome:
     """Exceptions from Pydantic AI toolset plumbing are handled in ``tool_bridge.execute_tool_call``."""
 
     try:
         value = await tool_call()
+    except OperationRejectedError as exception:
+        if step_context.operation_failure is not None:
+            raise step_context.operation_failure from step_context.operation_failure.__cause__
+        record_response_rejection(step_context, exception.rejection)
+        return rejection_tool_outcome(exception.rejection)
     except (ModelRetry, CallDeferred, ApprovalRequired):
         raise
     except OperationError as exception:
+        if step_context.operation_failure is not None:
+            raise step_context.operation_failure from step_context.operation_failure.__cause__
         outcome = _normalize_tool_failure(
             kind=exception.kind,
             message=str(exception),
@@ -125,7 +153,7 @@ class ToolResultWrapperToolset(WrapperToolset[StepContext]):
 
             return await execute_operation_async(run_context.deps, request, admit=lambda: None, execute=execute)
 
-        tool_result = await _run_tool_and_normalize(tool_call)
+        tool_result = await _run_tool_and_normalize(tool_call, run_context.deps)
         return tool_result
 
     # DEPENDENCY: Pydantic AI's WrapperToolset calls self.call_tool() rather

{nighthawk_python-0.16.0.dist-info → nighthawk_python-0.17.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.16.0
+Version: 0.17.0
 Summary: A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
 Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
 Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/

{nighthawk_python-0.16.0.dist-info → nighthawk_python-0.17.0.dist-info}/RECORD

@@ -5,8 +5,8 @@ nighthawk/errors.py,sha256=U9ogl_0MLA1xXe_bU2RCA1gRWN0ev5E4a3FiBLgpilI,1282
 nighthawk/function_call.py,sha256=o_i86cbsRxC0kMsTXCWvijA7SJmC7oNrcEghTNvpWJE,6745
 nighthawk/identifier_path.py,sha256=QRbDte7j0mubwg8ebs1GlxW7QeA5V_ow29MpVPCg6Ck,626
 nighthawk/json_renderer.py,sha256=QT4-kyKcr_rcga5hg2irKZ4a2OH6XJ8c0_b1zBlPjcE,10501
-nighthawk/lifecycle.py,sha256=pHCTZCMbG7iTVmLOWuwspi4DeM5p2Y5BskONFF_beTY,5513
-nighthawk/oversight.py,sha256=xCuJ5kARG0P2KS0eaf4pHqvkUYVgSULNqB-QLXEKxGU,5762
+nighthawk/lifecycle.py,sha256=X8y_xNjROcoFTr3jErPdH666sebnyNl8BRTpNcSItxw,5505
+nighthawk/oversight.py,sha256=e_qOpHV_dEX0gJAge3YC20t0kv_42A_ko_Ym50zx2vQ,6691
 nighthawk/testing.py,sha256=yJE2ru0igXknjN2CCpLur2XGSCGI-ww_58Y8XK4h4iw,8045
 nighthawk/ulid.py,sha256=CBpGLXDGm2j69Yk15hEq4Z5V8StWOY4714ow4BZn5tc,546
 nighthawk/backends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -16,11 +16,11 @@ nighthawk/backends/claude_code_cli.py,sha256=QntuxO2hJBstLJTmoA7Wk2SWdI-_1RnTEoC
 nighthawk/backends/claude_code_sdk.py,sha256=v_KkBV-gSjh0VJ0Y1551GlxrsGOIBErbkPjZ4c8ippQ,13470
 nighthawk/backends/claude_code_settings.py,sha256=wjHf8P38yrOvbhqUVT3uZ1qFjLlMIQ9de8DKHcRJn1g,1061
 nighthawk/backends/codex.py,sha256=6uYw7FGQYkVtwe34TseOw12Ip8tGN78RZ4N2F9rgdVE,15101
-nighthawk/backends/mcp_boundary.py,sha256=TZT1XF7Xknk1cbnrYtwN1KuILUt3EgnZbAIgXH5Nnv0,9444
-nighthawk/backends/mcp_server.py,sha256=6RL2OZOmfdDb-C2B6FYrAkPI_y5tWJ0P58FHKiODQzQ,8315
+nighthawk/backends/mcp_boundary.py,sha256=9A3MtJKocm4NNwKCAIs2I9VFyBVtnxjwEm33dKHddTI,10518
+nighthawk/backends/mcp_server.py,sha256=stAqpAOvY7Mkte1cDmet0_rbIEjMERacg5hRi-zB6CM,8059
 nighthawk/backends/process_management.py,sha256=ExPDyyJ7qFDzNe_1qEfiTM_s1ByAL9XXAm1yEwLFld0,776
 nighthawk/backends/text_projection.py,sha256=4qhugWdDXuwGNpTTuAEZge-8PMPKtAMypo66iziDB0I,12034
-nighthawk/backends/tool_bridge.py,sha256=2EhhmYIXNE35j7sltG6TZc-Iq_0nK8vdzAWOHSkmBAc,10530
+nighthawk/backends/tool_bridge.py,sha256=x2fXovrbgEYiSg_UmtT09hjkkvRIq7MfBJrL0gCCv4I,11741
 nighthawk/backends/tool_transport.py,sha256=iknOFt6tgi47Pfru2vQmQJuA8UPmyoCiFL1kO9J2sS0,3537
 nighthawk/natural/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nighthawk/natural/_names.py,sha256=zWXgVLbsFqzxDnQdlGtJamt0zUL8GlZckvECi5FEm70,916
@@ -35,7 +35,7 @@ nighthawk/resilience/_fallback.py,sha256=oqmmmGKe2BgQUWGEdBuMYTEFalnjUllYDHwSBa-
 nighthawk/resilience/_retry.py,sha256=9Rq8EpdtW_3B_-QmEzn7nJ2G4QdUJE7KXuvuMNRY14k,8462
 nighthawk/resilience/_timeout.py,sha256=j1FPvnQB3XtjH-7UVu7Cp4ujDtF5qQOWFcO_YOrth5I,4024
 nighthawk/resilience/_vote.py,sha256=rV2x8AkmoZJLAjUOfOV5SUa45NeZYo0kYic8lPuugXE,4675
-nighthawk/runtime/__init__.py,sha256=Z7aw3s29yxhz5yRXbJ2LQy1jmKN6z_Aq0z3YwoFFIBA,3093
+nighthawk/runtime/__init__.py,sha256=SipxZoD-LoQIGhiacTKWK_NfMtRwWaSlBiIWaFquCnM,3456
 nighthawk/runtime/_user_content.py,sha256=Vnt5Nbbk0I02m06ng8OtooE0Ph0Qqc3twzqbjsDUA6Q,3122
 nighthawk/runtime/annotations.py,sha256=TPjBz8-DZ9BjXSrRLlUqKVq4mGTvKBffPwHoHWdN8EA,3029
 nighthawk/runtime/assignment.py,sha256=hCMrLpfN7Z3CuE56co1uemJn0nhMwO0tDwYnlQTPqcs,6486
@@ -51,30 +51,31 @@ nighthawk/runtime/expression.py,sha256=421HuL53GGEKW1Tuag9VRRcJffmPShpJ0rTRmZYkx
 nighthawk/runtime/inspection.py,sha256=06zWKw_u61585qc-Wp1QmvKAekydWoCcmaDEU22Hdbw,3454
 nighthawk/runtime/interruption.py,sha256=9B3hjMbXXtjf1sP2qVAf10dWk0KDS_UttZwqaix1tFU,679
 nighthawk/runtime/model_candidate.py,sha256=X0aJvlk9zSDTwU6KCnYLBnOuiKab-E4IqVEeypvljhs,3122
+nighthawk/runtime/model_response.py,sha256=CcdJE440LJgvbmS3YpE6dv9BHvkWnl_9zpUdwgqsUKc,1565
 nighthawk/runtime/notifications.py,sha256=khLidCGr9lc2aed_GwGiWaUOx6jNQepGqY0_a6flJWo,1449
-nighthawk/runtime/operation_contract.py,sha256=zTZTQXrv6xpUgJxUIGB3xVFDQZ0NglgmdU30aFbOf9Q,2471
-nighthawk/runtime/operations.py,sha256=OQ15NKnSs2NSUgRxFALzS6bRCWPgbzNrjXCOOW6GH7A,6706
+nighthawk/runtime/operation_contract.py,sha256=h_wDoz780Jrr9lJbTyZHWRaq_RjP_qk3h3-3arceT_U,3596
+nighthawk/runtime/operations.py,sha256=5IkgJJAX3nwv4t_AKAVyT-oFUjCPjUTYzaqdDVTc7J0,8010
 nighthawk/runtime/preparation.py,sha256=zLrnP53k7PrKv4gTYf_RJDB2dOEbI_KxB7JSqPzG0EM,11396
 nighthawk/runtime/prompt.py,sha256=ihKOoMEWiTKX6SsyXiAvXydPfgnIAQBrBhDsBib2_ak,29750
-nighthawk/runtime/runner.py,sha256=I5A2CnqzxcWAmIQlGO46h5p460RB_ibHxnLktDj0g7c,27097
+nighthawk/runtime/runner.py,sha256=prIcoi6rZrSfA09YkO_ajDoXSqN1FmIJ2fD46rhvlLQ,27587
 nighthawk/runtime/scoping.py,sha256=94l8lW9UWDSAh4e1-lG1GOt3l7vlm_KMfAcCTbGGCM0,21623
-nighthawk/runtime/step_context.py,sha256=DM7mHCiiFhulUAqS6qK7TAZLHfOe-ZqRtZHkEwj22OE,5836
+nighthawk/runtime/step_context.py,sha256=k5oy_0GgWS4XeLiY7C-UQ9IVnQ7JSZEoR3Iyz-7pUp0,5972
 nighthawk/runtime/step_contract.py,sha256=xIQcpD1PDY_gqrTqSUZ_5yZoMQt1EJOU33fpn-Da_28,6737
 nighthawk/runtime/step_definition.py,sha256=f64IVSAfpbxUpFVdIKBuWW43m2sQRQDvVmFgBrQeKbE,1913
-nighthawk/runtime/step_executor.py,sha256=Q7Teu6mUrForLi1q6Q570ZRkP44KZ-9KoodUUXnJEXs,16089
+nighthawk/runtime/step_executor.py,sha256=QP23Cv91Xc_EC7iWIcGinb1219amaX-zWUg6VuSJuns,17818
 nighthawk/runtime/step_request.py,sha256=qs_kJZ_SqvYSD4yTs-5jSoHVrTbVT27YxWUFHeLHLjM,4508
 nighthawk/runtime/step_result.py,sha256=mCdteQgQMMwoYTvhCJLuwcctljw-rjjyoFy2awfiRRg,1678
 nighthawk/runtime/tool_calls.py,sha256=IZQWk2IH8rPF6hjVBzBDn0cpGDkG9k368dDFpmquYOg,3318
 nighthawk/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nighthawk/tools/_admission.py,sha256=T4W3n8Y36Q4CnAE01W85ftbd16Z1W7xjfqwn2qMXZFs,4075
-nighthawk/tools/_ordering.py,sha256=BhAU0oYcTWfDeF0lA0HY-04drzD5AMlax8uyYry4nOc,3997
+nighthawk/tools/_ordering.py,sha256=rTPKMIN4664EUeyAj-ouf3kjUY3sIATdXUOYBGCWKGU,12270
 nighthawk/tools/_tool_return_content.py,sha256=HlDDufHvMvqHfw3-L5fqQYM3s4qxaWz8GFjgNkHcg8s,2111
 nighthawk/tools/assignment.py,sha256=Uai4UCw0IICssmNRJvUkdPTX9QWXnyLIASVbw8c3PFk,1254
-nighthawk/tools/contracts.py,sha256=X-YixPwBun0FmjiyPPNCXPW2pJf7CpmWR7jyTVJQvsM,5325
+nighthawk/tools/contracts.py,sha256=xMrNjIducxIzcMn9o3zPoZN-Q8FPTSceCqZO-zk5qwA,5784
 nighthawk/tools/declarations.py,sha256=goPDT7iVaXez11R_9z8e4czeeA7wevmZPs8sO85hqdA,3986
-nighthawk/tools/execution.py,sha256=IeZs32tUSLJkj7_M94vrWh0Xt1CkJgvoUike9iIKe1I,6720
+nighthawk/tools/execution.py,sha256=8knipGL3SpjY9X-wPrGzC6_-USpWjXJtv0-JrzcnX-M,8068
 nighthawk/tools/provided.py,sha256=H17PoX8ztUmtgrBkB-bEdfDkK5OSULIl_tyMgzEc3g4,1958
-nighthawk_python-0.16.0.dist-info/METADATA,sha256=g2-niQ9VaMFvMMN3Rn0advG6wBR-Oume9kwYaC_UvjI,6147
-nighthawk_python-0.16.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-nighthawk_python-0.16.0.dist-info/licenses/LICENSE,sha256=R8tjrX79o5Pbi_l_aFPPWDbTZkmz4is0CxmzMMs3f0A,1076
-nighthawk_python-0.16.0.dist-info/RECORD,,
+nighthawk_python-0.17.0.dist-info/METADATA,sha256=I7pUiaTPLhW00Q032Wa1R1REheYK9DBejKQw6PVIj98,6147
+nighthawk_python-0.17.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nighthawk_python-0.17.0.dist-info/licenses/LICENSE,sha256=R8tjrX79o5Pbi_l_aFPPWDbTZkmz4is0CxmzMMs3f0A,1076
+nighthawk_python-0.17.0.dist-info/RECORD,,