nighthawk-python 0.11.0__tar.gz → 0.13.0__tar.gz

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/.claude/rules/docs.md

@@ -39,7 +39,7 @@ Public API documentation layering:
 | `coding-agent-backends.md` | Backend users | Backend reference | Backend-specific settings, shared capabilities, skills, MCP tool exposure, working directory, troubleshooting. |
 | `for-coding-agents.md` | Coding agents (LLMs) | Operational guide | Condensed, decision-oriented rules derived from human-oriented docs. Self-contained with absolute URLs. |
 | `specification.md` | Implementors | Canonical spec | Syntax, state layers, tools, outcomes, frontmatter, runtime semantics, observability contract, and custom backend capability/protocol semantics. Numbered section headings. |
-| `philosophy.md` | Evaluators | Design rationale | Execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, design landscape. |
+| `philosophy.md` | Evaluators | Design rationale | Execution model, design landscape, boundary-first consequences, trust and safety boundaries, tradeoffs, and runtime evaluation rationale. |
 | `api.md` | Developers | API reference | Auto-generated from docstrings, including protocol and extension-hook symbols. |
 | `roadmap.md` | Contributors | Future directions | Ideas only. Remove when implemented. |
 | `docs/AGENTS.md` | Coding agents editing docs | Documentation governance | Canonical ownership, page roles, routing rules, and docs test invariants. Symlink to `.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.
@@ -171,7 +171,7 @@ Pages in the Getting started, Patterns & verification, and Configuration nav gro
 
 **`philosophy.md`**
 
-- Owns the cumulative argument: execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, and design landscape.
+- Owns the cumulative argument: execution model, design landscape, boundary-first consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination), trust and safety boundaries, tradeoffs, and runtime evaluation rationale.
 - External references acceptable. Prefer stable URLs with enough inline context to survive link rot.
 - No how-to code examples for patterns in `natural-blocks.md` or `patterns.md`. Exception: positioning examples may reuse function names from those pages.
 

{nighthawk_python-0.11.0 → nighthawk_python-0.13.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.13.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,14 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:4.1.0": {
+      "version": "4.1.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:7d979c4a36d595eb4ab79909caa3f396daf3b6152dcf38e8328ea4eff42206c7",
+      "integrity": "sha256:7d979c4a36d595eb4ab79909caa3f396daf3b6152dcf38e8328ea4eff42206c7"
+    },
+    "ghcr.io/devcontainers/features/node:2.1.0": {
+      "version": "2.1.0",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857",
+      "integrity": "sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857"
+    }
+  }
+}

nighthawk_python-0.13.0/.devcontainer/devcontainer.json

@@ -0,0 +1,16 @@
+{
+	"name": "Python 3.13",
+	"image": "mcr.microsoft.com/devcontainers/python:3-3.13-bookworm",
+	"features": {
+		"ghcr.io/devcontainers/features/docker-in-docker:4.1.0": {},
+		"ghcr.io/devcontainers/features/node:2.1.0": {}
+	},
+	"postCreateCommand": "/bin/sh .devcontainer/postCreateCommand.sh",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"charliermarsh.ruff"
+			]
+		}
+	}
+}

nighthawk_python-0.13.0/.devcontainer/postCreateCommand.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+sudo apt-get update && export DEBIAN_FRONTEND=noninteractive \
+&& sudo apt-get -y install --no-install-recommends ripgrep fzf bubblewrap \
+&& sudo apt-get clean \
+&& sudo rm -rf /var/lib/apt/lists/*
+
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+uv sync
+
+npm install -g pyright
+
+curl -LsSf https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
+curl -LsSf https://claude.ai/install.sh | bash

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/.github/dependabot.yml

@@ -6,6 +6,12 @@
 
 version: 2
 updates:
+ - package-ecosystem: "uv"
+   directory: "/"
+   schedule:
+     interval: weekly
+   cooldown:
+     default-days: 7
  - package-ecosystem: "devcontainers"
    directory: "/"
    schedule:

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/.github/workflows/docs.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Build docs
         run: uv run mkdocs build
 
-      - uses: actions/upload-pages-artifact@v4
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: site
 

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Clarified the boundary-first philosophy page.
+- Clarified multimodal documentation and specification.
+- Raised the minimum Pydantic AI version to 2.37.0 and migrated coding-agent backends to its native-tool and structured-instruction APIs.
+- Raised the MCP minimum version to 2.1.1 and migrated the embedded tool server and content types to the MCP 2 API.
+- Updated the Claude Agent SDK integration to 0.2.151.
+
 ## [0.11.0]
 
 ### Added
@@ -179,7 +240,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.11.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...HEAD
+[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
 [0.9.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...v0.9.0

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/CONTRIBUTING.md

@@ -12,6 +12,14 @@
 uv sync --all-extras --all-groups
 ```
 
