nighthawk-python 0.8.0__tar.gz → 0.10.0__tar.gz

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/.github/workflows/docs.yml

@@ -46,4 +46,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0]
+
+### Added
+- Scope-level oversight hooks in `nh.scope(oversight=...)` for synchronous tool-call inspection and step-commit inspection.
+- Oversight trace events and backend/wrapper coverage for accept/reject decision paths.
+- Validation for `vote(min_success=...)` bounds (`>= 1` and `<= count`) with matching tests.
+- Tool-boundary regression test ensuring recoverable `ToolBoundaryError` is wrapped into JSON payload.
+
+### Changed
+- Finalized committed binding validation at step boundaries, added write-root dirty tracking for dotted `nh_assign`, and aligned prompt/docs with the new validation contract.
+- Introduced `ExecutionRef` (`run_id`, `scope_id`, optional `step_id`) and renamed runtime accessor to `get_execution_ref`.
+- Added top-level module access for `oversight` and `resilience`, with docs and public API tests aligned.
+- Consolidated tool-call oversight inspection to a single wrapper-side entry point and removed duplicate inspection guard state.
+- Unified tool result handling to TypedDict-based envelope types (`ToolResult`, `ToolError`) instead of Pydantic models.
+- Clarified tool-boundary policy: recoverable tool-call failures are JSON-envelope responses, host invariant violations propagate as Python exceptions.
+- Updated specification and runtime configuration docs to codify envelope-vs-raise boundary semantics for tool-call failures.
+- Updated API and patterns docs for `ExecutionRef`, `get_execution_ref`, and oversight/resilience namespace exposure.
+
+### Fixed
+- Backend handler now preserves wrapped tool error payloads (`{"value": ..., "error": ...}`) without dropping error details.
+- Tool-call context propagation now preserves step identity in execution ref during step execution.
+
+## [0.9.0]
+
+### Changed
+
+- Redesigned `nh.scope()` around `mode` semantics (`"inherit"` default, `"replace"` for explicit replacement).
+- Scope prompt suffix arguments now use list-based forms: `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments`.
+
+### Removed
+- Removed `step_executor_configuration_patch` from `nh.scope()`.
+- Removed `StepExecutorConfigurationPatch` from the public API.
+
+### Fixed
+- Clarified and aligned docs/tests for scope merge vs replace behavior.
+
 ## [0.8.0]
 
 ### Added
@@ -127,7 +163,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.0...v0.6.1

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.8.0
+Version: 0.10.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.8.0 → nighthawk_python-0.10.0}/docs/api.md

@@ -14,17 +14,18 @@
         - scope
         - AgentStepExecutor
         - StepExecutorConfiguration
-        - StepExecutorConfigurationPatch
         - StepPromptTemplates
         - StepContextLimits
         - JsonableValue
         - to_jsonable_value
-        - ExecutionContext
+        - ExecutionRef
         - get_current_step_context
         - get_current_usage_meter
-        - get_execution_context
+        - get_execution_ref
         - get_step_executor
+        - resilience
         - UsageMeter
+        - oversight
 
 ## Errors
 
@@ -124,4 +125,3 @@
 ## Testing
 
 ::: nighthawk.testing
-

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/docs/for-coding-agents.md

@@ -146,8 +146,12 @@ with nh.run(fast_executor):
         report = write_analysis_report(ticket_text, product_summary)
 ```
 
-`implicit_references` can inject global helper functions as block capabilities.
-Nested scopes still merge additively (set union by key).
+- `implicit_references` inject helper functions as block capabilities.
+- `nh.scope()` must run inside `nh.run()`; it keeps `run_id` and creates a new `scope_id`.
+- `mode` affects only `system_prompt_suffix_fragments`, `user_prompt_suffix_fragments`, and `implicit_references`.
+- `inherit`: suffix lists append; `implicit_references` merge with conflict check (same key + different object => `NighthawkError`).
+- `replace`: explicit list/mapping fully replace; `[]`/`{}` clear; `None` keeps inherited value.
+- `step_executor` / `step_executor_configuration` are resolved independently of `mode`.
 
 ## 4. The standard contract shape
 
@@ -323,7 +327,7 @@ Async rule:
 Resilience rule:
 
 - Keep retry, fallback, timeout, budget, and circuit-breaker policy in Python, not inside Natural text.
-- Import from `nighthawk.resilience` (not re-exported from `nighthawk`):
+- Import primitives from `nighthawk.resilience`. After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`:
 
 ```py
 from nighthawk.resilience import retrying

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/docs/natural-blocks.md

@@ -129,7 +129,7 @@ def detect_language(text: str):
     return language
 ```
 
