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

{nighthawk_python-0.14.0 → nighthawk_python-0.16.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.
-- 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.
+- Native tools (`nh.scope(tools=...)`): `specification.md` documents as spec, `runtime-configuration.md` documents usage and the role split with `task_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.
@@ -222,11 +222,9 @@ Pages in the Getting started, Patterns & verification, and Configuration nav gro
 - `prompt-example` anchors live in `natural-blocks.md` by default (`basic-binding`, `fstring-injection`, `local-function-signature`, `global-function-reference`). Exception: `carry-pattern` lives in `patterns.md` (cross-block composition). Test file: `tests/docs/test_prompt_examples.py`.
 - `for-coding-agents.md` operational examples and core doctrine are guarded by `tests/docs/test_coding_agent_examples.py`. Update the tests when changing executable guidance or non-negotiable rules.
 - When a docs change invalidates an existing test, first decide whether the docs or the test is the canonical truth for that claim, then update both sides to match.
-- Docs architecture regression tests (`tests/docs/test_docs_architecture.py`):
-  - Fail on stale references to deleted/renamed docs (`guide.md`, `design.md`, `providers.md`).
-  - Guard the canonical example relationship between `index.md` and `README.md` via fenced-code-block extraction + normalized exact match.
-  - Guard selected canonical-owner expectations where drift is likely.
-  - Automate `mkdocs.yml` nav entries vs `docs/` file existence as a pytest case.
-  - Guard that obsolete canonical pages do not remain published accidentally alongside their replacements.
+- `tests/docs/test_integrity.py` checks the shared README/index example, navigation targets, and explicit API member inventories.
+- `tests/docs/test_links.py` builds the published site and checks internal links and anchors against rendered HTML, including absolute links to this documentation site.
+- `tests/docs/test_runtime_examples.py` executes marked examples from runtime configuration, embedded execution, and verification, including against the installed wheel.
+- Test current links and executable claims; do not maintain lists of obsolete API names, document paths, or exact governance prose.
 - `mkdocs build` must succeed without `--strict`. Warnings are acceptable.
 - All internal relative links must resolve.

nighthawk_python-0.16.0/.claude/rules/evals.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "evals/**"
+---
+
+# Evaluations
+
+- Comments and docstrings: follow `.claude/rules/python.md`.
+- Under `evals/promptfoo/`, follow `.claude/rules/promptfoo.md`.
+- Files under `evals/*/evidence/` are dated records. Exclude them from comment cleanups and do not rewrite them.

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

@@ -58,7 +58,7 @@ Eval prompts are experimental copies of production code. Keep them in sync; dive
 | `evals/promptfoo/prompts/eval_default.txt` | `configuration.py:DEFAULT_STEP_SYSTEM_PROMPT_TEMPLATE` |
 | `evals/promptfoo/prompts/eval_coding_agent.txt` | No single counterpart; coding agent backends receive this prompt via `system_prompt_file` config. |
 | Suffix variants in `evals/promptfoo/provider.py` (`_build_suffix_*`) | `step_contract.py:build_step_system_prompt_suffix_fragment` |
-| Tool presets in `evals/promptfoo/provider.py` (`_build_tool_preset`) | `tools/registry.py` + `tools/assignment.py` |
+| Tool presets in `evals/promptfoo/provider.py` (`_build_tool_preset`) | `tools/provided.py` (names and descriptions) + `tools/declarations.py` (registration) |
 
 ## Eval evidence
 

nighthawk_python-0.16.0/.claude/rules/python.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Comments and docstrings
+
+Write a comment or docstring only for a fact that the code, names, signatures, types, specification, and tests do not convey.
+
+## Write
+
+- Why a choice was made, especially an intentionally non-obvious one.
+- Upstream library behavior that the code depends on or works around.
+- Platform, process, or environment constraints.
+- Concurrency, cancellation, ordering, and lifetime invariants.
+
+## Do not write
+
+- Restatements of what the code does, including step-by-step narration.
+- Section dividers or heading comments; group code with classes, modules, or name prefixes instead.
+- Planning Ids, phases, or history ("used to", "now").
+- Citations of specification section numbers or test file paths; tests pin specified behavior.
+- Type information already present in annotations.
+
+## Form
+
+- Keep each comment and docstring compact; prefer one line.
+- Use semantic line breaks.
+
+## Text that is not a comment
+
+The following text is consumed at runtime or serves as test data.
+Change it only as a deliberate behavior change:
+
+- Natural docstrings (`"""natural ...`).
+- Docstrings of binding functions and tools, which LLMs may read.
+- Docstrings of Pydantic models that enter LLM-facing JSON schemas, such as `StepFinalResult`.
+- Fixture docstrings that tests assert on or expose to Natural blocks.
+
+Tool directives (`noqa`, `type: ignore`, `pyright: ignore`) are outside these rules.

{nighthawk_python-0.14.0 → nighthawk_python-0.16.0}/.claude/rules/src.md

@@ -7,11 +7,19 @@ paths:
 
 - Prefer concrete code. Add a new abstraction only when the same change uses it from non-test code.
 - Default to module-private names. Export via `__all__` only for stable non-test consumers.
-- If a change expands or changes public API, update or confirm `tests/public/`.
+- If a change expands or changes public API, update the behavior owner tests and confirm export resolution in `tests/test_public_api.py`.
 - Prefer async implementations in `runtime/` and `backends/`; keep sync bridges only at compatibility boundaries.
 - Reuse the existing `NighthawkError` hierarchy before adding a new exception class.
 - Prefer Pydantic (`BaseModel`, `TypeAdapter`) and Pydantic AI primitives over custom validation, parsing, schema, or agent/tool plumbing.
 - Use `opentelemetry.trace` spans at run/scope/step/tool boundaries and `logging.getLogger("nighthawk")` for diagnostics. Do not import `logfire` in `src/`.
 - Use PEP 695 `type` statements for new type aliases.
 - Ask before adding a new `src/` subpackage for a single module.
-- Follow `CONTRIBUTING.md` § Docstring Guide for docstring scope and format.
+
+## Comments and docstrings
+
+Follow `.claude/rules/python.md`. Additionally:
+
+- Public API means the objects rendered by `docs/api.md`. Follow `CONTRIBUTING.md` "Docstring Guide" for their format.
+- Keep examples in `docs/`, not in docstrings.
+- Write an internal docstring only for a fact the code does not convey; otherwise omit it.
+- Write a module docstring only when it states a responsibility boundary that the module name does not convey.

nighthawk_python-0.16.0/.claude/rules/tests.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "tests/**"
+---
+
+# Testing (pytest)
+
+- Prefer deterministic pytest coverage by default. Use helpers from `nighthawk.testing` before reaching for live LLM calls.
+- Use `StubExecutor` from `tests/support/executors.py` only for envelope and runtime parser checks; prefer `nighthawk.testing` for normal Natural-function tests.
+- Keep live-LLM tests in `tests/integration/` and behind the documented environment gates.
+- For Python behavior changes, add or update pytest coverage in the same change and run `uv run pytest -q`.
+- If a change affects public API or README examples, update the behavior owner tests and confirm `tests/test_public_api.py`. If it affects docs examples or anchors, confirm `tests/docs/`.
+- If a change affects prompt rendering, system prompt text, suffix generation, or tool exposure behavior, follow `.claude/rules/promptfoo.md`.
+
+## Comments and docstrings
+
+Follow `.claude/rules/python.md`. Additionally:
+
+- Group tests with test classes or test name prefixes, not divider comments.
+- Write a test docstring only for a non-obvious reason, such as pinned upstream behavior.
+- Write a module docstring only for an operational fact that `tests/README.md` does not document.

{nighthawk_python-0.14.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
@@ -76,17 +75,26 @@ jobs:
         with:
           persist-credentials: false
 
-      # "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
+      # Keep packaging and its fresh installation check independent of the
+      # source test job's dependency cache.
+      - uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: false
 
       - name: Build sdist and wheel
         run: uv build
 
+      - name: Verify documented examples against the installed wheel
+        run: |
+          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 --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.14.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.14.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.14.0 → nighthawk_python-0.16.0}/.gitignore

@@ -8,6 +8,7 @@ evals/promptfoo/outputs/
 evals/promptfoo/*.json
 evals/promptfoo/*.html
 evals/promptfoo/*.csv
+evals/model_tools/outputs/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -224,4 +225,4 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml

{nighthawk_python-0.14.0 → nighthawk_python-0.16.0}/AGENTS.md

@@ -17,6 +17,8 @@
 
 ### Rules
 
+- 改行 (line wrapping) は fixed column で hard-wrap しない.
+  - User が column 上限を明示しない限り, 文末 / clause 区切り / list item など意味の区切りでのみ改行する (semantic line break).
 - Use full words in all identifiers unless listed above.
 - Disallowed abbreviations: `ctx` -> `context`, `cfg` -> `configuration`, `repo` -> `repository`, `opts` -> `options`, `ref` -> `reference`.
 - Map/Dict: `(adjective + "_")* + key + "_to_" + value`.
@@ -33,14 +35,14 @@ A Python 3.13+ library embedding a "Natural" DSL inside Python functions, execut
 
 Natural DSL sources and included markdown are trusted, repository-managed assets. Do not wire untrusted user input into Natural blocks or template preprocessing.
 
-### Repository layout
+ExecPlans: write under `.agents/execplans/` only on request; follow `.agents/PLANS.md`.
 
-- `src/nighthawk/`: Library package.
-- `tests/`: Pytest suite.
-- `docs/`: User-facing documentation (MkDocs).
-- `.agents/`: `execplans/` (on request only), `PLANS.md` (format spec).
-- `.devcontainer/`: Devcontainer definition.
-- `pyproject.toml`, `uv.lock`: Metadata and locked dependencies.
+### Design references
+
+- Read [Philosophy](docs/philosophy.md) when making architectural decisions about function composition, Python integration, agent authorship, accumulated capability, or Core responsibility.
+- Read [Design drivers](docs/design-drivers.md) when using application requirements to justify Core changes or deciding which information belongs in this workspace.
+- Use [Specification](docs/specification.md) for supported behavior and [Roadmap](docs/roadmap.md) for exploratory directions; application scenarios do not establish runtime guarantees.
+- Treat Nighthawk-based development tooling as an application; its presence here does not make it a public library feature.
 
 ## Development workflow
 

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

@@ -7,6 +7,106 @@ 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
+
+- Immutable `StepDefinition` declarations and synchronous/asynchronous embedded step execution use explicit host namespaces and keep validated writeback inside the ordinary lifecycle boundary.
+- Shared binding inference and ordered validation expose `MISSING_ANNOTATION` and structured binding errors through `nighthawk.runtime`.
+
+- Exact Natural definition lookup, optional whole-function call handlers, inert function model declarations, and preserving executor model resolution.
+
+- `StepEnvironment` separates Python lexical bindings, inherited working state, scoped task references, and tracked step assignments, with source-qualified lookup and progressing discovery.
+- Replaceable `ContextBuilder` presentation and shared static value inspection preserve application helper-name collisions and complete discovery continuations, including pages nested in ordinary containers.
+- Common operation admission, awaited inspection, serialized execution, and completion records cover evaluation, assignment, return-expression resolution, and native tools. Failed tool argument admission retains its identity and original exception.
+- Lifecycle start and operation notifications support asynchronous handlers alongside terminal delivery.
+- `ExecutionReference.parent_step_execution_id` correlates joined child steps with their active parent.
+
+### Changed
+
+- Breaking: `ScriptedExecutor` records and rejects unexpected invocations after its response sequence is exhausted. Supply an explicit `default_response=pass_response()` or another response when repetition is intended.
+
+- Breaking: deterministic test responses use resolved `StepResult` values. Replace `return_response("'bug'")` with `return_response("bug")`, `return_response("result", result=42)` with `return_response(42, result=42)`, and `raise_response("failed", error_type="ValueError")` with `raise_response("failed", error_type=ValueError)`. Direct `StepResponse` construction uses `Return(value)`, `Raise(message, error_type)`, `Pass()`, `Break()`, or `Continue()` from `nighthawk.runtime`; strings are never evaluated as expressions.
+
+- Refreshed locked dependencies, including Pydantic 2.14.1, OpenAI 3.31.0, MCP 2.3.0, and Logfire 5.2.0.
+- `task_references` replaces `implicit_references`. Injection remains separate from Python module globals.
+- Executors accept one `StepRequest` and return a resolved `StepCandidate`. Finalization validates all initialized declared outputs, rejects undeclared proposals, and independently validates return values. An initial `Raise` discards pending writes.
+- Commit rewrites validate supplied replacements once without repeating inspection or expression effects; supplied output mappings replace the full selected mapping.
+- Dotted assignment requires an ordinary Pydantic field with `validate_assignment=True`. Right-hand-side evaluation precedes live attribute traversal, and earlier effects are not rolled back on failure.
+- Ordinary application and propagated validator exceptions cross model and backend boundaries unchanged. Runtime input errors and explicit Pydantic AI control signals retain their recovery paths.
+- `Oversight.inspect_operation` replaces both tool-call and return-expression inspection hooks with one `OperationRequest` boundary.
+- Output contracts use supported explicit annotations before initial-value inference; unresolved required annotations fail preparation rather than weakening validation.
+- Lexical support is bounded to source-available functions, live defining-module globals, and existing closure cells, including declared global/nonlocal output writeback. Natural text alone does not capture an otherwise inaccessible outer variable. Parent-state inheritance covers joined child calls; deferred generated expressions and children that outlive their parent have no lifetime guarantee.
+- Integrated Natural execution contracts into the specification and usage guides, with practical parent/child examples and explicit validation, inheritance, and host-delivery boundaries. The README and landing-page example now demonstrate typed output validation.
+- Reframed the philosophy around AI agents building, composing, evaluating, and improving reusable capabilities through Python and Natural, with a compact statement of purpose and Core inclusion criteria.
+- Expanded design drivers with capability construction and reuse scenarios, success conditions, comparisons against ordinary Python and model libraries, and evidence-based decisions about guidance, reusable libraries, simplification, or Core changes.
+
+### 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.
+
+- `run()` and `scope()` reject invalid executor objects before changing the active execution context.
+- Tool-return content projection receives an explicit rendering policy; MCP discovery content respects the caller's selected policy.
+- Verification guidance captures actual model request messages instead of claiming full-prompt DEBUG logging. Published internal links and anchors are checked against the rendered MkDocs site.
+
+- Source instrumentation retains defaults, live closure cells and globals, Python unbound-name behavior, and application names that resemble generated helpers.
+- Variadic output bindings validate their tuple or dictionary elements, preserving `Annotated` constraints and unpacked collection contracts.
+- Python 3.14 callable descriptions recover source annotation spelling without invoking deferred evaluators. Natural decoration preserves deferred annotations, and global-output preparation obtains deferred module contracts.
+- Ordered model tool batches and coding-agent callbacks preserve per-step operation order and stop after terminal operation failure.
+- Native model batches also order argument validation before each corresponding body, preventing later validators from running ahead of an earlier rejection. A scoped Pydantic AI 2.37 compatibility adapter preserves its completion strategies; the dependency range is bounded to that minor series.
+- Coding-agent callbacks use the request's event loop and captured scope; process and transport failures preserve their originating exceptions.
+- Interrupted asynchronous notifications and synchronous bridge shutdown wait for actual owned cleanup completion. `interruption_delivery_timeout` requests notification cancellation but no longer bounds total cleanup time, including handlers that suppress cancellation.
+- Bridge startup interruption joins already launched workers, and asynchronous generator shutdown failures remain inspectable in the propagated exception chain.
+- Caller interruption and notification timeouts preserve cleanup that a notification has already entered through its own cancellation.
+- Synchronous bridge interruption also preserves a root task's existing cancellation cleanup, including its final effects and exception chain.
+- Rejected synchronous DSL returns preserve borrowed application coroutines; only Core-created unstarted await wrappers are disposed.
+
+### Removed
+
+- Unused public `ToolEvaluationError` and `ToolValidationError` classes. Handle finalization failures through `ExecutionError`, independent binding validation through `BindingValidationError`, and application exceptions by their original types; recoverable model tool failures remain structured observations.
+- `scope(implicit_references=...)` and `get_implicit_references()`; use scoped task references and the active step environment.
+- `Oversight.inspect_tool_call`, `Oversight.inspect_return_expression`, and the associated `ToolCall`, `ToolCallDecision`, and `ReturnExpression` types.
+- `Rewrite.return_value`; replace a return through `Rewrite.outcome`.
+- The executor protocol's separate program, context, binding, and control arguments and outcome/bindings tuple result; use `StepRequest` and `StepCandidate`.
+
+### Migration notes for hosts
+
+These changes apply after 0.14.0; earlier release sections describe their own APIs.
+The removed entry points have no compatibility aliases.
+
+| Before | After |
+| --- | --- |
+| `nh.scope(implicit_references=task_name_to_value)` | `nh.scope(task_references=task_name_to_value)`; task injection no longer overrides Python globals. Omission, `UNSET`, replacement, and `Merge` keep their composition roles. |
+| `nh.get_implicit_references()` | During a step, use `nh.get_step_context().environment.task_name_to_value`. Outside a step, retain the task mapping supplied by the host; there is no run-only replacement getter. |
+| `inspect_tool_call(ToolCall)` / `inspect_return_expression(ReturnExpression)` | Install `inspect_operation(operation: OperationRequest)`, returning `Accept` or `Reject`, directly or asynchronously. Inspect `operation.kind` and the applicable expression/tool fields; ordinary helper calls through evaluation have kind `"evaluation"`. |
+| `ToolCallDecision` | Use `Accept` or `Reject` for operation decisions; `StepCommitDecision` additionally permits `Rewrite`. |
+| `Rewrite(return_value=value)` | `Rewrite(outcome=Return(value))`, importing `Return` from `nighthawk.runtime`. Use `Return(None)` for an explicit `None`, subject to the return contract. |
+| `run_step(...)` / `run_step_async(...)` with separate boundary arguments and a tuple result | Accept keyword-only `request: StepRequest` and return `StepCandidate(outcome=..., binding_name_to_value=...)`. Import both types and resolved outcomes from `nighthawk.runtime`; read live values through `request.step_context.environment`. |
+| An outer value mentioned only in Natural text | Pass it explicitly, establish an existing cell with a valid `nonlocal` declaration, or inject a task reference. |
+
+Custom executors still pass through mandatory finalization.
+Ordinary helper exceptions now propagate to Python; return a domain observation when an expected failure should be handled by the model.
+See the [executor contract](docs/specification.md#14-step-executor), [environment boundaries](docs/specification.md#81-state-layers-python-locals-and-step-locals), and [host configuration guide](docs/runtime-configuration.md#oversight-in-scopes) for complete semantics.
+
 ## [0.14.0]
 
 ### Added
@@ -264,7 +364,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.14.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
 [0.12.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.11.0...v0.12.0

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

@@ -45,15 +45,29 @@ uv run pyright
 uv run pytest -q       # quiet output
 ```
 
+Test ownership and helper conventions are documented in [tests/README.md](tests/README.md).
+
+### Design and application evidence
+
+Use [Philosophy](docs/philosophy.md) for design principles and [Specification](docs/specification.md) for supported runtime contracts.
+[Design drivers](docs/design-drivers.md) defines which application information belongs in this workspace and how to distinguish conceptual scenarios from verified behavior.
+When proposing Core changes, show the application composition that exposes the general execution need.
+Nighthawk-based development checks are an application of the library; adopting a local check does not make it a public feature or a requirement for library users.
+
 ### Integration tests
 
 The full setup command installs the OpenAI provider development dependency.
-Run integration tests with your `.env` loaded:
+Integration tests are opt-in; loading credentials alone does not enable them.
+Run OpenAI integration tests with your `.env` loaded:
 
 ```bash
-set -a; source .env; set +a; uv run pytest -q
+NIGHTHAWK_OPENAI_INTEGRATION_TESTS=1 uv run --env-file .env pytest -q tests/integration/
 ```
 
+Add `NIGHTHAWK_OPENAI_MULTIMODAL_INTEGRATION_TESTS=1` to include the image cases.
+Coding agent tests use their respective flags: `NIGHTHAWK_CODEX_INTEGRATION_TESTS=1`, `NIGHTHAWK_CLAUDE_SDK_INTEGRATION_TESTS=1`, or `NIGHTHAWK_CLAUDE_CLI_INTEGRATION_TESTS=1`.
+Their executables and authentication must be available in the test environment.
+
 ### Trace inspection with otel-tui
 
 Nighthawk emits OpenTelemetry traces for step execution. You can inspect them
@@ -130,15 +144,10 @@ Use [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-
 
 ### Scope
 
-Write docstrings only for public API members exported via `__all__` in `src/nighthawk/__init__.py`, plus public classes and functions in these modules:
+This guide covers the public API: the objects rendered by `docs/api.md`.
 
-- `nighthawk.errors`
-- `nighthawk.configuration`
-- `nighthawk.backends.claude_code_sdk`
-- `nighthawk.backends.claude_code_cli`
-- `nighthawk.backends.codex`
-
-Do not write docstrings for names prefixed with `_` (module-private).
+Other docstrings, including those for names prefixed with `_`, are written only for facts the code does not convey and stay compact.
+See `.claude/rules/python.md` for the rules that apply to all comments and docstrings.
 
 ### Structure
 
@@ -153,7 +162,8 @@ Required. Use imperative mood ("Return ...", "Start ...", "Register ..."). Keep
 | `Args` | One or more parameters exist. Do not repeat type information already present in annotations. |
 | `Returns` / `Yields` | Return value is not `None`, or carries meaning that is not obvious from the type alone. |
 | `Raises` | The function raises exceptions that callers are expected to catch. |
-| `Example` | Required for decorators (`natural_function`, `tool`) and context managers (`run`, `scope`). Optional for everything else. |
+
+Do not add an `Example` section; examples live in `docs/`.
 
 #### Classes
 
@@ -196,19 +206,7 @@ def run(
         run_id: Optional identifier for the run. If not provided, a ULID is
             generated automatically.
 
-    Yields:
-        None
-
     Raises:
         RuntimeError: If called while another run is already active.
-
-    Example:
-        ```python
-        executor = AgentStepExecutor.from_configuration(
-            configuration=StepExecutorConfiguration(model="openai-responses:gpt-5.6-luna"),
-        )
-        with nighthawk.run(executor):
-            result = my_natural_function()
-        ```
     """
 ```