+`uv` manages the project virtual environment in `.venv`. Do not create or
+activate a separate virtual environment; run project commands through `uv run`.
+The `.venv` directory is generated and ignored by Git. It can be deleted to
+rebuild the local environment, and the next `uv sync` or `uv run` recreates it.
+
+Declare project dependencies in `pyproject.toml` through `uv add`, rather than
+installing them directly into `.venv` with `uv pip install`.
+
 If you see a `uv` warning about hardlinking (common in containers or cross-filesystem workspaces), suppress it with:
 
 ```bash
@@ -39,13 +47,8 @@ uv run pytest -q       # quiet output
 
 ### Integration tests
 
-Integration tests require provider packages and API keys. Install the provider you need:
-
-```bash
-uv pip install pydantic-ai-slim[openai]
-```
-
-Then run with your `.env` loaded:
+The full setup command installs the OpenAI provider development dependency.
+Run integration tests with your `.env` loaded:
 
 ```bash
 set -a; source .env; set +a; uv run pytest -q
@@ -80,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 |
@@ -90,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
@@ -202,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.11.0 → nighthawk_python-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.11.0
+Version: 0.13.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/
@@ -20,17 +20,17 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: headson>=0.16.1
-Requires-Dist: pydantic-ai-slim>=1.87.0
+Requires-Dist: pydantic-ai-slim>=2.37.0
 Requires-Dist: pydantic>=2.13.3
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: tenacity>=9.1.4
 Requires-Dist: tiktoken>=0.12.0
 Provides-Extra: claude-code-cli
-Requires-Dist: mcp>=1.27.0; extra == 'claude-code-cli'
+Requires-Dist: mcp>=2.1.1; extra == 'claude-code-cli'
 Provides-Extra: claude-code-sdk
-Requires-Dist: claude-agent-sdk==0.1.48; extra == 'claude-code-sdk'
+Requires-Dist: claude-agent-sdk==0.2.151; extra == 'claude-code-sdk'
 Provides-Extra: codex
