nighthawk-python 0.15.0__tar.gz → 0.17.0__tar.gz

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
           persist-credentials: false
 
       # setup-uv publishes no floating major tag since v8, so pin an exact release.
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: "3.13"
           # Same dependency set and cache key as "test (3.13)". Only that job
@@ -32,16 +32,16 @@ jobs:
           save-cache: false
 
       - name: Install dependencies
-        run: uv sync --all-extras --all-groups
+        run: uv sync --locked --all-extras --all-groups
 
       - name: Format check
-        run: uv run ruff format --check .
+        run: uv run --no-sync ruff format --check .
 
       - name: Lint
-        run: uv run ruff check .
+        run: uv run --no-sync ruff check .
 
       - name: Type check
-        run: uv run pyright
+        run: uv run --no-sync pyright
 
   test:
     name: Test (Python ${{ matrix.python-version }})
@@ -49,23 +49,22 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.13", "3.14"]
-    continue-on-error: ${{ matrix.python-version != '3.13' }}
+        python-version: ["3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
       # Sole writer of the per-Python-version dependency cache.
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --all-extras --all-groups
+        run: uv sync --locked --all-extras --all-groups
 
       - name: Run tests
-        run: uv run pytest -q
+        run: uv run --no-sync pytest -q
 
   build:
     name: Build distribution
@@ -78,7 +77,7 @@ jobs:
 
       # Keep packaging and its fresh installation check independent of the
       # source test job's dependency cache.
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: false
 
@@ -87,14 +86,15 @@ jobs:
 
       - name: Verify documented examples against the installed wheel
         run: |
-          uv sync --all-groups
+          uv sync --locked --all-groups
           uv venv "$RUNNER_TEMP/nighthawk-distribution"
           uv pip install --python "$RUNNER_TEMP/nighthawk-distribution/bin/python" dist/*.whl
           NIGHTHAWK_DISTRIBUTION_PYTHON="$RUNNER_TEMP/nighthawk-distribution/bin/python" \
-            uv run pytest -q tests/docs/test_runtime_examples.py
+            uv run --no-sync pytest -q tests/docs/test_runtime_examples.py
 
       - name: Upload distribution artifacts
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: python-package-distributions
           path: dist/
+          if-no-files-found: error

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Deploy docs to GitHub Pages
+name: Build and deploy docs to GitHub Pages
 
 on:
   push:
@@ -8,26 +8,38 @@ on:
       - "src/nighthawk/**"
       - "mkdocs.yml"
       - "pyproject.toml"
+      - "uv.lock"
+      - ".python-version"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/nighthawk/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".python-version"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: pages
-  cancel-in-progress: false
+  group: pages-${{ github.event_name == 'pull_request' && github.ref || 'deployment' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
 
       # setup-uv publishes no floating major tag since v8, so pin an exact release.
-      - uses: astral-sh/setup-uv@v10.0.1
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: "3.13"
           # The docs group is a subset of the cache "test (3.13)" saves under
@@ -35,18 +47,24 @@ jobs:
           save-cache: false
 
       - name: Install dependencies
-        run: uv sync --group docs
+        # The default dev group supplies Ruff for API signature formatting.
+        run: uv sync --locked --group docs
 
       - name: Build docs
-        run: uv run mkdocs build
+        run: uv run --no-sync mkdocs build
 
       - uses: actions/upload-pages-artifact@v5
+        if: github.event_name != 'pull_request'
         with:
           path: site
 
   deploy:
+    if: github.event_name != 'pull_request'
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/.github/workflows/publish.yml

@@ -24,7 +24,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: python-package-distributions
           path: dist/

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0]
+
+### Changed
+
+- Breaking: operation inspection now returns `Accept`, `RejectOperation`, or `AbortStep`. Commit inspection accepts `Accept`, `Rewrite`, or `AbortStep`. Replace terminal `Reject(reason)` decisions with `AbortStep(reason)`; there is no legacy alias or implicit change to recoverable behavior.
+- Breaking: `StepAbortedError` replaces `OversightRejectedError`. Terminal records use `failure_stage="oversight_abort"` and `abort_reason` instead of `oversight_rejection` and `rejection_reason`. Aborted operation records use status `"aborted"`; recoverable refusals use `"rejected"`.
+- Breaking: explicit commit `AbortStep` decisions also propagate `StepAbortedError` instead of an `ExecutionError` wrapper, matching operation inspection; terminal delivery may still supply a host exception.
+- Standard agent output processing resolves candidate expressions before leaving its model loop. Rejected return expressions can be corrected without recreating the step or replaying prior operations.
+- Rejection stops the remaining calls in the same visible model response before argument validation, records them as `"skipped"`, and discards that response's final candidates. Nighthawk makes `early` dispatch follow emission order; ordinary Pydantic AI runs retain their own strategies.
+- MCP/SDK tool responses carry error indicators and structured refusal information. Coding-agent internal batches and inference requests remain outside Core's visible response/request boundaries.
+
+### Added
+
+- `OperationRejection`, `OperationRejectedError`, and exported `OperationDeliveryError` support direct executor recovery and correlated failure diagnostics. Refusals retain live state, earlier effects, request accounting, and ordinary finalization.
+- Deterministic model, executor, lifecycle, ordering, and backend tests cover refusal feedback, skipped calls, cancellation, notification failures, limits, and nested execution. See [operation feedback](docs/operation-feedback.md) for examples and migration details.
+
+## [0.16.0]
+
+### Changed
+
+- Breaking: `StepCandidate` and testing responses distinguish omitted output selection (`UNSET`, select initialized declared outputs) from an explicit complete mapping (`{}`, no writes). Added `StepRequest.snapshot_output_bindings()` for explicit Python composition. `StepResponse` and response factories use `binding_name_to_value`; keyword-expanded output arguments are removed.
+- Breaking: `Raise` rejects explicit nonempty output mappings in candidates and rewrites. Standard agent executors retain automatic output selection and final validation.
+- Breaking: optional executor configuration and run identifiers use `UNSET`; invalid `None`, raw configuration dictionaries, and empty run identifiers fail at entry. Environment mappings reject `None`, and `StepExecutorConfiguration.model_settings` defaults to an empty dictionary.
+- `function_call_scope` now supports omission or `UNSET` for inheritance, `None` for clearing, and validated handler replacement.
+- Breaking: Natural functions no longer copy parent working values into their environment. Share values through Python arguments, globals, closures, or explicit `scope(task_references=...)`; ordinary Python helpers can select references from the active environment. Removed the `parent` name source and `parent_name_to_value` from `StepEnvironment` and test-call records.
+- Documented explicit working-state snapshots, scoped reference replacement and clearing, and synchronous/asynchronous host sharing examples. Updated composition examples to declare their dependencies.
+
+### Fixed
+
+- Falsey nonempty mappings and configuration objects retain their explicit values; invalid scope arguments fail before model resolution.
+- Nested configuration and sharing scopes preserve the active step identity so child executions retain their parent-step correlation.
+
 ## [0.15.0]
 
 ### Added
@@ -43,6 +75,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Embedded step type annotations resolve explicit and scoped names on Python 3.14, including nested forward references and names that shadow builtins.
 - Dynamic annotation validation uses explicit `TypeForm[object]` casts at Pydantic `TypeAdapter` boundaries, restoring type-checking compatibility with Pydantic 2.14 without changing runtime validation. Declared `typing-extensions` as a direct dependency.
 - Error-handling guides distinguish Natural-selected exceptions, recoverable tool errors, and finalization failures. Published handlers are executed against deterministic runtime responses.
 - Tests follow environment, prompt, executor, and model-selection ownership; scope tests use current composition terminology and avoid duplicate replacement checks or fixed instrumentation names.
@@ -347,7 +380,9 @@ Invalid initial results fail before oversight; use resilience retries to recover
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.15.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.15.0...v0.17.0
+[0.16.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.12.0...v0.13.0

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.15.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.15.0 → nighthawk_python-0.17.0}/docs/api.md

@@ -181,9 +181,11 @@
         - StepCommit
         - Rewrite
         - Accept
-        - Reject
+        - RejectOperation
+        - AbortStep
         - Oversight
-        - OversightRejectedError
+        - StepAbortedError
+        - OperationDecision
         - StepCommitDecision
 
 ## Lifecycle
@@ -257,6 +259,10 @@ See [Embedded execution](embedded-execution.md) for executable synchronous and a
         - OperationRequest
         - OperationFinished
         - OperationError
+        - OperationRejection
+        - OperationRejectedError
+        - OperationDeliveryError
+        - OperationStatus
 
 ::: nighthawk.runtime.expression
     options:

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/coding-agent-backends.md

@@ -60,6 +60,11 @@ All three backends accept `working_directory` in their model settings. This abso
 
 If a backend CLI process fails (e.g., crashes, times out, or returns an invalid response), Nighthawk surfaces the failure as an `ExecutionError`. See [Patterns](patterns.md#error-handling) for error handling patterns.
 
+Operation inspection can return `RejectOperation` to deliver structured refusal through MCP/SDK error results while keeping the transport available for another inspected request.
+`AbortStep`, inspection failures, and operation notification failures terminate the step even if the coding agent catches a tool error.
+Core cannot identify a coding agent's invisible response batches or individually gate its internal inference requests.
+The [operation feedback support matrix](operation-feedback.md#ordering-and-backend-boundaries) describes these limits and the distinct behavior of directly visible Pydantic AI responses.
+
 ### Allowed tool names
 
 Use `allowed_tool_names` to restrict which Nighthawk tools are exposed to the backend via MCP. When `None` (default), all tools visible in the current scope are exposed.

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/design-drivers.md

@@ -168,6 +168,45 @@ The expected benefit is less custom host integration for dynamic declarations an
 Success requires correct per-invocation value contracts and completion records that reflect writeback failures.
 Compare the effort and complexity of constructing and changing this integration with an ordinary Python implementation providing the same guarantees.
 
+## Explicit sharing across nested Natural calls
+
+**Status:** The name-resolution contract is covered by deterministic tests in `tests/runtime/test_explicit_sharing.py`, with executable synchronous and asynchronous [sharing examples](runtime-configuration.md#selecting-shared-values-with-python).
+The originating evidence is one embedded conversation host's v0.15.0 reproduction; independent application evidence and model-quality improvements remain unevaluated.
+
+The host calls reusable Natural functions from a step containing conversation input and temporary working values.
+Automatically copying those working names into children creates dependencies beyond the child's arguments, Python lexical environment, and deliberately shared references.
+A context builder can omit prompt content but cannot change preparation-time binding resolution or runtime name lookup.
+Requiring host executors to reconstruct Core preparation would move execution complexity into applications.
+
+Core therefore constructs each child's own Python environment and supplies only the active scope's explicit task references as additional names.
+Applications select values using ordinary Python helpers and pass dictionaries through `scope(task_references=...)`; no inheritance mode or environment-construction callback is required.
+Scopes preserve execution parentage and existing management contracts while replacing or clearing shared references.
+This simplifies an existing execution semantic; it does not establish a general object-isolation facility.
+
+The deterministic evidence covers absent parent bindings, preparation failures, real context construction, expression and discovery access, object identity, nested execution, and scoped asynchronous behavior.
+It does not establish that separating names prevents repeated model calls or improves judgments.
+Assess those hypotheses through application evaluations, including independent reuse and the effort needed to declare shared dependencies.
+
+## Correcting refused operations within a Natural step
+
+**Status:** Execution contracts have deterministic coverage in `tests/runtime/test_operation_recovery.py` and `tests/backends/test_rejection_feedback.py`, with executable [model and custom-executor examples](operation-feedback.md).
+No independent application case or comparative model-quality evaluation is recorded.
+
+A host may refuse a proposed operation while still permitting a different way to complete the task.
+Previously every operation-inspection rejection ended the step, even if an executor caught the exception.
+Ordinary helper return values can communicate expected domain findings, but cannot change that Core-owned inspection and finalization contract.
+Reimplementing the operation pipeline in application executors would duplicate state, notification, and termination responsibilities.
+
+Core therefore separates `RejectOperation`, which refuses one body and exposes deliberate feedback, from `AbortStep`, which ends the inspected step.
+The same step retains its live environment, prior effects, model history, and request controls while the model or custom executor chooses another operation.
+Refusal records survive successful finalization; failed notifications and terminal stops cannot become ordinary feedback.
+Visible model batches stop at refusal, while provider-internal batches remain a documented backend boundary.
+
+Applications own the policy, alternative operations, acceptance criteria, and any durable evidence or improvement process.
+Core does not infer that a later accepted output means the task was completed, automatically retry an operation, or add a separate repair agent or policy engine.
+The deterministic tests establish execution behavior, not improved judgment, accumulated capability, or comparative advantage.
+Further application evidence should compare successful corrections, unacceptable effects, authoring and maintenance burden, and inference cost against ordinary Python/model-library compositions.
+
 ## Using Nighthawk to develop Nighthawk
 
 **Status:** Conceptual application direction.

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/embedded-execution.md

@@ -36,7 +36,10 @@ Caller locals, globals, closure cells, and inherited parent working state are no
 Scoped configuration, execution identity, oversight, capabilities, and lifecycle retain their usual inheritance rules.
 
 Called Python functions retain their own closures and globals.
-Nested Natural functions use their own Python frames and the usual parent working-state inheritance; the explicit namespace is not installed as their local environment.
+Nested Natural functions use their own Python frames and the active scope's explicit task references.
+The explicit namespace and later parent temporaries do not become implicit inputs to those functions or their descendants.
+Pass values as arguments, or use a Python helper to select references for `nh.scope(task_references=...)` before calling the child.
+See the [synchronous and asynchronous sharing examples](runtime-configuration.md#selecting-shared-values-with-python).
 This selects an execution environment without isolating Python objects or restricting the authority of called functions.
 
 Omitting an output annotation selects the ordinary initial-value inference rule.
@@ -52,10 +55,13 @@ It returns `None` or an awaitable completing that assignment.
 Callbacks run sequentially in output declaration order; Core records a successful assignment only after its callback returns normally.
 Both entry points accept synchronous or asynchronous writers; the synchronous entry point uses the ordinary bridge for awaitables.
 
-Normal finalization includes initialized declared outputs, even if the executor does not propose them.
-Tracked working values take precedence over initial values, and explicit executor proposals take precedence over both.
-Uninitialized outputs without proposals remain absent.
-An initial `Raise` discards outputs before value validation while still rejecting undeclared names.
+When `StepCandidate.binding_name_to_value` is omitted or `nh.UNSET`, finalization selects initialized declared outputs.
+Tracked working values take precedence over current Python values; uninitialized outputs and task-only references remain absent.
+A supplied mapping selects exactly those outputs, including when it is empty; omitted names are neither supplemented nor validated for writeback.
+Selected values must satisfy their output contracts before commit inspection.
+Use `request.snapshot_output_bindings()` and ordinary Python dictionary composition to explicitly combine current output values with replacements.
+An initial `Raise` selects no outputs and skips validation of pending working values.
+Pairing `Raise` with an explicitly supplied nonempty output mapping is invalid for both `StepCandidate` and `Rewrite`.
 A commit `Rewrite` with an explicitly supplied mapping replaces the selected outputs completely; rewriting to `{}` does not restore initial values.
 
 These are separate facts:
@@ -71,6 +77,53 @@ An interrupted writer must finish its cancellation handling before control can r
 If a writer mutates storage and then raises, Core cannot infer whether the assignment completed; that writer owns diagnosis and recovery for its partial effects.
 This interface does not promise database transactions, rollback, retries, or durable storage.
 
+This example uses the same executor with synchronous and asynchronous entry points to distinguish automatic, empty, explicit, and composed output selections.
+
+<!-- runnable-example:output_selection -->
+```py
+import asyncio
+
+import nighthawk as nh
+from nighthawk.runtime import Pass, StepCandidate, StepDefinition, StepRequest, execute_step, execute_step_async
+
+
+class Executor:
+    def run_step(self, *, request: StepRequest) -> StepCandidate:
+        selection = request.processed_natural_program
+        if selection == "automatic":
+            return StepCandidate(outcome=Pass())
+        if selection == "empty":
+            return StepCandidate(outcome=Pass(), binding_name_to_value={})
+        if selection == "explicit":
+            return StepCandidate(outcome=Pass(), binding_name_to_value={"first": 7})
+        return StepCandidate(outcome=Pass(), binding_name_to_value={**request.snapshot_output_bindings(), "first": 7})
+
+
+async def main() -> None:
+    selection_to_binding_name_to_value = {
+        "automatic": {"first": 1, "second": 2},
+        "empty": {},
+        "explicit": {"first": 7},
+        "composed": {"first": 7, "second": 2},
+    }
+    with nh.run(Executor()):
+        for asynchronous in (False, True):
+            for selection, expected_binding_name_to_value in selection_to_binding_name_to_value.items():
+                saved_name_to_value: dict[str, object] = {}
+                definition = StepDefinition(selection, output_binding_names=("first", "second"))
+                initial_name_to_value = {"first": 1, "second": 2}
+                if asynchronous:
+                    await execute_step_async(definition, name_to_value=initial_name_to_value, write_binding=saved_name_to_value.__setitem__)
+                else:
+                    execute_step(definition, name_to_value=initial_name_to_value, write_binding=saved_name_to_value.__setitem__)
+                assert saved_name_to_value == expected_binding_name_to_value
+
+
+asyncio.run(main())
+print("automatic=2; empty=0; explicit=1; composed=2; sync_and_async=True")
+```
+<!-- /runnable-example:output_selection -->
+
 Terminal delivery happens after writeback or failure, with the usual `StepCompleted`, `StepRaised`, `StepFailed`, or `StepInterrupted` record.
 Notification failure propagates without replaying execution or notification and without undoing completed writes.
 The optional `source_location` labels the trusted program for diagnostics; its default is `<embedded>:0`.
@@ -107,7 +160,7 @@ definition = StepDefinition(
     binding_name_to_type={"summary": str},
     source_location="trusted_summary:1",
 )
-executor = ScriptedExecutor([pass_response(summary="The trial passed.")])
+executor = ScriptedExecutor([pass_response(binding_name_to_value={"summary": "The trial passed."})])
 with nh.run(executor), nh.scope(lifecycle=StepLifecycle(finished)):
     outcome = execute_step(definition, name_to_value=name_to_value, write_binding=name_to_value.__setitem__)
 
@@ -159,7 +212,7 @@ async def main() -> None:
         binding_name_to_type={"selected": "Selection"},
         source_location="trusted_selection:1",
     )
-    executor = ScriptedExecutor([pass_response(selected={"label": "alpha"})])
+    executor = ScriptedExecutor([pass_response(binding_name_to_value={"selected": {"label": "alpha"}})])
     with nh.run(executor), nh.scope(lifecycle=StepLifecycle(finished)):
         outcome = await execute_step_async(definition, name_to_value={"candidates": ["alpha", "beta"], "Selection": Selection}, write_binding=write)
     assert outcome == Pass()

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/executors.md

@@ -30,6 +30,9 @@ step_executor = nh.AgentStepExecutor.from_configuration(configuration=configurat
 
 The `model` field accepts a `provider:model` identifier or a borrowed Pydantic AI `Model` instance whose client lifetime remains with the host.
 The default model is `openai-responses:gpt-5.6-luna`.
+`model_settings` defaults to an empty dictionary; `None` and `UNSET` are invalid field values.
+Optional executor configuration arguments use omission or `nh.UNSET` to create a fresh default configuration.
+An explicit configuration replaces the complete value; raw dictionaries and `None` are rejected before constructing an agent.
 
 Use [Runtime configuration](runtime-configuration.md) to establish a run, select child models, or mix executors.
 Host wrappers can support model selection through the [configuration resolution protocol](specification.md#model-declarations-and-observation).
@@ -49,6 +52,42 @@ executor = nh.AgentStepExecutor.from_agent(agent=agent)
 
 For full control, implement `AsyncStepExecutor` directly. See [Specification Section 14.3](specification.md#143-custom-backends) for semantics and [API reference](api.md#runtime-executor-boundary) for the protocol.
 
+## Output selection
+
+Executors return `StepCandidate(outcome=..., binding_name_to_value=...)`.
+The output mapping selects the complete set of values to validate and consider for writeback.
+
+| Selection | Meaning |
+|---|---|
+| Omitted or `nh.UNSET` | Select initialized declared outputs from the working environment at finalization. |
+| `{}` | Select no writes, even when declared outputs already have values. |
+| `{"result": value}` | Select only `result`; do not supplement other initialized outputs. |
+| `None` | Invalid. |
+
+The standard agent executor omits the selection, so its tracked assignments and other initialized declared outputs receive final validation.
+An explicit selection validates only its entries; output names must still be declared, and commit inspection still applies.
+Neither an empty selection nor a later rejection undoes earlier calls or in-place object mutations.
+`Raise` permits only omitted or empty output selections.
+
+For an explicit combination of current outputs and replacements, use ordinary Python:
+
+```py
+from nighthawk.runtime import Pass, StepCandidate, StepRequest
+
+
+def select_result(request: StepRequest, result: object) -> StepCandidate:
+    return StepCandidate(
+        outcome=Pass(),
+        binding_name_to_value={**request.snapshot_output_bindings(), "result": result},
+    )
+```
+
+`snapshot_output_bindings()` returns a fresh dictionary in declaration order, preferring tracked assignments over current Python values, including live globals and cells.
+Unbound outputs, temporaries, and task-only references are excluded.
+The method preserves value identity and performs no validation or writes.
+A snapshot fixes associations at the time it is taken; omission selects them later, during finalization.
+`Rewrite` uses the same complete-mapping semantics after initial validation, with omission retaining the current commit field.
+
 ## Next steps
 
 - **[Pydantic AI providers](pydantic-ai-providers.md)** -- Installation, model identifiers, credentials, and model settings for each Pydantic AI provider.

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/for-coding-agents.md

@@ -89,7 +89,7 @@ Read [Quickstart](https://kurusugawa-computer.github.io/nighthawk-python/quickst
 - Use `deny` frontmatter to prohibit outcomes that would bypass required Python work. The template denies `return` to preserve the Python return path and denies the explicit `raise` outcome; runtime and helper failures can still raise.
 - Denying outcomes does not require a fresh assignment. A permitted `pass` can retain an output's initial value. Use a deliberate default or an unbound annotated output, and validate the result before dependent work.
 - Each block starts a fresh model interaction without implicit message history. Carry essential inputs and results through Python parameters and return values.
-- Lexical values, inherited parent working state, and scoped task references can supply context. Prefer explicit arguments for essential dependencies and inheritance for intentionally shared policy. Child name rebinding stays local; mutable objects can remain shared.
+- Python lexical values and scoped task references supply context. Prefer explicit arguments for essential dependencies and `scope(task_references=...)` for intentionally shared policy. Parent working values are not copied into children. Child name rebinding stays local; explicitly shared mutable objects retain identity.
 
 The type boundary may sit inside a function: accept text that needs interpretation, then commit a typed result before deterministic work begins.
 Types constrain the result's shape and range; they do not prove that its meaning is correct.
@@ -189,8 +189,8 @@ def test_quote_batch_processes_each_message_and_uses_host_price():
     messages = ["A dozen, please.", "Please send three."]
     executor = ScriptedExecutor(
         responses=[
-            pass_response(order={"quantity": 12}),
-            pass_response(order={"quantity": 3}),
+            pass_response(binding_name_to_value={"order": {"quantity": 12}}),
+            pass_response(binding_name_to_value={"order": {"quantity": 3}}),
         ],
     )
     with nh.run(executor):
@@ -199,14 +199,14 @@ def test_quote_batch_processes_each_message_and_uses_host_price():
 
 
 def test_quote_batch_stops_when_quantity_is_unclear():
-    executor = ScriptedExecutor(responses=[pass_response(order={"quantity": None})])
+    executor = ScriptedExecutor(responses=[pass_response(binding_name_to_value={"order": {"quantity": None}})])
     with nh.run(executor), pytest.raises(ValueError, match="Quantity needs clarification"):
         quote_batch(["A few, please.", "Then three more."], unit_price_cents=250)
     assert len(executor.calls) == 1
 
 
 def test_quote_batch_rejects_invalid_model_output():
-    executor = ScriptedExecutor(responses=[pass_response(order={"quantity": 0})])
+    executor = ScriptedExecutor(responses=[pass_response(binding_name_to_value={"order": {"quantity": 0}})])
     with nh.run(executor), pytest.raises(nh.ExecutionError):
         quote_batch(["One, please."], unit_price_cents=250)
 ```

{nighthawk_python-0.15.0 → nighthawk_python-0.17.0}/docs/natural-blocks.md

@@ -81,7 +81,7 @@ Presentation is a view of accessible state, not its authority or a replacement f
 
 Each Natural block performs one task with declared output bindings and one outcome.
 There is no implicit model message history between blocks.
-Python values, inherited parent working state, and scoped task references supply context to each fresh interaction (see [Patterns: cross-block composition](patterns.md#cross-block-composition)).
+Python lexical values and explicitly scoped task references supply context to each fresh interaction (see [Patterns: cross-block composition](patterns.md#cross-block-composition)).
 
 ## Providing data to a block
 
@@ -150,7 +150,8 @@ An explicit output annotation determines its validation contract at block entry.
 Without one, the runtime infers the initialized value's type, except for `None` and a plain `object()`; otherwise the output is unconstrained.
 Annotate collections explicitly when element types matter: `findings: list[Finding] = []` retains its element contract, while `findings = []` selects only `list`.
 An unresolved explicit annotation fails preparation instead of silently falling back to inference.
-All bound declared outputs receive final validation even if the model never assigns them; an initial Raise discards pending outputs.
+The standard executor selects all bound declared outputs for final validation even if the model never assigns them; an initial Raise discards pending outputs.
+Custom executors may supply an explicit complete output selection; see [output selection](executors.md#output-selection).
 Output contracts constrain values, not the factual correctness of a judgment.
 See [binding contracts](specification.md#7-natural-dsl-bindings) for annotation acquisition and global/nonlocal writeback.
 
@@ -401,7 +402,7 @@ Function parameters and working locals are candidates for LOCALS, and explicit m
 
 Keep fewer incidental locals alive when they do not help the judgment. A callable passed through a parameter retains its live callable metadata even when the parameter annotation is `object`, `Any`, or absent. Signature and documentation acquisition are best-effort and do not execute application properties or annotation expressions.
 
-Use explicit parameters for essential inputs and independent reuse. Module globals and task injection can supply shared capabilities; inherited working state supplies deliberately shared parent context. These layers preserve their provenance and remain available beyond the initial presentation budget.
+Use explicit parameters for essential inputs and independent reuse. Module globals and task references can supply shared capabilities and context. Parent working values are not copied into children; select values in ordinary Python and supply them through arguments or `nh.scope(task_references=...)`. These layers preserve their provenance and remain available beyond the initial presentation budget.
 
 **Note:** Nighthawk also accepts native tools through `nh.scope(tools=[...])`, which exposes functions via the model's native tool-calling interface for the duration of the scope. This path is reserved for cases that need native tool calling, such as strict argument schemas or Pydantic AI tool features. Binding functions are preferred for all other uses because they incur no per-definition token overhead beyond a signature line in the prompt context. See [Runtime configuration](runtime-configuration.md#scoped-tools) and [Specification Section 8.3](specification.md#83-tools-available-to-the-llm).