-Type annotations on write bindings enable validation and coercion at commit time.
+Type annotations on write bindings enable validation and coercion at step finalization for values that are actually committed.
 
 ### Pydantic model write bindings
 

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/docs/patterns.md

@@ -326,7 +326,8 @@ Natural blocks are non-deterministic by nature. Production deployments need stra
 from nighthawk.resilience import retrying, fallback, vote, timeout, budget, circuit_breaker
 ```
 
-Import directly from `nighthawk.resilience`. Resilience primitives are not re-exported from the top-level `nighthawk` namespace.
+Import directly from `nighthawk.resilience`.
+After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`.
 
 ### Retrying
 

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/docs/philosophy.md

@@ -23,7 +23,7 @@ calculate_average([1, "2", "three", "cuatro", "五"])  # 3.0
 
 Binding functions like `<python_average>` appear in the prompt as a compact signature line. The LLM's pre-trained Python knowledge lets it reason about types, return values, and composition from the signature alone, without JSON Schema or protocol overhead. See [Tool exposure efficiency](#tool-exposure-efficiency) for the quantitative comparison with MCP and CLI tool exposure.
 
-With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates the type annotation at runtime, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
+With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates committed write bindings at step finalization, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
 
 With [coding agent backends](coding-agent-backends.md), the same boundary contract applies, but each Natural block becomes an autonomous agent execution. The agent can read files, run commands, and invoke skills -- while typed bindings enforce what crosses the boundary back to Python. The same `scope()` and `run()` context managers that structure human-written workflows are equally legible to a coding agent constructing workflows programmatically. When a coding agent operates inside a Natural block, binding functions appear as Python signatures in the prompt:
 

nighthawk_python-0.10.0/docs/runtime-configuration.md

