nighthawk-python 0.12.0__tar.gz → 0.14.0__tar.gz

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/.claude/rules/docs.md

@@ -77,7 +77,7 @@ List only topics that commonly drift across multiple files or are easy to mispla
 - Terminology: "task" = structural unit (contract), "judgment" = cognitive act. Use "one task per block".
 - Code examples: self-contained and understandable without surrounding prose.
 - Built-in tools (`nh_eval`, `nh_assign`): implementation details. Only `specification.md` may expose them.
-- `@nh.tool`: `specification.md` documents as spec, `natural-blocks.md` may mention it with a "prefer binding functions" note, all others must not reference it.
+- Native tools (`nh.scope(tools=...)`): `specification.md` documents as spec, `runtime-configuration.md` documents usage and the role split with `implicit_references`, `natural-blocks.md` may mention it with a "prefer binding functions" note, all others must not reference it.
 - Package name: always `nighthawk-python` in `pip install` commands.
 - When renaming a document or changing its role, update all inbound references, routing rules here, relevant `tests/docs`, and navigation metadata if applicable.
 - When a governance file under `docs/` is not meant for publication, its MkDocs handling must be explicit.

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/.claude/rules/promptfoo.md

@@ -21,7 +21,7 @@ paths:
 4. Once validated, port the change to the corresponding production code (see mapping below).
 5. Run `uv run pytest -q` to confirm no regressions.
 
-**`--filter-providers` caveat**: The flag takes a regex pattern, not an exact label. A pattern like `"gpt-5.4-mini"` matches every provider whose label contains that substring (e.g. both `openai-responses` and `codex` labels). Use an anchored or label-specific pattern (e.g. `"^gpt-5.4-mini"`, `"codex:"`) to target a single provider.
+**`--filter-providers` caveat**: The flag takes a regex pattern, not an exact label. A pattern like `"gpt-5.6-luna"` matches every provider whose label contains that substring (e.g. both `openai-responses` and `codex` labels). Use an anchored or label-specific pattern (e.g. `"^gpt-5.6-luna"`, `"codex:"`) to target a single provider.
 
 ## Prompt variant cleanup (deletion timing and criteria)
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/.github/workflows/ci.yml

@@ -19,13 +19,17 @@ jobs:
     name: Lint and type check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: "3.13"