-Requires-Dist: mcp>=1.27.0; extra == 'codex'
+Requires-Dist: mcp>=2.1.1; extra == 'codex'
 Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/nighthawk-python)](https://pypi.org/project/nighthawk-python)
@@ -68,12 +68,12 @@ For other providers, see [Pydantic AI providers](https://kurusugawa-computer.git
 ```py
 import nighthawk as nh
 
+
 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.11.0 → nighthawk_python-0.13.0}/README.md

@@ -33,12 +33,12 @@ For other providers, see [Pydantic AI providers](https://kurusugawa-computer.git
 ```py
 import nighthawk as nh
 
+
 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.11.0 → nighthawk_python-0.13.0}/docs/api.md

@@ -8,23 +8,31 @@
 ::: 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_capabilities
+        - get_step_context
+        - get_usage_meter
         - get_execution_ref
         - get_implicit_references
+        - get_oversight
         - get_step_executor
         - get_system_prompt_suffix_fragments
+        - get_tools
         - get_user_prompt_suffix_fragments
         - resilience
         - UsageMeter
@@ -93,7 +101,7 @@
       members:
         - StepContext
         - ToolResultRenderingPolicy
-        - get_current_step_context
+        - get_step_context
         - step_context_scope
 
 ## Tool Contracts
@@ -128,3 +136,22 @@
 ## Testing
 
 ::: nighthawk.testing
+
+::: nighthawk.oversight
+    options:
+      members:
+        - Pass
+        - Return
+        - Break
+        - Continue
+        - Raise
+        - StepResult
+        - StepCommit
+        - Rewrite
+        - Accept
+        - Reject
+        - ToolCall
+        - Oversight
+        - OversightRejectedError
+        - StepCommitDecision
+        - ToolCallDecision

{nighthawk_python-0.11.0 → nighthawk_python-0.13.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.
 
@@ -45,7 +45,7 @@ Coding agent backends do not receive native VLM-style user-prompt multimodal inp
 - `BinaryContent` is staged to a local file and referenced in the prompt with `<image>` / `<file>` plus a local file path.
 - URL-based content (`ImageUrl`, `AudioUrl`, `DocumentUrl`, `VideoUrl`) is referenced by URL in the projected prompt text.
 - `UploadedFile` user-prompt content is rejected because these backends cannot resolve provider-owned file identifiers. Tool results still preserve the rest of the payload and replace only the `UploadedFile` item with explanatory fallback text.
-- Tool results cross the backend boundary as MCP content. Image (`BinaryContent.is_image`) and audio (`BinaryContent.is_audio`) items travel natively as `ImageContent` / `AudioContent`; all other `BinaryContent` and `FileUrl` items project to `TextContent` so the MCP path stays symmetric with the text-projected prompt path. When mixed top-level text/multimodal tool-result sequences preserve their original order they satisfy the same `UserContent` rule used for prompt hoisting. The user prompt itself remains text-projected for these backends.
+- Tool results cross the backend boundary as MCP content. Image (`BinaryContent.is_image`) and audio (`BinaryContent.is_audio`) items travel natively as `ImageContent` / `AudioContent`; all other `BinaryContent` and `FileUrl` items project to `TextContent` so the MCP path stays symmetric with the text-projected prompt path. Native MCP video carriage is intentionally unsupported for now because video-modal requirements are unstable; document carriage also remains text-projected unless a future backend advertises an explicit capability. When mixed top-level text/multimodal tool-result sequences preserve their original order they satisfy the same `UserContent` rule used for prompt hoisting. The user prompt itself remains text-projected for these backends.
 - When a successful tool result splits to no text and no user content, the projected prompt stays header-only rather than inserting the preview JSON envelope.
 
 This differs from provider-backed executors that can pass a `tuple[UserContent, ...]` to a multimodal-capable provider API directly.
@@ -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
@@ -281,6 +281,7 @@ Example Natural function that invokes the skill:
 ```py
 import nighthawk as nh
 
+
 @nh.natural_function
 def summarize_feedback(feedback_items: list[str]) -> str:
     def group_feedback_by_topic(feedback_items: list[str]) -> dict[str, list[str]]:

{nighthawk_python-0.11.0 → nighthawk_python-0.13.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.11.0 → nighthawk_python-0.13.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.
+- Only `oversight` accepts `None` to clear 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
 

{nighthawk_python-0.11.0 → nighthawk_python-0.13.0}/docs/index.md

@@ -14,12 +14,12 @@ The same mechanism handles lightweight LLM judgments ("classify this sentiment")
 ```py
 import nighthawk as nh
 
+
 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):
 
@@ -61,7 +61,7 @@ The LLM interprets the mixed-format input list via `<numbers>`, calls the Python
 
 ## Background and project
 
-- **[Philosophy](philosophy.md)** -- Design rationale: execution model, harness evidence, design consequences (resilience, scoped execution contexts, tool exposure, multi-agent coordination, tradeoffs), runtime evaluation rationale, and design landscape.
+- **[Philosophy](philosophy.md)** -- Design rationale: execution model, design landscape, boundary-first consequences, trust and safety boundaries, tradeoffs, and runtime evaluation rationale.
 - **[Roadmap](roadmap.md)** -- Future directions and open questions.
 
 ## Origins

{nighthawk_python-0.11.0 → nighthawk_python-0.13.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):
@@ -139,11 +139,13 @@ Write bindings can use Pydantic models for structured output with automatic vali
 ```py
 from pydantic import BaseModel
 
+
 class ReviewVerdict(BaseModel):
     approved: bool
     reason: str
     risk_level: str
 
+
 @nh.natural_function
 def judge_review(review_data: str) -> ReviewVerdict:
     verdict: ReviewVerdict
@@ -171,7 +173,21 @@ Transport depends on the executor:
 - Provider-backed executors that accept Pydantic AI `UserContent` send the value natively to the VLM API.
 - Coding-agent backends text-project the value (staged local files or URL references). See [Coding agent backends: multimodal inputs](coding-agent-backends.md#multimodal-inputs).
 
-For the normative rendering and transport rules, including dotted-reference hoisting and the remaining v0.11.0 nesting restrictions, see [Specification Section 8.2](specification.md#82-locals-summary).
+Nested multimodal values inside dicts, models, and objects are not recursively hoisted. Keep the prompt boundary explicit by lifting the media-bearing leaf into a helper variable before the Natural block:
+
+```py
+def summarize_report(report: Report) -> str:
+    report_scan = report.attachments.scan_image
+    summary = ""
+    """natural
+    Read <report_scan> and summarize the visual evidence in <:summary>.
+    """
+    return summary
+```
+
+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#822-locals-summary).
 
 ### f-string injection
 
@@ -180,6 +196,7 @@ Inline f-string blocks embed Python expressions directly into the Natural progra
 ```py
 PROJECT_POLICY = ["safety-first", "concise-output", "cite-assumptions"]
 
+
 @nh.natural_function
 def choose_policy(post: str) -> str:
     selected_policy = ""
@@ -219,10 +236,12 @@ Member accesses and function results work too:
 ```py
 from pydantic import BaseModel
 
+
 class Config(BaseModel):
     max_length: int = 100
     style: str = "formal"
 
+
 @nh.natural_function
 def generate(config: Config, topic: str) -> str:
     output = ""
@@ -296,6 +315,7 @@ When a Natural block references a module-level name via `<name>`, it appears in
 def python_average(numbers):
     return sum(numbers) / len(numbers)
 
+
 @nh.natural_function
 def calculate_average(numbers):
     """natural
@@ -341,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
 
@@ -375,11 +395,13 @@ For deterministic functions (no Natural blocks), the boundary is at the function
 ```py
 from pydantic import BaseModel
 
+
 class ScoreInput(BaseModel):
     base: int
     bonus: int
     multiplier: float = 1.0
 
+
 def compute_score(score_input: ScoreInput) -> int:
     return int((score_input.base + score_input.bonus) * score_input.multiplier)
 ```
@@ -392,11 +414,13 @@ For judgment-heavy functions (containing Natural blocks), the boundary moves *in
 from pydantic import BaseModel
 from nighthawk import JsonableValue
 
+
 class ReviewVerdict(BaseModel):
     approved: bool
     reason: str
     risk_level: str
 
+
 @nh.natural_function
 def judge_review(review_data: str | JsonableValue) -> ReviewVerdict:
     verdict: ReviewVerdict
@@ -470,6 +494,7 @@ def get_feedback_summary(topic: str, max_items: int = 10) -> str:
     items = fetch_feedback(topic=topic, limit=max_items)
     return format_summary(items)
 
+
 # Natural block sees only what it needs
 @nh.natural_function
 def analyze_feedback(topic: str) -> str: