nighthawk-python 0.15.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/composition.py

@@ -1,4 +1,4 @@
-"""Explicit inheritance and composition operations for execution scopes."""
+"""Omitted arguments and explicit collection composition operations."""
 
 from __future__ import annotations
 
@@ -30,7 +30,11 @@ class UnsetType:
 
 
 UNSET = UnsetType()
-"""Inherit the enclosing scope value; also marks omitted rewrite fields."""
+"""An omitted argument: use the receiving API's documented default behavior.
+
+Scopes inherit, runs create fresh resources, and rewrites retain the current field.
+Ordinary values, including empty collections, remain explicit values.
+"""
 
 
 @dataclass(frozen=True, init=False)

nighthawk/configuration.py

@@ -121,8 +121,9 @@ class StepExecutorConfiguration(BaseModel):
             Instances retain identity; the host owns client lifetime. Serialization
             must explicitly exclude a live model field, including in nested records.
             Configuration representations omit the model to avoid traversing credentials.
-        model_settings: Provider-specific model settings. Accepts a dict or a
-            backend-specific BaseModel instance (auto-converted to dict).
+        model_settings: Provider-specific overrides. Defaults to an empty dict;
+            accepts a dict or a backend-specific BaseModel (converted to dict).
+            None and UNSET are invalid. An empty dict preserves model-owned defaults.
         prompts: Prompt templates for step execution.
         context_limits: Token and item limits for context rendering.
         json_renderer_style: Headson rendering style for JSON summarization.
@@ -136,11 +137,11 @@ class StepExecutorConfiguration(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     model: str | InstanceOf[Model] = Field(default="openai-responses:gpt-5.6-luna", repr=False)
-    model_settings: dict[str, Any] | BaseModel | None = None
+    model_settings: dict[str, Any] | BaseModel = Field(default_factory=dict)
 
     @field_validator("model_settings", mode="before")
     @classmethod
-    def _normalize_model_settings(cls, value: Any) -> dict[str, Any] | None:
+    def _normalize_model_settings(cls, value: Any) -> dict[str, Any]:
         if isinstance(value, BaseModel):
             return value.model_dump()
         return value

nighthawk/function_call.py

@@ -10,8 +10,9 @@ from contextlib import contextmanager, nullcontext
 from contextvars import ContextVar
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Any, Protocol
+from typing import Any, Protocol, runtime_checkable
 
+from .composition import UNSET, UnsetType
 from .configuration import ModelSelection
 from .errors import NighthawkError
 from .natural.definition import NaturalFunctionDefinition
@@ -31,6 +32,7 @@ class FunctionCall:
     model_selection: ModelSelection | None
 
 
+@runtime_checkable
 class FunctionCallHandler(Protocol):
     """Application-owned admission, grouping, and observation of function calls."""
 
@@ -48,9 +50,19 @@ _call: ContextVar[FunctionCall | None] = ContextVar("nighthawk_function_call", d
 
 
 @contextmanager
-def function_call_scope(handler: FunctionCallHandler | None) -> Iterator[None]:
-    """Install or explicitly clear interception independently of executor runs."""
-    token = _handler.set(handler)
+def function_call_scope(handler: FunctionCallHandler | None | UnsetType = UNSET) -> Iterator[None]:
+    """Inherit, replace, or clear interception independently of executor runs.
+
+    Omission or UNSET inherits; None clears; a handler replaces the current one.
+    Invalid handlers fail before context installation.
+    """
+    if (
+        not isinstance(handler, UnsetType)
+        and handler is not None
+        and (not isinstance(handler, FunctionCallHandler) or not callable(handler.invoke) or not callable(handler.invoke_async))
+    ):
+        raise TypeError("handler must implement FunctionCallHandler, be None, or be UNSET")
+    token = _handler.set(_handler.get() if isinstance(handler, UnsetType) else handler)
     try:
         yield
     finally:

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,17 +75,38 @@ 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:
-    """Replace supplied commit fields; UNSET inherits and Return(None) returns None.
+    """Replace supplied commit fields; UNSET retains and Return(None) returns None.
 
     A mapping replaces all writes. Use outcome=Return(value=...) to supply
     a new return value or change another allowed outcome into a return.
     Replacements are validated before commit without replaying return expressions.
+    A resolved Raise cannot be paired with an explicit nonempty output mapping.
     """
 
     outcome: StepResult | UnsetType = UNSET
@@ -96,19 +117,22 @@ class Rewrite:
         if not isinstance(self.outcome, (UnsetType, Pass, Return, Break, Continue, Raise)):
             raise TypeError("Rewrite outcome must be a resolved StepResult or UNSET")
         if not isinstance(self.binding_name_to_value, UnsetType):
-            if not isinstance(self.binding_name_to_value, Mapping):
-                raise TypeError("Rewrite binding_name_to_value must be a mapping or UNSET")
+            if not isinstance(self.binding_name_to_value, Mapping) or any(not isinstance(name, str) for name in self.binding_name_to_value):
+                raise TypeError("Rewrite binding_name_to_value must be a string-keyed mapping or UNSET")
             object.__setattr__(self, "binding_name_to_value", _reference_mapping(self.binding_name_to_value))
         if self.outcome is UNSET and self.binding_name_to_value is UNSET:
             raise ValueError("Rewrite must change outcome or binding_name_to_value")
+        if isinstance(self.outcome, Raise) and not isinstance(self.binding_name_to_value, UnsetType) and len(self.binding_name_to_value):
+            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
 
 
@@ -150,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/environment.py

@@ -5,13 +5,21 @@ from __future__ import annotations
 from collections.abc import Iterator, Mapping
 from dataclasses import dataclass
 from types import CellType, MappingProxyType
-from typing import Literal
+from typing import Literal, Never
 
 from .bindings import MISSING_ANNOTATION
 from .description import annotation_text
 from .discovery import DiscoveryResult, page_names
 
-type EnvironmentSource = Literal["effective", "python", "parent", "task", "step"]
+type EnvironmentSource = Literal["effective", "python", "task", "step"]
+
+_EMPTY_NAME_TO_VALUE: Mapping[str, Never] = MappingProxyType({})
+
+
+def _copy_name_to_value[T](name_to_value: Mapping[str, T], parameter: str) -> dict[str, T]:
+    if not isinstance(name_to_value, Mapping) or any(not isinstance(name, str) for name in name_to_value):
+        raise TypeError(f"{parameter} must be a string-keyed mapping")
+    return dict(name_to_value)
 
 
 class MissingEnvironmentNameError(NameError):
@@ -63,6 +71,16 @@ class _ExpressionNamespace(dict[str, object]):
             return self._override_name_to_value[name]
         return self._environment.resolve(name)
 
+    def __contains__(self, name: object) -> bool:
+        # Python 3.14 forward references check membership before looking up a name.
+        if not isinstance(name, str):
+            return False
+        try:
+            self[name]
+        except MissingEnvironmentNameError:
+            return False
+        return True
+
 
 @dataclass(frozen=True)
 class _RuntimeAccess:
@@ -78,7 +96,7 @@ class _RuntimeAccess:
 class StepEnvironment:
     """Read-only environment views with a separate, tracked working namespace.
 
-    Parent membership and object associations are captured at entry.
+    Python working associations and scoped task references are captured at entry.
     Application values remain live; the views do not freeze their object graphs.
     """
 
@@ -88,28 +106,29 @@ class StepEnvironment:
         python_name_to_value: Mapping[str, object],
         python_globals: dict[str, object],
         local_name_set: frozenset[str] = frozenset(),
-        python_name_to_cell: Mapping[str, CellType] | None = None,
-        parent_name_to_value: Mapping[str, object] | None = None,
-        task_name_to_value: Mapping[str, object] | None = None,
+        python_name_to_cell: Mapping[str, CellType] = _EMPTY_NAME_TO_VALUE,
+        task_name_to_value: Mapping[str, object] = _EMPTY_NAME_TO_VALUE,
         output_name_set: frozenset[str] = frozenset(),
-        binding_name_to_annotation: Mapping[str, object] | None = None,
-        binding_name_to_type: Mapping[str, object] | None = None,
+        binding_name_to_annotation: Mapping[str, object] = _EMPTY_NAME_TO_VALUE,
+        binding_name_to_type: Mapping[str, object] = _EMPTY_NAME_TO_VALUE,
         runtime_name_set: frozenset[str] = frozenset(),
     ) -> None:
+        python_name_to_value = _copy_name_to_value(python_name_to_value, "python_name_to_value")
+        if not isinstance(python_globals, dict) or any(not isinstance(name, str) for name in python_globals):
+            raise TypeError("python_globals must be a string-keyed dict")
         self._runtime_name_set = frozenset(runtime_name_set)
         self._python_name_to_value = {name: value for name, value in python_name_to_value.items() if not self._is_runtime_name(name)}
         self._python_global_name_to_value = python_globals
         builtins_value = python_globals.get("__builtins__", __builtins__)
         self._python_builtin_name_to_value: dict[str, object] = builtins_value if isinstance(builtins_value, dict) else vars(builtins_value)
         self._local_name_set = local_name_set
-        self._python_name_to_cell = dict(python_name_to_cell or {})
+        self._python_name_to_cell = _copy_name_to_value(python_name_to_cell, "python_name_to_cell")
         self._output_name_set = output_name_set
         self._step_name_to_value: dict[str, object] = {}
-        self._binding_name_to_annotation = dict(binding_name_to_annotation or {})
-        self._binding_name_to_type = dict(binding_name_to_type or {})
+        self._binding_name_to_annotation = _copy_name_to_value(binding_name_to_annotation, "binding_name_to_annotation")
+        self._binding_name_to_type = _copy_name_to_value(binding_name_to_type, "binding_name_to_type")
         self.python_name_to_value: Mapping[str, object] = _PythonEnvironmentView(self)
-        self.parent_name_to_value = MappingProxyType(dict(parent_name_to_value or {}))
-        self.task_name_to_value = MappingProxyType(dict(task_name_to_value or {}))
+        self.task_name_to_value = MappingProxyType(_copy_name_to_value(task_name_to_value, "task_name_to_value"))
         self.step_name_to_value = MappingProxyType(self._step_name_to_value)
         known_names = (
             python_name_to_value.keys()
@@ -117,7 +136,6 @@ class StepEnvironment:
             | self._python_builtin_name_to_value.keys()
             | self._local_name_set
             | self._python_name_to_cell.keys()
-            | self.parent_name_to_value.keys()
             | self.task_name_to_value.keys()
             | self._runtime_name_set
         )
@@ -166,7 +184,6 @@ class StepEnvironment:
         source_to_name_to_value = {
             "step": self.step_name_to_value,
             "python": self.python_name_to_value,
-            "parent": self.parent_name_to_value,
             "task": self.task_name_to_value,
         }
         if source != "effective" and source not in source_to_name_to_value:
@@ -188,19 +205,25 @@ class StepEnvironment:
         self._step_name_to_value[name] = value
 
     def snapshot_working_state(self) -> dict[str, object]:
-        snapshot = dict(self.parent_name_to_value)
+        """Copy this step's bound working names for explicit application-owned sharing.
+
+        Include Python locals, live cells, and tracked assignments.
+        Exclude module globals, builtins, scoped task references, and runtime names.
+        Referenced objects retain identity; the returned mapping is independent.
+        """
+        name_to_value: dict[str, object] = {}
         for name in self._python_name_to_value.keys() | self._local_name_set | self._python_name_to_cell.keys():
             if self._is_runtime_name(name):
                 continue
             try:
-                snapshot[name] = self._resolve_python(name)
+                name_to_value[name] = self._resolve_python(name)
             except (KeyError, UnboundLocalError):
-                snapshot.pop(name, None)
-        snapshot.update(self.step_name_to_value)
-        return snapshot
+                continue
+        name_to_value.update(self.step_name_to_value)
+        return name_to_value
 
-    def expression_namespace(self, overrides: Mapping[str, object] | None = None) -> dict[str, object]:
-        return _ExpressionNamespace(self, overrides or {})
+    def expression_namespace(self, overrides: Mapping[str, object] = _EMPTY_NAME_TO_VALUE) -> dict[str, object]:
+        return _ExpressionNamespace(self, _copy_name_to_value(overrides, "overrides"))
 
     def reference(self, name: str, *, source: EnvironmentSource = "effective") -> str:
         """Return a Python expression resolving this binding when evaluated."""
@@ -208,18 +231,17 @@ class StepEnvironment:
 
     def discover(self, *, source: EnvironmentSource = "effective", cursor: str | None = None, max_items: int = 8) -> dict[str, object]:
         """List names with provenance, usable references, and progressing pages."""
-        source_to_view = {
+        source_to_name_to_value = {
             "python": self.python_name_to_value,
-            "parent": self.parent_name_to_value,
             "task": self.task_name_to_value,
             "step": self.step_name_to_value,
         }
-        if source != "effective" and source not in source_to_view:
-            return {"error": "Unknown source", "recovery": "Choose effective, python, parent, task, or step."}
+        if source != "effective" and source not in source_to_name_to_value:
+            return {"error": "Unknown source", "recovery": "Choose effective, python, task, or step."}
         names = (
-            tuple(sorted(set().union(*[set(view) for view in source_to_view.values()])))
+            tuple(sorted(set().union(*[set(view) for view in source_to_name_to_value.values()])))
             if source == "effective"
-            else tuple(sorted(source_to_view[source]))
+            else tuple(sorted(source_to_name_to_value[source]))
         )
         page = page_names(names, source=source, cursor=cursor, max_items=max_items)
         if page.error is not None:
@@ -244,7 +266,6 @@ class StepEnvironment:
             for source, view in (
                 ("step", self.step_name_to_value),
                 ("python", self.python_name_to_value),
-                ("parent", self.parent_name_to_value),
                 ("task", self.task_name_to_value),
             )
             if name in view

nighthawk/runtime/expression.py

@@ -38,7 +38,7 @@ async def evaluate_compiled_expression(
     allow_awaitable_result: bool = True,
     override_name_to_value: Mapping[str, object] | None = None,
 ) -> object:
-    namespace = step_context.environment.expression_namespace(override_name_to_value)
+    namespace = step_context.environment.expression_namespace({} if override_name_to_value is None else override_name_to_value)
     try:
         value = eval(compiled, namespace, namespace)
         if inspect.isawaitable(value):

nighthawk/runtime/model_candidate.py

@@ -2,6 +2,7 @@
 
 from collections.abc import Mapping
 
+from ..composition import UNSET, UnsetType
 from ..errors import ExecutionError
 from .expression import evaluate_expression_operation
 from .operation_contract import OperationError
@@ -13,14 +14,21 @@ from .step_result import Break, Continue, Pass, Raise, Return, StepResult
 async def resolve_model_candidate(
     request: StepRequest,
     outcome: StepOutcome,
-    binding_name_to_value: Mapping[str, object],
+    binding_name_to_value: Mapping[str, object] | UnsetType = UNSET,
 ) -> StepCandidate:
     """Resolve a provider response once; leave commit validation to the runner."""
     if outcome.kind not in request.allowed_step_kinds:
         raise ExecutionError(f"Step '{outcome.kind}' is not allowed for this step. Allowed kinds: {request.allowed_step_kinds}")
-    undeclared = binding_name_to_value.keys() - set(request.output_binding_names)
+    if not isinstance(binding_name_to_value, UnsetType) and (
+        not isinstance(binding_name_to_value, Mapping) or any(not isinstance(name, str) for name in binding_name_to_value)
+    ):
+        raise TypeError("binding_name_to_value must be a string-keyed mapping or UNSET")
+    supplied_name_to_value = {} if isinstance(binding_name_to_value, UnsetType) else dict(binding_name_to_value)
+    undeclared = supplied_name_to_value.keys() - set(request.output_binding_names)
     if undeclared:
         raise ExecutionError(f"Undeclared output binding names: {sorted(undeclared)}")
+    if isinstance(outcome, RaiseStepOutcome) and supplied_name_to_value:
+        raise ExecutionError("Raise cannot include output bindings")
     resolved: StepResult
     if isinstance(outcome, ReturnStepOutcome):
         value = await evaluate_expression_operation(
@@ -29,7 +37,7 @@ async def resolve_model_candidate(
             purpose="return",
             allow_awaitable_result=request.allow_awaitable_return,
             expected_type=request.return_annotation,
-            override_name_to_value=binding_name_to_value,
+            override_name_to_value=supplied_name_to_value,
         )
         resolved = Return(value)
     elif isinstance(outcome, RaiseStepOutcome):
@@ -46,4 +54,4 @@ async def resolve_model_candidate(
         resolved = Raise(outcome.raise_message, error_type)
     else:
         resolved = {"pass": Pass, "break": Break, "continue": Continue}[outcome.kind]()
-    return StepCandidate(outcome=resolved, binding_name_to_value=binding_name_to_value)
+    return StepCandidate(outcome=resolved, binding_name_to_value=UNSET if isinstance(binding_name_to_value, UnsetType) else supplied_name_to_value)