+          # Same dependency set and cache key as "test (3.13)". Only that job
+          # saves the entry; concurrent writers race to reserve the same key.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --all-extras --all-groups
@@ -48,11 +52,12 @@ jobs:
         python-version: ["3.13", "3.14"]
     continue-on-error: ${{ matrix.python-version != '3.13' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # Sole writer of the per-Python-version dependency cache.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -67,11 +72,15 @@ jobs:
     needs: [lint, test]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # "uv build" only resolves the build backend, so a cache entry would add
+      # no measurable benefit while colliding with the docs workflow key.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: false
 
       - name: Build sdist and wheel
         run: uv build

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/.github/workflows/docs.yml

@@ -24,9 +24,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          # The docs group is a subset of the cache "test (3.13)" saves under
+          # this key, so restore it here but never overwrite it.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --group docs

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/.github/workflows/publish.yml

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

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/CHANGELOG.md

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0]
+
+### Added
+
+- Scoped `nh.lifecycle.StepLifecycle` delivers typed completion, DSL raise, failure, or interruption records after generated caller assignments. Hosts can record one terminal event and translate failures with explicit exception chaining.
+- `Oversight.inspect_return_expression` approves expressions before core evaluation, await, and return validation.
+- `StepDeliveryError` supports host storage adapters without claiming persistence succeeded.
+
+### Changed
+
+- `ExecutionReference` and `get_execution_reference` replace the abbreviated identity API. `step_execution_id` identifies each invocation; `source_location` identifies its source. StepContext, inspection, testing observations, terminal records, and spans share this identity.
+- Runtime internal exceptions, including preparation and await failures, now propagate through `ExecutionError.step_failed` with the original exception as cause. Rejection is a classified failure. DSL exceptions remain distinct.
+- Completion tracing follows actual caller assignments. Cancellation retains priority if terminal delivery fails. Delivery errors never retry execution or undo effects.
+- Natural functions preserve original closure cells for nonlocal assignments and source locations for generated execution.
+
+### Fixed
+
+- Lifecycle handlers can rethrow an already-recorded host exception or interruption without replacing its original cause with a self-reference.
+- Host integration guidance distinguishes one delivery attempt from ledger deduplication and explains the validation, await, and rewrite limits of name-only return approval.
+
+### Removed
+
+- `ExecutionRef`, `get_execution_ref`, and `step_id`, without compatibility aliases. Span attributes use `step.execution.id` and `step.source_location`.
+
+## [0.13.0]
+
+### Added
+
+- `nh.UNSET`, `nh.UnsetType`, `nh.Extend`, and `nh.Merge` express inheritance and per-field scope composition.
+- Caller-constructed Pydantic AI Models in `StepExecutorConfiguration.model`, retaining identity and the managed execution contract. Clients are borrowed; hosts own authentication delivery and lifetime.
+- Host-installed usage meters, scoped native tools and Pydantic AI capabilities, and public scope getters.
+- Resolved `Pass`, `Return`, `Break`, `Continue`, and `Raise` outcomes through `nh.oversight`, with explicit `Rewrite(return_value=None)` support.
+- `nh.get_transformed_function()` for compiled-body inspection through conventional wrappers.
+
+### Changed
+
+- The default model is now `openai-responses:gpt-5.6-luna` (previously `openai-responses:gpt-5.4-nano`).
+- Scope omission inherits; ordinary values replace and empty collections clear. Only oversight accepts `None`. Executor replacement precedes full configuration replacement.
+- Run getters require a run; `get_step_context()` requires a step. Budget wrappers retain optional private meter discovery.
+- Repeated identical tool declarations are idempotent. Conflicts use `NameConflictError` and `ToolNameConflictError`; invalid tools use `ToolDeclarationError`.
+- `StepCommit.outcome` contains resolved Python values in variants. Inspection mappings preserve contained types and identity through shallow read-only views. Trusted hooks must not mutate references.
+- One validated candidate is inspected, then supplied rewrites are validated before final assignment. Bindings-only rewrites preserve the resolved return; return expressions are never replayed. Rejection cannot roll back preceding host side effects.
+- Decorated functions share real module globals; `__wrapped__` and `inspect.unwrap` follow the original function.
+- Live Model configuration serialization requires explicit model-field exclusion, including nested records. External agents reject Model injection and configured model switches rather than silently changing a label.
+
+### Removed
+
+- Global `scope(mode=...)`, the old `get_current_usage_meter` and `get_current_step_context` names, and `ToolRegistrationError`; no deprecated aliases remain.
+- `@nighthawk.tool` and the process-global tool registry. Declare tools in scopes.
+- `StepCommitProposal`, old proposed/rewritten fields, and parallel `StepCommit.step_outcome`/`return_value` fields.
+
+### Compatibility
+
+The supported public API is `nighthawk.__all__` plus the modules listed in `docs/api.md`. Private names may change without notice. Minor releases in the 0.x series may contain the breaking changes listed here.
+
+### Migration notes for hosts
+
+| Before | After |
+|---|---|
+| `scope(mode="inherit", tools=[fn])` | `scope(tools=nh.Extend([fn]))` |
+| `scope(mode="replace", implicit_references={})` | `scope(implicit_references={})` |
+| `scope(implicit_references=None)` to inherit | Omit the field or use `nh.UNSET`; use `nh.Merge(mapping)` to compose |
+| `get_current_usage_meter()` / `get_current_step_context()` | `get_usage_meter()` / `get_step_context()`; missing context raises |
+| `ToolRegistrationError` | `ToolDeclarationError`; catch `NameConflictError` across namespaces |
+| Private meter context writes | `nh.run(executor, usage_meter=meter)` or `nh.scope(usage_meter=meter)` |
+| `@nh.tool` at import time | `nh.scope(tools=[fn])` or an explicit Pydantic AI `Tool` |
+| `StepCommit.return_value` | Check `isinstance(commit.outcome, nh.oversight.Return)`, then read `.value` |
+| Expression-based `Rewrite(step_outcome=...)` | `Rewrite(outcome=nh.oversight.Return(value=...))` |
+| Bindings rewrite that implicitly recalculates return | Supply both replacement bindings and `return_value` explicitly |
+| `inspect.unwrap(function)` to find compiled code | `nh.get_transformed_function(function)` |
+| Credential transport via environment for managed construction | Construct authenticated Provider/Model in memory and use `StepExecutorConfiguration(model=model)` |
+| Dumping configuration containing a live Model | Explicitly exclude `model`; the partial dump cannot reconstruct it |
+| Changing an external agent's configured model | Replace the executor with a managed executor or a host-configured external agent |
+
+Invalid initial results fail before oversight; use resilience retries to recover. `from_configuration(configuration=...)` retains its signature. String model settings remain serializable, and environment-configured provider strings remain supported.
+
 ## [0.12.0]
 
 ### Changed
@@ -188,7 +264,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.12.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.14.0...HEAD
+[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
 [0.12.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.9.0...v0.10.0

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/CONTRIBUTING.md

@@ -83,8 +83,8 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx promptfoo
 | Command | Purpose |
 |---|---|
 | `eval $PFOO eval` | Full regression (all backends, all tests) |
-| `eval $PFOO eval -c promptfooconfig-prompt-ab.yaml` | Prompt A/B test (gpt-5.4-mini only) |
-| `eval $PFOO eval -c promptfooconfig-nano-sanity.yaml --no-cache` | Default-model sanity check (gpt-5.4-nano only) |
+| `eval $PFOO eval -c promptfooconfig-prompt-ab.yaml` | Prompt A/B test (gpt-5.6-luna only) |
+| `eval $PFOO eval -c promptfooconfig-luna-sanity.yaml --no-cache` | Default-model sanity check (gpt-5.6-luna only) |
 | `eval $PFOO eval -c promptfooconfig-agents.yaml` | Coding agent backends (reduced test set) |
 | `eval $PFOO eval -c promptfooconfig.yaml --filter-pattern "P-BIND-001"` | Single test |
 | `eval $PFOO eval -c promptfooconfig.yaml --filter-providers "claude-code-cli"` | Single backend |
@@ -93,8 +93,8 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx promptfoo
 #### Config files (`evals/promptfoo/`)
 
 - `promptfooconfig.yaml` — Regression: winner prompt combo across openai-responses, claude-code-cli, and codex backends. All test cases.
-- `promptfooconfig-prompt-ab.yaml` — A/B testing: 4 prompt/tool variants on gpt-5.4-mini. All test cases.
-- `promptfooconfig-nano-sanity.yaml` — Default-model sanity check on openai-responses:gpt-5.4-nano. All test cases.
+- `promptfooconfig-prompt-ab.yaml` — A/B testing: 4 prompt/tool variants on gpt-5.6-luna. All test cases.
+- `promptfooconfig-luna-sanity.yaml` — Default-model sanity check on openai-responses:gpt-5.6-luna. All test cases.
 - `promptfooconfig-agents.yaml` — Coding agent only: claude-code-cli and codex with reduced test set.
 
 #### Directory layout
@@ -205,7 +205,7 @@ def run(
     Example:
         ```python
         executor = AgentStepExecutor.from_configuration(
-            configuration=StepExecutorConfiguration(model="openai-responses:gpt-5.4-mini"),
+            configuration=StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"),
         )
         with nighthawk.run(executor):
             result = my_natural_function()

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.12.0
+Version: 0.14.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/
@@ -73,7 +73,7 @@ def python_average(numbers):
     return sum(numbers) / len(numbers)
 
 
-step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"))
 
 with nh.run(step_executor):
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/README.md

@@ -38,7 +38,7 @@ def python_average(numbers):
     return sum(numbers) / len(numbers)
 
 
-step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"))
 
 with nh.run(step_executor):
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/api.md

@@ -8,27 +8,37 @@
 ::: nighthawk
     options:
       members:
+        - UNSET
+        - UnsetType
+        - Extend
+        - Merge
+        - get_transformed_function
         - natural_function
-        - tool
         - run
         - scope
         - AgentStepExecutor
+        - StepExecutor
         - StepExecutorConfiguration
         - StepPromptTemplates
         - StepContextLimits
         - JsonableValue
         - to_jsonable_value
-        - ExecutionRef
-        - get_current_step_context
-        - get_current_usage_meter
-        - get_execution_ref
+        - ExecutionReference
+        - get_capabilities
+        - get_step_context
+        - get_usage_meter
+        - get_execution_reference
         - get_implicit_references
+        - get_oversight
+        - get_lifecycle
         - get_step_executor
         - get_system_prompt_suffix_fragments
+        - get_tools
         - get_user_prompt_suffix_fragments
         - resilience
         - UsageMeter
         - oversight
+        - lifecycle
 
 ## Errors
 
@@ -93,18 +103,45 @@
       members:
         - StepContext
         - ToolResultRenderingPolicy
-        - get_current_step_context
+        - get_step_context
         - step_context_scope
 
+## Step Contracts
+
+Import these types from `nighthawk.runtime.step_contract` when implementing a custom
+`StepExecutor` or constructing a `nighthawk.testing.StepResponse`.
+`StepKind` describes the allowed outcome kinds, and `StepOutcome` is the union of
+the five outcome models, discriminated by their `kind` field.
+
+These models describe executor results before the runner resolves them for
+oversight. In particular, `ReturnStepOutcome.return_expression` holds a Python
+expression that the runner evaluates, whereas `nighthawk.oversight.Return.value`
+holds the evaluated value. Oversight hooks use `nighthawk.oversight.StepResult`.
+
+::: nighthawk.runtime.step_contract
+    options:
+      members:
+        - StepKind
+        - StepOutcome
+        - PassStepOutcome
+        - ReturnStepOutcome
+        - BreakStepOutcome
+        - ContinueStepOutcome
+        - RaiseStepOutcome
+
 ## Tool Contracts
 
 ::: nighthawk.tools.contracts
     options:
       members:
-        - ToolResult
+        - ToolOutcome
         - ToolBoundaryError
-        - Error
+        - ToolError
         - ErrorKind
+
+::: nighthawk.tools.execution
+    options:
+      members:
         - ToolResultWrapperToolset
 
 ## Resilience
@@ -128,3 +165,37 @@
 ## Testing
 
 ::: nighthawk.testing
+
+::: nighthawk.oversight
+    options:
+      members:
+        - Pass
+        - Return
+        - Break
+        - Continue
+        - Raise
+        - StepResult
+        - StepCommit
+        - ReturnExpression
+        - Rewrite
+        - Accept
+        - Reject
+        - ToolCall
+        - Oversight
+        - OversightRejectedError
+        - StepCommitDecision
+        - ToolCallDecision
+
+## Lifecycle
+
+::: nighthawk.lifecycle
+    options:
+      members:
+        - StepLifecycle
+        - StepFinished
+        - StepCompleted
+        - StepRaised
+        - StepFailed
+        - StepInterrupted
+        - FailureStage
+        - StepDeliveryError

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/coding-agent-backends.md

@@ -25,7 +25,7 @@ Codex:
 configuration = nh.StepExecutorConfiguration(model="codex:default")
 ```
 
-The segment after `:` selects the model. Use `default` to let the backend choose its default model, or specify a model alias recognized by the backend CLI (e.g., `claude-code-sdk:sonnet`, `codex:gpt-5.4-mini`). Available aliases depend on the backend CLI version.
+The segment after `:` selects the model. Use `default` to let the backend choose its default model, or specify a model alias recognized by the backend CLI (e.g., `claude-code-sdk:sonnet`, `codex:gpt-5.6-luna`). Available aliases depend on the backend CLI version.
 
 Backend-specific settings are configured via the `model_settings` field of `StepExecutorConfiguration`. Each backend provides a settings class (`ClaudeCodeSdkModelSettings`, `ClaudeCodeCliModelSettings`, `CodexModelSettings`) that can be passed directly — `StepExecutorConfiguration` auto-converts `BaseModel` instances to dicts internally.
 
@@ -63,7 +63,7 @@ If a backend CLI process fails (e.g., crashes, times out, or returns an invalid
 
 ### Allowed tool names
 
-Use `allowed_tool_names` to restrict which Nighthawk tools are exposed to the backend via MCP. When `None` (default), all registered tools are exposed.
+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.
 
 ```py
 from nighthawk.backends.claude_code_sdk import ClaudeCodeSdkModelSettings

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/executors.md

@@ -33,11 +33,11 @@ See [Philosophy](philosophy.md) for the full design rationale, including the des
 ```py
 import nighthawk as nh
 
-configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
+configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna")
 step_executor = nh.AgentStepExecutor.from_configuration(configuration=configuration)
 ```
 
-The `model` field accepts a `provider:model` format identifier. The default model is `openai-responses:gpt-5.4-nano`.
+The `model` field accepts a `provider:model` format identifier. The default model is `openai-responses:gpt-5.6-luna`.
 
 All Natural functions must be called inside a `with nh.run(step_executor):` context:
 
@@ -57,7 +57,7 @@ For most cases, wrap a Pydantic AI `Agent` using `AgentStepExecutor`:
 ```py
 from pydantic_ai import Agent
 
-agent = Agent(model="openai-responses:gpt-5.4-nano", ...)
+agent = Agent(model="openai-responses:gpt-5.6-luna", ...)
 executor = nh.AgentStepExecutor.from_agent(agent=agent)
 ```
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/for-coding-agents.md

@@ -79,7 +79,7 @@ def summarize(text: str) -> str:
 
 executor = nh.AgentStepExecutor.from_configuration(
     configuration=nh.StepExecutorConfiguration(
-        model="openai-responses:gpt-5.4-mini",
+        model="openai-responses:gpt-5.6-luna",
     ),
 )
 
@@ -99,7 +99,7 @@ import nighthawk as nh
 
 fast_executor = nh.AgentStepExecutor.from_configuration(
     configuration=nh.StepExecutorConfiguration(
-        model="openai-responses:gpt-5.4-mini",
+        model="openai-responses:gpt-5.6-luna",
     ),
 )
 
@@ -149,10 +149,10 @@ with nh.run(fast_executor):
 
 - `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`.
+- Omission or `nh.UNSET` inherits; ordinary values replace and `[]`/`{}` clear collections.
+- Use `nh.Extend([...])` to append suffix fragments and `nh.Merge({...})` to merge implicit references by identity.
+- `oversight` and `lifecycle` accept `None` to clear their hooks; other scope fields reject it.
+- Executor replacement precedes full configuration replacement. Managed Model instances retain identity; external agents own their model selection.
 
 ## 4. The standard contract shape
 
@@ -321,9 +321,9 @@ Error-handling rule:
 
 Async rule:
 
-- Async natural functions can use async binding functions.
-- If a sync natural function triggers an async binding function and gets an awaitable, Nighthawk raises `ExecutionError`.
-- Fix that by making the natural function `async`.
+- Both sync and async Natural functions can call async binding functions through tools; tool expressions await their results.
+- Only an async Natural function may have a final return expression that produces an awaitable. A sync Natural function rejects that final result with `ExecutionError`.
+- Make the Natural function `async` when it needs an awaitable final return expression, not merely because it uses an async binding function.
 
 Resilience rule:
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/index.md

@@ -19,7 +19,7 @@ def python_average(numbers):
     return sum(numbers) / len(numbers)
 
 
-step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"))
 
 with nh.run(step_executor):
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/natural-blocks.md

@@ -13,7 +13,7 @@ All examples assume the [Quickstart](quickstart.md) setup:
 import nighthawk as nh
 
 step_executor = nh.AgentStepExecutor.from_configuration(
-    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"),
+    configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"),
 )
 
 with nh.run(step_executor):
@@ -187,7 +187,7 @@ def summarize_report(report: Report) -> str:
 
 This keeps the media selection visible in ordinary Python, avoids accidental traversal of large object graphs, and lets normal LOCALS budgeting decide whether the helper variable is rendered.
 
-For the normative rendering and transport rules, including dotted-reference hoisting and nested multimodal behavior, see [Specification Section 8.2](specification.md#82-locals-summary).
+For the normative rendering and transport rules, including dotted-reference hoisting and nested multimodal behavior, see [Specification Section 8.2](specification.md#822-locals-summary).
 
 ### f-string injection
 
@@ -361,7 +361,7 @@ When you pass a module-level callable as a function parameter with a generic typ
 
 The principle extends beyond callables. Any module-level name that is stable across invocations -- constants, classes, utility functions -- should stay in GLOBALS via `<name>` read bindings rather than being pulled into LOCALS via parameters or local assignments. Reserve function parameters for data that genuinely varies per call.
 
-**Note:** Nighthawk also provides `@nh.tool`, which registers functions via the model's native tool-calling interface. This path is reserved for cases that require `RunContext[StepContext]` access. 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 [Specification Section 8.3](specification.md#83-tools-available-to-the-llm) for the `@nh.tool` specification.
+**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).
 
 ## Writing guidelines
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/patterns.md

@@ -153,7 +153,7 @@ except InputError as e:
 
 All Nighthawk exceptions inherit from `NighthawkError`. The most common exception in application code is `ExecutionError`, raised when a Natural block produces an invalid outcome, a disallowed outcome type, or a validation failure.
 
-For the full exception hierarchy (`NaturalParseError`, `ToolEvaluationError`, `ToolValidationError`, `ToolRegistrationError`), see [Specification Section 13](specification.md#13-error-handling).
+For the full exception hierarchy (`NaturalParseError`, `ToolEvaluationError`, `ToolValidationError`, `ToolDeclarationError`), see [Specification Section 13](specification.md#13-error-handling).
 
 ## Async Natural functions
 
@@ -224,12 +224,12 @@ Each concurrent Natural block executes independently -- there is no shared messa
 
 Async natural functions can call sync binding functions, and sync natural functions can reference async binding functions. Nighthawk detects awaitable return values and handles them automatically:
 
-- In async natural functions: awaitable results from `nh_eval` and `nh_assign` expressions are awaited before returning to the LLM.
-- In sync natural functions: if the resolved return value is awaitable, execution fails (the caller must be async to await).
+- Tool expressions await async binding function results in both sync and async Natural functions before returning them to the LLM.
+- A final return expression may produce an awaitable only in an async Natural function. A sync Natural function rejects an awaitable final return value.
 
-This means you can mix sync and async binding functions freely in async natural functions without special handling.
+You can therefore use async binding functions through tools without changing a synchronous Natural function into an async function.
 
-**Failure mode:** if a sync natural function references an async binding function and the LLM calls it, the expression produces an awaitable that cannot be awaited in a sync context. Nighthawk raises an `ExecutionError`. To fix, make the natural function `async`.
+**Failure mode:** if a sync Natural function selects a return expression such as `fetch_result()` and that expression produces an awaitable, Nighthawk raises `ExecutionError`. Make the Natural function `async` to permit an awaitable final return expression. This restriction does not apply when the model calls `fetch_result()` through a tool and writes its resolved result to a binding. See [async execution semantics](specification.md#85-async-execution-model).
 
 ## Cross-block composition
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/philosophy.md

@@ -118,11 +118,13 @@ Nighthawk keeps resilience in Python. The `nighthawk.resilience` primitives are
 
 The host controls exactly which calls are retried, how many attempts are allowed, which exceptions trigger fallback, what gets logged, and what happens on exhaustion. This applies to lightweight provider-backed judgments and to autonomous coding-agent executions. See [Patterns](patterns.md#resilience-patterns) for examples.
 
+Hosts inspect one validated candidate per step. Acceptance preserves its values; explicit replacements are validated before final assignment. The read-only inspection mappings retain references to application values, so trusted hooks use rewrites rather than in-place mutations. Return expressions run once, and rejection cannot undo their side effects.
+
 ### Scoped execution contexts
 
 `run()` establishes the execution boundary by linking a step executor to the current context through an explicit Python `with` statement. `scope()` narrows configuration within an existing run: model override, prompt suffix, executor replacement, implicit references, or oversight.
 
-Nesting follows Python lexical structure. The host program's control flow, not a framework runtime, determines which configuration is active at any point. Runtime behavior lives in Python structures rather than in prose-only instructions or static configuration. See [Runtime configuration](runtime-configuration.md) for details.
+Configuration follows the active execution context and propagates through calls and async tasks using Python context variables. The host program's control flow, not a framework runtime, determines which configuration is active at any point. Runtime behavior lives in Python structures rather than in prose-only instructions or static configuration. See [Runtime configuration](runtime-configuration.md) for details.
 
 ### Tool exposure efficiency
 

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/pydantic-ai-providers.md

@@ -7,10 +7,10 @@ Nighthawk delegates Natural block execution to an LLM. The model is selected thr
 ```py
 import nighthawk as nh
 
-configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
+configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna")
 ```
 
-The default model is `openai-responses:gpt-5.4-nano`. Recommended model for quality: `openai-responses:gpt-5.4`.
+The default model is `openai-responses:gpt-5.6-luna`. Recommended model for quality: `openai-responses:gpt-5.6-terra`.
 
 ## Pydantic AI providers
 
@@ -20,7 +20,7 @@ Examples:
 
 OpenAI:
 ```py
-configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano")
+configuration = nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna")
 ```
 
 Anthropic (direct API):
@@ -83,7 +83,7 @@ Pydantic AI providers accept standard Pydantic AI model settings via the `model_
 
 ```py
 configuration = nh.StepExecutorConfiguration(
-    model="openai-responses:gpt-5.4-nano",
+    model="openai-responses:gpt-5.6-luna",
     model_settings={"temperature": 0.5},
 )
 ```
@@ -96,8 +96,12 @@ Install the required provider package. For example: `pip install pydantic-ai-sli
 
 **`ValueError: Invalid model identifier`**
 
-The model identifier must be in `provider:model` format (e.g., `openai-responses:gpt-5.4-mini`). Check for typos or a missing provider prefix. See the [Pydantic AI documentation](https://ai.pydantic.dev/models/overview/) for valid provider prefixes.
+The model identifier must be in `provider:model` format (e.g., `openai-responses:gpt-5.6-luna`). Check for typos or a missing provider prefix. See the [Pydantic AI documentation](https://ai.pydantic.dev/models/overview/) for valid provider prefixes.
 
 **Provider authentication errors**
 
 Each Pydantic AI provider requires its own credentials (e.g., `OPENAI_API_KEY` for OpenAI). Nighthawk does not manage provider credentials -- see the [Pydantic AI documentation](https://ai.pydantic.dev/models/overview/) for provider-specific credential setup.
+
+## In-memory authentication
+
+Pydantic AI Providers accept caller-owned authentication clients or keys through Python constructors. Construct an authenticated Model and pass it through `StepExecutorConfiguration.model`; see [Caller-authenticated models](runtime-configuration.md#caller-authenticated-models) for the handoff and [the configuration contract](specification.md#52-configuration) for ownership and serialization. The Docker host supplies its own credential input channel. This option does not remove environment-configured provider strings.

{nighthawk_python-0.12.0 → nighthawk_python-0.14.0}/docs/quickstart.md

@@ -21,7 +21,7 @@ Save as `quickstart.py`:
 ```py
 import nighthawk as nh
 
-step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.4-nano"))
+step_executor = nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"))
 
 with nh.run(step_executor):