@@ -0,0 +1,252 @@
+# Runtime configuration
+
+> This page assumes you have completed [Executors](executors.md).
+
+This page covers how to configure execution at runtime: scoping modes, prompt suffix fragments, context limits, JSON rendering, and execution identity. These settings are independent of executor choice and apply equally to Pydantic AI providers and coding agent backends.
+
+## Scoped overrides with `nh.scope()`
+
+Use `nh.scope()` to override execution settings within an existing run. Each scope generates a new `scope_id` while keeping the current `run_id`.
+
+```py
+with nh.run(step_executor):
+
+    # Inherit mode (default): merge/append into current scope state
+    with nh.scope(
+        step_executor_configuration=nh.StepExecutorConfiguration(
+            model="openai-responses:gpt-5.4-mini",
+        ),
+    ) as scoped_executor:
+        expensive_analysis(data)
+
+    # Replace mode: replace only explicitly provided values
+    # None means "no change". [] / {} means "clear".
+    with nh.scope(
+        mode="replace",
+        system_prompt_suffix_fragments=["Always respond in formal English."],
+        implicit_references={},
+    ):
+        formal_summary(text)
+
+    # Replace the step executor entirely for a section
+    with nh.scope(step_executor=another_executor):
+        specialized_step(data)
+
+    # Add implicit global references for this scope
+    with nh.scope(implicit_references={"search_repository": search_repository}):
+        typed_labeling_step(ticket_text)
+
+    # Add synchronous oversight for this scope
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
+```
+
+Parameters:
+
+- `mode`: scope composition mode. Default: `"inherit"`.
+- `step_executor_configuration`: replace the entire configuration.
+- `step_executor`: replace the step executor entirely.
+- `oversight`: scope-level synchronous tool-call inspection and step-commit inspection hooks.
+- `system_prompt_suffix_fragments`: scope-level system suffix fragments.
+- `user_prompt_suffix_fragments`: scope-level user suffix fragments.
+- `implicit_references`: scope-level implicit global references.
+
+Mode semantics:
+
+- `mode="inherit"` (default):
+  - `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` are appended.
+  - `implicit_references` are merged additively with conflict checks.
+- `mode="replace"`:
+  - `None` means no change.
+  - Explicit `[]` or `{}` clears inherited list/dict values.
+  - Explicit list/dict values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
+
+For `oversight`, omitted means inherit the current hooks, while explicit `None` clears them for the nested scope.
+
+The context manager yields the resolved `StepExecutor` for the scope.
+
+`StepExecutorConfiguration` also accepts `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` (tuples of strings) as baseline suffix fragments for the whole run. In `mode="inherit"`, scope-level fragments are appended after configuration-level fragments.
+
+## Scoped implicit references
+
+`implicit_references` can inject global helper functions as step capabilities:
+
+```py
+def search_repository(query: str) -> list[str]: ...
+
+with nh.run(step_executor):
+    with nh.scope(implicit_references={"search_repository": search_repository}):
+        triage_issue(ticket_text)
+```
+
+In `mode="inherit"` (default), nested scopes merge additively with conflict checks.
+In `mode="replace"`, explicit mappings fully replace inherited mappings.
+
+```py
+with nh.run(step_executor), nh.scope(implicit_references={"parent": search_repository}):
+    with nh.scope(mode="replace", implicit_references={}):
+        triage_issue(ticket_text)
+```
+
+The inner scope above clears inherited implicit references.
+
+```py
+with nh.scope(mode="replace", implicit_references={"child": search_repository}):
+    triage_issue(ticket_text)
+```
+
+This fully replaces inherited references with the provided mapping.
+
+```py
+with nh.scope(mode="replace", implicit_references=None):
+    triage_issue(ticket_text)
+```
+
+This keeps inherited references unchanged.
+
+## Prompt suffix fragments in scopes
+
+Use list values when setting scope-level suffix fragments:
+
+```py
+with nh.run(step_executor):
+    with nh.scope(system_prompt_suffix_fragments=["Use concise answers."]):
+        summarize_ticket(ticket_text)
+```
+
+`user_prompt_suffix_fragments` follows the same rules.
+
+```py
+with nh.scope(user_prompt_suffix_fragments=["Focus on actionable output."]):
+    summarize_ticket(ticket_text)
+```
+
+In `mode="inherit"`, provided lists are appended.
+In `mode="replace"`, provided lists fully replace inherited lists.
+
+```py
+with nh.run(step_executor), nh.scope(system_prompt_suffix_fragments=["parent"]):
+    with nh.scope(mode="replace", system_prompt_suffix_fragments=["child_1", "child_2"]):
+        summarize_ticket(ticket_text)
+```
+
+Pass `[]` to clear inherited fragments.
+
+```py
+with nh.scope(mode="replace", system_prompt_suffix_fragments=[]):
+    summarize_ticket(ticket_text)
+```
+
+Pass `None` to keep inherited fragments unchanged.
+
+```py
+with nh.scope(mode="replace", system_prompt_suffix_fragments=None):
+    summarize_ticket(ticket_text)
+```
+
+The same `replace` semantics apply to `user_prompt_suffix_fragments`.
+
+## Synchronous oversight in scopes
+
+Use `nh.scope(oversight=...)` when the host needs synchronous inspection around tool calls or a final rewrite/reject checkpoint before Nighthawk commits a step result.
+
+```py
+def inspect_tool_call(tool_call: nh.oversight.ToolCall) -> nh.oversight.ToolCallDecision:
+    if tool_call.tool_name == "delete_file":
+        return nh.oversight.Reject("Deletion must be approved by a human.")
+    return nh.oversight.Accept()
+
+
+def inspect_step_commit(proposal: nh.oversight.StepCommitProposal) -> nh.oversight.StepCommitDecision:
+    if "result" in proposal.proposed_binding_name_to_value:
+        return nh.oversight.Rewrite(rewritten_binding_name_to_value={"result": "reviewed"})
+    return nh.oversight.Accept()
+
+
+with nh.run(step_executor):
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
+```
+
+Tool rejections are returned to the model as a normal tool result envelope with `error.kind == "oversight"`. Step rejections raise `nh.oversight.OversightRejectedError` to the host. Rewrite values still flow through the normal step finalization path. For the normative boundary rule on which tool-call failures are envelope-wrapped versus propagated as host exceptions, see [Specification Section 8.3](specification.md#83-tool-boundary-contract-built-in-tooling).
+
+## Mixing executors
+
+Use `nh.scope(step_executor=...)` to switch executors within a single run. This is the standard pattern for mixing a cheap classifier with a deep autonomous step:
+
+```py
+fast_executor = nh.AgentStepExecutor.from_configuration(
+    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini"),
+)
+
+deep_executor = nh.AgentStepExecutor.from_configuration(
+    configuration=nh.StepExecutorConfiguration(model="codex:default"),
+)
+
+with nh.run(fast_executor):
+    label = classify_ticket(text)             # fast, cheap
+    with nh.scope(step_executor=deep_executor):
+        diagnosis = inspect_repository(text)  # deep, autonomous
+```
+
+See [Executors](executors.md#decision-tree) for when to choose a coding agent backend over a provider-backed executor.
+
+## Context limits
+
+The LOCALS and GLOBALS sections are bounded by token and item limits configured via `StepContextLimits`. When a limit is reached, remaining entries are omitted and a `<snipped>` marker is appended. The underlying data remains in Python memory and is accessible through binding functions at runtime -- truncation affects prompt coherence, not data availability.
+
+```py
+configuration = nh.StepExecutorConfiguration(
+    model="openai-responses:gpt-5.4-mini",
+    context_limits=nh.StepContextLimits(
+        locals_max_tokens=4096,
+        locals_max_items=50,
+    ),
+)
+```
+
+See [Specification Section 8.2](specification.md#82-prompt-context) for the full specification.
+
+## JSON rendering style
+
+`StepExecutorConfiguration` also accepts `json_renderer_style`, which controls how values are rendered in prompt context and tool results (e.g., strict JSON vs annotated pseudo-JSON with omission markers). See [Specification Section 5.2](specification.md#52-configuration) for available styles.
+
+## Runtime execution identity
+
+Each `nh.run()` generates an `ExecutionRef` with a unique `run_id` (trace root) and `scope_id`. Nested `nh.scope()` calls generate new `scope_id` values while keeping the same `run_id`.
+
+```py
+execution_ref = nh.get_execution_ref()
+execution_ref.run_id    # trace root -- stable across nested scopes
+execution_ref.scope_id  # current scope -- changes with each nh.scope()
+execution_ref.step_id   # None outside active step execution
+```
+
+Use `run_id` to correlate distributed agent processes in logs and traces. Use `scope_id` to identify the current logical execution context. See [Specification Section 10](specification.md#10-runtime-scoping) for the full specification and [Verification: observability](verification.md#observability) for tracing integration.
+
+## Usage metering
+
+Each `nh.run()` creates a `UsageMeter` that accumulates LLM token usage across all Natural block executions in the run. The meter is thread-safe and updated automatically after each step.
+
+```py
+meter = nh.get_current_usage_meter()   # None outside nh.run()
+if meter is not None:
+    meter.total_tokens     # cumulative input + output tokens
+    meter.snapshot()       # independent RunUsage copy of current totals
+```
+
+`get_current_usage_meter()` returns `None` outside an active `nh.run()` context. Use the meter to inspect cumulative cost at decision points -- for example, to choose a cheaper model mid-pipeline when spend is high. For automatic budget enforcement, see [Patterns: Budget](patterns.md#budget).
+
+## Next steps
+
+Continue to **[Patterns](patterns.md)** for outcomes, error handling, async, cross-block composition, resilience, and common mistakes.

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/docs/specification.md

@@ -91,9 +91,6 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - `json_renderer_style`: [headson](https://github.com/kantord/headson) rendering style used in prompt context and tool result envelopes. Default: `"default"`. Available values: `"strict"` (valid JSON, no annotations), `"default"` (pseudo-JSON with omission markers like `…`), `"detailed"` (JS-like with inline comments such as `// N more`).
     - `system_prompt_suffix_fragments`: optional baseline system prompt suffix fragments for this executor configuration.
     - `user_prompt_suffix_fragments`: optional baseline user prompt suffix fragments for this executor configuration.
-- `StepExecutorConfigurationPatch`
-    - Partial override object for scoped configuration updates.
-    - Supports patching model, model settings, templates, limits, renderer style, tokenizer encoding, and prompt suffix fragment tuples.
 
 ### 5.3. Supporting types
 
@@ -106,17 +103,18 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - Fields: `locals_max_tokens`, `locals_max_items`, `globals_max_tokens`, `globals_max_items`, `value_max_tokens`, `object_max_methods`, `object_max_fields`, `object_field_value_max_tokens`, `tool_result_max_tokens`.
 - `JsonableValue`
     - Type alias for JSON-serializable Python values (`dict | list | str | int | float | bool | None`).
-- `ExecutionContext`
+- `ExecutionRef`
     - Frozen dataclass representing runtime execution identity.
     - `run_id`: the Id of the outermost run (trace root).
     - `scope_id`: the Id of the current scope.
+    - `step_id`: the Id of the current step when available, otherwise `None`.
 
 ### 5.4. Runtime accessors
 
 - `nighthawk.get_current_step_context() -> StepContext`
     - Get the `StepContext` for the currently executing Natural block. Raises if no step is active.
 
-See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_context`).
+See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_ref`).
 
 ## 6. Natural block detection
 
@@ -395,6 +393,7 @@ Eval tool:
 
 - `nh_eval(expression: str) -> object`
     - Evaluate a Python expression and return the result. Use to inspect values, call functions, and mutate objects in-place.
+    - In-place mutations performed via `nh_eval` are not runtime-validated.
     - If the evaluated expression is awaitable, it is awaited before returning.
 
 Binding tool:
@@ -424,13 +423,16 @@ Semantics of `nh_assign`:
     - Traverse attributes for each intermediate segment.
     - Assign using attribute assignment on the final segment.
     - Validation:
-        - Validate only when runtime type metadata is available; otherwise assign without validation.
+        - Validate only the final assigned field when runtime type metadata is available; otherwise assign without validation.
 
 Commit and mutation notes:
 
 - Commit selection is controlled only by `<:name>` bindings.
 - `<:name>` selects which top-level names are committed from `step_locals` into Python locals at Natural block boundaries.
-- Dotted mutation is independent of `<:name>`.
+- Dotted `nh_assign` on a write binding root marks that root as dirty for commit selection.
+- Dotted `nh_assign` on a read binding root does not participate in commit selection.
+- Final validation is applied only to committed write bindings at step finalization.
+- Dotted mutation on read bindings and in-place mutation via `nh_eval` are outside the final validation guarantee.
 
 Write tool return value:
 
@@ -449,6 +451,11 @@ All tool results are wrapped in a JSON envelope with the following structure:
 
 Error kind categories: `invalid_input`, `resolution`, `execution`, `transient`, `internal`.
 
+Boundary rule for tool-call failures:
+
+- If the model can recover by changing tool arguments, choosing another tool, or continuing without the tool, the failure MUST be returned in the JSON envelope (`{"value": null, "error": ...}`).
+- Host invariant violations (for example, broken runtime contract or invalid host-side oversight hook contract) MAY propagate as Python exceptions to the host instead of being envelope-wrapped.
+
 The `value` field is bounded by `context_limits.tool_result_max_tokens` and may be summarized using [headson](https://github.com/kantord/headson) truncation when the full rendering exceeds the token budget. Headson is a structure-aware JSON summarizer: it parses the full JSON tree, then selects representative nodes to produce a compact preview that preserves the shape and key values of the data within a strict byte budget (analogous to `head`/`tail` but for structured data).
 
 Atomicity requirement:
@@ -573,10 +580,11 @@ The required runtime object for step execution is:
 
 - `step_executor` (required): a strategy object responsible for executing steps (Natural blocks).
 
-Runtime execution identity is modeled separately in `ExecutionContext`:
+Runtime execution identity is modeled separately in `ExecutionRef`:
 
 - `run_id`: the Id of the outermost run (trace root). This serves as the golden thread that connects distributed agent processes (e.g. parent, child, grandchild) across process boundaries in observability tools.
 - `scope_id`: the Id of the current (possibly nested) run scope. This serves as the identity of the current logical execution context.
+- `step_id`: the Id of the current step when available. Outside active step execution it is `None`.
 
 Nighthawk does not own workspace filesystem concerns (such as include resolution or host file operations). Those concerns belong to the host application layer that embeds Nighthawk.
 
@@ -585,21 +593,27 @@ API:
 
 - `nighthawk.run(step_executor: StepExecutor, *, run_id: str | None = None)`
     - Replaces the current context step executor with the provided step executor.
-    - Generates a new `ExecutionContext` for the duration of the `with`.
+    - Generates a new `ExecutionRef` for the duration of the `with`.
     - Uses provided `run_id` when given; otherwise generates a new `run_id` (trace root).
     - Always generates a fresh `scope_id`.
     - Can be used even when no step executor is currently set.
-- `nighthawk.scope(*, step_executor_configuration: StepExecutorConfiguration | None = None, step_executor_configuration_patch: StepExecutorConfigurationPatch | None = None, step_executor: StepExecutor | None = None, system_prompt_suffix_fragment: str | None = None, user_prompt_suffix_fragment: str | None = None) -> Iterator[StepExecutor]`
+- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, oversight: Oversight | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
     - Enter a nested scope within the current run.
     - Requires an existing step executor.
     - Generates a new `scope_id` (keeps the current `run_id`).
-    - Only specified fields are overridden for the duration of the `with`.
-    - `system_prompt_suffix_fragment`: optional string appended to the system prompt for the duration of the scope.
-    - `user_prompt_suffix_fragment`: optional string appended to the user prompt for the duration of the scope.
+    - `oversight` omitted means inherit the current hooks; explicit `None` clears them for the nested scope.
+    - `mode="inherit"` (default):
+        - Appends prompt suffix fragment lists.
+        - Merges `implicit_references` additively with conflict checks.
+    - `mode="replace"`:
+        - Replaces provided list/mapping values.
+        - `None` means no change.
+        - Explicit `[]` / `{}` clears inherited list/mapping values.
+        - Explicit list/mapping values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
     - Yields the resolved `StepExecutor` for the scope.
 - `nighthawk.get_step_executor() -> StepExecutor`
     - Get the current step executor. Raises if unset.
-- `nighthawk.get_execution_context() -> ExecutionContext`
+- `nighthawk.get_execution_ref() -> ExecutionRef`
     - Get the current runtime execution identity. Raises if unset.
 
 ### 10.1. Observability contract (OpenTelemetry span/event)

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.8.0"
+version = "0.10.0"
 description = "A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/src/nighthawk/__init__.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
+from . import oversight, resilience
 from .configuration import (
     StepContextLimits,
     StepExecutorConfiguration,
-    StepExecutorConfigurationPatch,
     StepPromptTemplates,
 )
 from .errors import (
@@ -16,15 +16,15 @@ from .errors import (
 )
 from .json_renderer import JsonableValue, to_jsonable_value
 from .natural.decorator import natural_function
-from .runtime.scoping import ExecutionContext, UsageMeter, get_current_usage_meter, get_execution_context, get_step_executor, run, scope
+from .runtime.scoping import ExecutionRef, UsageMeter, get_current_usage_meter, get_execution_ref, get_step_executor, run, scope
 from .runtime.step_context import StepContext, get_current_step_context
 from .runtime.step_executor import AgentStepExecutor, StepExecutor
 from .tools.registry import tool
 
 __all__ = [
     "AgentStepExecutor",
-    "ExecutionContext",
     "ExecutionError",
+    "ExecutionRef",
     "JsonableValue",
     "NaturalParseError",
     "NighthawkError",
@@ -32,7 +32,6 @@ __all__ = [
     "StepContextLimits",
     "StepExecutor",
     "StepExecutorConfiguration",
-    "StepExecutorConfigurationPatch",
     "StepPromptTemplates",
     "ToolEvaluationError",
     "ToolRegistrationError",
@@ -40,9 +39,11 @@ __all__ = [
     "UsageMeter",
     "get_current_step_context",
     "get_current_usage_meter",
-    "get_execution_context",
+    "get_execution_ref",
     "get_step_executor",
+    "oversight",
     "natural_function",
+    "resilience",
     "run",
     "scope",
     "to_jsonable_value",

{nighthawk_python-0.8.0 → nighthawk_python-0.10.0}/src/nighthawk/backends/mcp_server.py

@@ -23,6 +23,7 @@ from pydantic_ai import RunContext
 from pydantic_ai.exceptions import UnexpectedModelBehavior
 from pydantic_ai.tools import ToolDefinition
 
+from ..errors import NighthawkError
 from ..runtime.step_context import (
     DEFAULT_TOOL_RESULT_RENDERING_POLICY,
     StepContext,
@@ -203,7 +204,7 @@ async def mcp_server_if_needed(
     parent_otel_context = otel_context.get_current()
     parent_run_context = get_current_run_context()
     if parent_run_context is None:
-        raise RuntimeError("Codex MCP tool server requires an active RunContext")
+        raise NighthawkError("Codex MCP tool server requires an active RunContext")
     typed_parent_run_context = cast(RunContext[StepContext], parent_run_context)
     tool_result_rendering_policy = typed_parent_run_context.deps.tool_result_rendering_policy
     if tool_result_rendering_policy is None: