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

{nighthawk_python-0.15.0 → nighthawk_python-0.16.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.16.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.16.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.16.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +59,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 +364,8 @@ 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.16.0...HEAD
+[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.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.15.0
+Version: 0.16.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.16.0}/docs/design-drivers.md

@@ -168,6 +168,25 @@ 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.
+
 ## Using Nighthawk to develop Nighthawk
 
 **Status:** Conceptual application direction.

{nighthawk_python-0.15.0 → nighthawk_python-0.16.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.16.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.16.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.16.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).
 

{nighthawk_python-0.15.0 → nighthawk_python-0.16.0}/docs/patterns.md

@@ -257,7 +257,7 @@ async def classify_batch(texts: list[str]) -> list[str]:
 ```
 
 Each concurrent Natural block has its own step context and no shared model message history.
-Inherited Python objects and host accounting can still be shared; `asyncio.gather` is appropriate when those shared values are safe for concurrent use.
+Explicit Python references and host accounting can still be shared; `asyncio.gather` is appropriate when those shared values are safe for concurrent use.
 Tasks capture their selected context when created, including model selection and function-call handlers; awaiting a task elsewhere does not replace that context.
 
 ### Async and sync interoperability
@@ -274,10 +274,10 @@ You can therefore use async binding functions through tools without changing a s
 ## Cross-block composition
 
 Each Natural block starts a fresh model interaction ([one block, one task](natural-blocks.md#one-block-one-task)).
-Use Python arguments and returned values for essential inputs and results, inherited parent working state for intentionally shared task context, and scoped task references for injected capabilities.
-Joined children inherit materialized parent associations at entry; shared objects remain live, while child name rebinding does not update the parent.
-Children that outlive their parent have no inheritance guarantee.
-The [environment contract](specification.md#813-parent-lifetime-and-expression-lifetime) defines the precise boundaries.
+Use Python arguments and returned values for essential inputs and results, and scoped task references for deliberately shared context and capabilities.
+Children do not receive a parent's working values automatically; explicitly shared objects remain live, while child name rebinding does not update the parent.
+Hosts establish explicit inputs and execution scope for independent work that outlives a parent step.
+The [environment contract](specification.md#813-shared-values-and-expression-lifetime) defines the precise boundaries.
 
 ### Python iteration with Natural judgment
 
@@ -317,7 +317,7 @@ async def summarize_and_assess(document: str) -> list[tuple[str, float]]:
 ### Natural selects follow-up assessments
 
 Here the parent chooses which claims need review.
-The child receives the document and claim explicitly, and inherits the parent's materialized review policy.
+The child receives the document and claim as arguments, and the review policy through an explicit task-reference scope.
 Call these ordinary Natural functions inside `nh.run(executor)`:
 
 ```python
@@ -342,18 +342,19 @@ async def assess_claim(document: str, claim: str) -> float:
 async def review_claims(document: str, claims: list[str]) -> list[tuple[str, float]]:
     review_guidance = "Check quantitative and causal claims against direct evidence."
     assessments: list[tuple[str, float]] = []
-    """natural
-    Use <review_guidance> to choose claims from <claims> that need closer review.
-    Call <assess_claim> with <document> and each selected claim, awaiting each result.
-    Store the selected claims and their returned scores in <:assessments>.
-    """
+    with nh.scope(task_references={"review_guidance": review_guidance}):
+        """natural
+        Use <review_guidance> to choose claims from <claims> that need closer review.
+        Call <assess_claim> with <document> and each selected claim, awaiting each result.
+        Store the selected claims and their returned scores in <:assessments>.
+        """
     return assessments
 ```
 
 The parent step remains active until its chosen calls finish.
-The policy does not need to pass through intermediate helper signatures, but `assess_claim` now has an inherited dependency: calling it independently requires supplying that policy, for example through task injection.
+The policy does not need to pass through intermediate helper signatures, but `assess_claim` has an explicit scoped dependency: calling it independently requires supplying `review_guidance` through task references.
 Prefer an explicit policy parameter when independent reuse matters.
-The [nested execution acceptance example](specification.md#144-nested-execution-acceptance-example) isolates inheritance mechanics separately from this judgment task.
+The [nested execution acceptance example](specification.md#144-nested-execution-acceptance-example) isolates explicit argument passing separately from this judgment task.
 
 ### The carry pattern
 

{nighthawk_python-0.15.0 → nighthawk_python-0.16.0}/docs/roadmap.md

@@ -82,7 +82,7 @@ Explore explicit serialization of host data and correlation metadata for multi-p
 
 ### Async bridge ContextVar propagation
 
-Investigate propagating selected context-variable rebindings back from bridge threads while preserving [parent lifetime and shared-value boundaries](specification.md#813-parent-lifetime-and-expression-lifetime).
+Investigate propagating selected context-variable rebindings back from bridge threads while preserving [shared-value and expression-lifetime boundaries](specification.md#813-shared-values-and-expression-lifetime).
 
 ## Implementation hardening