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

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

@@ -7,7 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0]
+
+### Added
+- Native Pydantic AI multimodal binding support for Natural block prompts, including `BinaryContent`, URL-based media, `UploadedFile`, and explicit dotted multimodal references.
+- Multimodal tool-result transport for coding-agent backends, preserving mixed text/media order and carrying MCP image/audio content natively where supported.
+- Public scope snapshot getters: `get_implicit_references`, `get_system_prompt_suffix_fragments`, and `get_user_prompt_suffix_fragments`.
+
+### Changed
+- Coding-agent backends now text-project multimodal user prompts into local file paths or URL placeholders while provider-backed executors pass `UserContent` natively.
+- Tool results now retain `ToolOutcome` payloads through backend boundaries so multimodal-capable transports can render native content before falling back to JSON previews.
+- Optimize Natural block runtime prompt
+- Update dependencies
+
+### Fixed
+- Cleaned up staged multimodal prompt files when text projection fails before a projected request is returned.
+
+## [0.10.0]
+
+### Added
+- Scope-level oversight hooks in `nh.scope(oversight=...)` for synchronous tool-call inspection and step-commit inspection.
+- Oversight trace events and backend/wrapper coverage for accept/reject decision paths.
+- Validation for `vote(min_success=...)` bounds (`>= 1` and `<= count`) with matching tests.
+- Tool-boundary regression test ensuring recoverable `ToolBoundaryError` is wrapped into JSON payload.
+
+### Changed
+- Finalized committed binding validation at step boundaries, added write-root dirty tracking for dotted `nh_assign`, and aligned prompt/docs with the new validation contract.
+- Introduced `ExecutionRef` (`run_id`, `scope_id`, optional `step_id`) and renamed runtime accessor to `get_execution_ref`.
+- Added top-level module access for `oversight` and `resilience`, with docs and public API tests aligned.
+- Consolidated tool-call oversight inspection to a single wrapper-side entry point and removed duplicate inspection guard state.
+- Unified tool result handling to TypedDict-based envelope types (`ToolResult`, `ToolError`) instead of Pydantic models.
+- Clarified tool-boundary policy: recoverable tool-call failures are JSON-envelope responses, host invariant violations propagate as Python exceptions.
+- Updated specification and runtime configuration docs to codify envelope-vs-raise boundary semantics for tool-call failures.
+- Updated API and patterns docs for `ExecutionRef`, `get_execution_ref`, and oversight/resilience namespace exposure.
+
+### Fixed
+- Backend handler now preserves wrapped tool error payloads (`{"value": ..., "error": ...}`) without dropping error details.
+- Tool-call context propagation now preserves step identity in execution ref during step execution.
+
+## [0.9.0]
+
 ### Changed
+
 - Redesigned `nh.scope()` around `mode` semantics (`"inherit"` default, `"replace"` for explicit replacement).
 - Scope prompt suffix arguments now use list-based forms: `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments`.
 
@@ -138,7 +179,10 @@ 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.8.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.11.0...HEAD
+[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
 [0.8.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.0...v0.6.1

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

@@ -81,6 +81,7 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx promptfoo
 |---|---|
 | `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-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,6 +91,7 @@ PFOO="cd evals/promptfoo && PROMPTFOO_PYTHON=\"$(uv python find)\" npx 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-agents.yaml` — Coding agent only: claude-code-cli and codex with reduced test set.
 
 #### Directory layout

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.9.0
+Version: 0.11.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.68
-Requires-Dist: pydantic>=2
-Requires-Dist: pyyaml>=6
-Requires-Dist: tenacity>=9
-Requires-Dist: tiktoken>=0.12
+Requires-Dist: pydantic-ai-slim>=1.87.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.26; extra == 'claude-code-cli'
+Requires-Dist: mcp>=1.27.0; extra == 'claude-code-cli'
 Provides-Extra: claude-code-sdk
 Requires-Dist: claude-agent-sdk==0.1.48; extra == 'claude-code-sdk'
 Provides-Extra: codex
-Requires-Dist: mcp>=1.26; extra == 'codex'
+Requires-Dist: mcp>=1.27.0; extra == 'codex'
 Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/nighthawk-python)](https://pypi.org/project/nighthawk-python)

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/api.md

@@ -18,12 +18,17 @@
         - StepContextLimits
         - JsonableValue
         - to_jsonable_value
-        - ExecutionContext
+        - ExecutionRef
         - get_current_step_context
         - get_current_usage_meter
-        - get_execution_context
+        - get_execution_ref
+        - get_implicit_references
         - get_step_executor
+        - get_system_prompt_suffix_fragments
+        - get_user_prompt_suffix_fragments
+        - resilience
         - UsageMeter
+        - oversight
 
 ## Errors
 
@@ -123,4 +128,3 @@
 ## Testing
 
 ::: nighthawk.testing
-

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/coding-agent-backends.md

@@ -38,6 +38,18 @@ All three backends provide capabilities not available with Pydantic AI providers
 - **Callable discoverability:** Same rules as [Natural blocks](natural-blocks.md#functions-and-discoverability).
 - **Project-scoped files:** The CLI loads its own project files (CLAUDE.md, AGENTS.md) from `working_directory`.
 
+### Multimodal inputs
+
+Coding agent backends do not receive native VLM-style user-prompt multimodal input. Nighthawk projects multimodal prompt content into the CLI text channel instead:
+
+- `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.
+- 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.
+
 ### Working directory
 
 All three backends accept `working_directory` in their model settings. This absolute path determines:

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/for-coding-agents.md

@@ -14,6 +14,7 @@ You are expected to write, review, and debug Python code that uses Nighthawk as
 - Prefer explicit, typed write bindings. Runtime inference exists for unannotated write bindings, but new code should not rely on it.
 - Keep outputs narrow and typed, especially when using coding agent backends. A block may do broad internal work, but the Python boundary should stay small.
 - When prompt context is truncated and you see `<snipped>`, first reduce context surface or split the block. Increase `StepContextLimits` only after simplification fails.
+- Explicit dotted multimodal references such as `<holder.photo>` can still be omitted under tight `locals_max_items` / `locals_max_tokens`; resize budgets rather than assuming hoisting is unconditional.
 
 ## 2. First decision: should this be Natural at all?
 
@@ -327,7 +328,7 @@ Async rule:
 Resilience rule:
 
 - Keep retry, fallback, timeout, budget, and circuit-breaker policy in Python, not inside Natural text.
-- Import from `nighthawk.resilience` (not re-exported from `nighthawk`):
+- Import primitives from `nighthawk.resilience`. After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`:
 
 ```py
 from nighthawk.resilience import retrying

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/natural-blocks.md

@@ -63,6 +63,7 @@ Three sections:
 
 - **`<<<NH:PROGRAM>>>`** -- your Natural block text (after sentinel removal and `textwrap.dedent`).
 - **`<<<NH:LOCALS>>>`** -- step locals, rendered alphabetically as `name: type = value`.
+  Nighthawk renders the full current locals snapshot by design; control context size by deciding which locals exist before the block.
 - **`<<<NH:GLOBALS>>>`** -- module-level names referenced via `<name>` that are not in step locals.
 
 ### One block, one task
@@ -129,7 +130,7 @@ def detect_language(text: str):
     return language
 ```
 
-Type annotations on write bindings enable validation and coercion at commit time.
+Type annotations on write bindings enable validation and coercion at step finalization for values that are actually committed.
 
 ### Pydantic model write bindings
 
@@ -161,6 +162,17 @@ When the LLM assigns a value to `verdict`, Nighthawk validates and coerces it to
 
 Read and write bindings are rendered identically in the LOCALS section (e.g., `name: type = value`). The `<name>` vs `<:name>` distinction in the Natural program text is the signal that tells the LLM which names it may update. At runtime, Nighthawk enforces the distinction: read bindings block rebinding, while write bindings allow rebinding and commit values back to Python locals.
 
+### Multimodal bindings
+
+A binding may hold a Pydantic AI multimodal value -- `BinaryContent`, `ImageUrl`, `AudioUrl`, `DocumentUrl`, `VideoUrl`, or `UploadedFile`. These are first-class binding values: reference them with `<name>` like any other binding, and Nighthawk renders the inline placeholder (`<image>` for image media, `<file>` otherwise) in the LOCALS or GLOBALS line. Explicit dotted leaf references use the same mechanism, and dotted `list` / `tuple` leaves are hoisted when they satisfy the same `UserContent` rule as top-level bindings. `UploadedFile` is only usable as native user-prompt content on provider-backed executors that can resolve the provider-owned file reference; coding-agent backends reject it at the user-prompt boundary.
+
+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).
+
 ### f-string injection
 
 Inline f-string blocks embed Python expressions directly into the Natural program text. The expression is evaluated when Python evaluates the f-string -- before the LLM sees the prompt.
@@ -323,6 +335,8 @@ python_average: (numbers)
 
 Function parameters and local variables appear in LOCALS. Module-level names referenced via `<name>` that are _not_ in locals appear in GLOBALS. Nighthawk renders callable entries with their full signature and docstring intent -- but only when type information is available.
 
+This is a deliberate tradeoff: LOCALS stays a flat, predictable snapshot of what Python has already bound. If you want less prompt context, keep fewer locals alive at the block boundary. Section truncation still follows the normal lexicographic rendering order, so under tight budgets an explicitly referenced dotted multimodal leaf can still be omitted along with any other later entry.
+
 When you pass a module-level callable as a function parameter with a generic type (`object`, `Any`, or no annotation), the name moves from GLOBALS to LOCALS and **its signature is erased**. The LLM cannot discover the correct arguments or return type.
 
 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.

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/patterns.md

@@ -326,7 +326,8 @@ Natural blocks are non-deterministic by nature. Production deployments need stra
 from nighthawk.resilience import retrying, fallback, vote, timeout, budget, circuit_breaker
 ```
 
-Import directly from `nighthawk.resilience`. Resilience primitives are not re-exported from the top-level `nighthawk` namespace.
+Import directly from `nighthawk.resilience`.
+After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`.
 
 ### Retrying
 

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/philosophy.md

@@ -23,7 +23,7 @@ calculate_average([1, "2", "three", "cuatro", "五"])  # 3.0
 
 Binding functions like `<python_average>` appear in the prompt as a compact signature line. The LLM's pre-trained Python knowledge lets it reason about types, return values, and composition from the signature alone, without JSON Schema or protocol overhead. See [Tool exposure efficiency](#tool-exposure-efficiency) for the quantitative comparison with MCP and CLI tool exposure.
 
-With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates the type annotation at runtime, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
+With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates committed write bindings at step finalization, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
 
 With [coding agent backends](coding-agent-backends.md), the same boundary contract applies, but each Natural block becomes an autonomous agent execution. The agent can read files, run commands, and invoke skills -- while typed bindings enforce what crosses the boundary back to Python. The same `scope()` and `run()` context managers that structure human-written workflows are equally legible to a coding agent constructing workflows programmatically. When a coding agent operates inside a Natural block, binding functions appear as Python signatures in the prompt:
 

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/runtime-configuration.md

@@ -35,6 +35,15 @@ with nh.run(step_executor):
     # Add implicit global references for this scope
     with nh.scope(implicit_references={"search_repository": search_repository}):
         typed_labeling_step(ticket_text)
+
+    # Add synchronous oversight for this scope
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
 ```
 
 Parameters:
@@ -42,6 +51,7 @@ Parameters:
 - `mode`: scope composition mode. Default: `"inherit"`.
 - `step_executor_configuration`: replace the entire configuration.
 - `step_executor`: replace the step executor entirely.
+- `oversight`: scope-level synchronous tool-call inspection and step-commit inspection hooks.
 - `system_prompt_suffix_fragments`: scope-level system suffix fragments.
 - `user_prompt_suffix_fragments`: scope-level user suffix fragments.
 - `implicit_references`: scope-level implicit global references.
@@ -56,10 +66,16 @@ Mode semantics:
   - Explicit `[]` or `{}` clears inherited list/dict values.
   - Explicit list/dict values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
 
+For `oversight`, omitted means inherit the current hooks, while explicit `None` clears them for the nested scope.
+
 The context manager yields the resolved `StepExecutor` for the scope.
 
 `StepExecutorConfiguration` also accepts `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` (tuples of strings) as baseline suffix fragments for the whole run. In `mode="inherit"`, scope-level fragments are appended after configuration-level fragments.
 
+System prompt suffix fragments are rendered with the same `$tool_result_max_tokens` placeholder used by built-in prompt templates. Use `$$tool_result_max_tokens` if the literal text must appear in the final prompt.
+
+Text-projected backends that expose Nighthawk tools automatically add a short tool-result preview warning to the system prompt. You do not need to add a separate preview warning fragment for coding-agent or other text-projected tool transports.
+
 ## Scoped implicit references
 
 `implicit_references` can inject global helper functions as step capabilities:
@@ -138,6 +154,59 @@ with nh.scope(mode="replace", system_prompt_suffix_fragments=None):
 ```
 
 The same `replace` semantics apply to `user_prompt_suffix_fragments`.
+
+## Reading the active scope
+
+Within an active `nh.run()` context, three snapshot getters expose the current scope's accumulated state:
+
+- `nh.get_implicit_references()` returns a `Mapping[str, object]` snapshot of implicit references.
+- `nh.get_system_prompt_suffix_fragments()` returns the system prompt suffix fragments as a `tuple[str, ...]`.
+- `nh.get_user_prompt_suffix_fragments()` returns the user prompt suffix fragments as a `tuple[str, ...]`.
+
+The prompt suffix getters return only fragments accumulated via `nh.scope(...)`; configuration-level baseline fragments from `StepExecutorConfiguration` are not included.
+
+Use these when composing nested scopes from a host helper: read the parent state, derive a subset, then re-enter via `nh.scope(mode="replace", ...)`. Both narrowing (keeping a subset) and masking (removing specific keys) are expressed by deriving a new mapping and passing it under `mode="replace"`.
+
+```py
+with nh.run(step_executor):
+    with nh.scope(implicit_references={"a": helper_a, "b": helper_b}):
+        current = nh.get_implicit_references()
+        narrowed = {name: value for name, value in current.items() if name != "b"}
+        with nh.scope(mode="replace", implicit_references=narrowed):
+            triage_issue(ticket_text)
+```
+
+All three getters require an active run context. Outside `nh.run()` they raise `NighthawkError`, matching `nh.get_step_executor()` semantics. Catch `NighthawkError` if a helper needs to detect the absence of a run.
+
+## Synchronous oversight in scopes
+
+Use `nh.scope(oversight=...)` when the host needs synchronous inspection around tool calls or a final rewrite/reject checkpoint before Nighthawk commits a step result.
+
+```py
+def inspect_tool_call(tool_call: nh.oversight.ToolCall) -> nh.oversight.ToolCallDecision:
+    if tool_call.tool_name == "delete_file":
+        return nh.oversight.Reject("Deletion must be approved by a human.")
+    return nh.oversight.Accept()
+
+
+def inspect_step_commit(proposal: nh.oversight.StepCommitProposal) -> nh.oversight.StepCommitDecision:
+    if "result" in proposal.proposed_binding_name_to_value:
+        return nh.oversight.Rewrite(rewritten_binding_name_to_value={"result": "reviewed"})
+    return nh.oversight.Accept()
+
+
+with nh.run(step_executor):
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
+```
+
+Tool rejections are returned to the model as a recoverable observation. On preview-based paths this appears with `error.kind == "oversight"` in the projected preview; provider-backed paths that use Pydantic AI's standard retry loop may instead surface the same structured details as a retry prompt whose final line is compact JSON. Step rejections raise `nh.oversight.OversightRejectedError` to the host. Rewrite values still flow through the normal step finalization path. For the normative boundary rule on which tool-call failures are projected back to the model versus propagated as host exceptions, see [Specification Section 8.3](specification.md#83-tool-boundary-contract-built-in-tooling).
+
 ## Mixing executors
 
 Use `nh.scope(step_executor=...)` to switch executors within a single run. This is the standard pattern for mixing a cheap classifier with a deep autonomous step:
@@ -181,12 +250,13 @@ See [Specification Section 8.2](specification.md#82-prompt-context) for the full
 
 ## Runtime execution identity
 
-Each `nh.run()` generates an `ExecutionContext` with a unique `run_id` (trace root) and `scope_id`. Nested `nh.scope()` calls generate new `scope_id` values while keeping the same `run_id`.
+Each `nh.run()` generates an `ExecutionRef` with a unique `run_id` (trace root) and `scope_id`. Nested `nh.scope()` calls generate new `scope_id` values while keeping the same `run_id`.
 
 ```py
-context = nh.get_execution_context()
-context.run_id    # trace root -- stable across nested scopes
-context.scope_id  # current scope -- changes with each nh.scope()
+execution_ref = nh.get_execution_ref()
+execution_ref.run_id    # trace root -- stable across nested scopes
+execution_ref.scope_id  # current scope -- changes with each nh.scope()
+execution_ref.step_id   # None outside active step execution
 ```
 
 Use `run_id` to correlate distributed agent processes in logs and traces. Use `scope_id` to identify the current logical execution context. See [Specification Section 10](specification.md#10-runtime-scoping) for the full specification and [Verification: observability](verification.md#observability) for tracing integration.

{nighthawk_python-0.9.0 → nighthawk_python-0.11.0}/docs/specification.md

@@ -88,7 +88,7 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
         - `step_system_prompt_template`: system prompt template that defines the step execution protocol.
         - `step_user_prompt_template`: full user prompt template including section delimiters.
     - `context_limits`: limits for rendering dynamic context into the prompt.
-    - `json_renderer_style`: [headson](https://github.com/kantord/headson) rendering style used in prompt context and tool result envelopes. Default: `"default"`. Available values: `"strict"` (valid JSON, no annotations), `"default"` (pseudo-JSON with omission markers like `…`), `"detailed"` (JS-like with inline comments such as `// N more`).
+    - `json_renderer_style`: [headson](https://github.com/kantord/headson) rendering style used in prompt context and projected tool-result previews. Default: `"default"`. Available values: `"strict"` (valid JSON, no annotations), `"default"` (pseudo-JSON with omission markers like `…`), `"detailed"` (JS-like with inline comments such as `// N more`).
     - `system_prompt_suffix_fragments`: optional baseline system prompt suffix fragments for this executor configuration.
     - `user_prompt_suffix_fragments`: optional baseline user prompt suffix fragments for this executor configuration.
 
@@ -103,17 +103,18 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - Fields: `locals_max_tokens`, `locals_max_items`, `globals_max_tokens`, `globals_max_items`, `value_max_tokens`, `object_max_methods`, `object_max_fields`, `object_field_value_max_tokens`, `tool_result_max_tokens`.
 - `JsonableValue`
     - Type alias for JSON-serializable Python values (`dict | list | str | int | float | bool | None`).
-- `ExecutionContext`
+- `ExecutionRef`
     - Frozen dataclass representing runtime execution identity.
     - `run_id`: the Id of the outermost run (trace root).
     - `scope_id`: the Id of the current scope.
+    - `step_id`: the Id of the current step when available, otherwise `None`.
 
 ### 5.4. Runtime accessors
 
 - `nighthawk.get_current_step_context() -> StepContext`
     - Get the `StepContext` for the currently executing Natural block. Raises if no step is active.
 
-See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_context`).
+See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_ref`).
 
 ## 6. Natural block detection
 
@@ -239,7 +240,7 @@ The template uses `$program`, `$locals`, and `$globals` placeholders, substitute
 
 #### 8.2.2. Locals summary
 
-The locals summary renders selected names from `step_locals`.
+The locals summary renders selected names from `step_locals`. It is a transparent projection of Python-visible local state at the Natural block boundary. Nighthawk MUST NOT automatically suppress otherwise eligible LOCALS entries based on reference frequency, VLM cost, or multimodal payload type; users control prompt cost by reducing the Python locals that exist at the block boundary.
 
 Selection:
 
@@ -268,6 +269,19 @@ Rendering format:
     - Method expansion is bounded by `context_limits.object_max_methods`; field expansion is bounded by `context_limits.object_max_fields`; each field value preview is bounded by `context_limits.object_field_value_max_tokens`.
     - If object member limits are exceeded, explicit omission lines are added: `name.<methods>: <snipped N public methods>` and/or `name.<fields>: <snipped N public fields>`.
 - Other non-callable values: `name: type_name = json_value`, where `json_value` is bounded by `context_limits.value_max_tokens`.
+- Top-level Pydantic AI multimodal values are rendered as `name: TypeName = ` followed by inline user content in the prompt payload.
+    - This applies to top-level locals/globals entries.
+- Top-level `list` / `tuple` values are also rendered as inline user content when every item is valid Pydantic AI `UserContent` and at least one item is multimodal.
+    - The binding line still renders once, for example `photos: list = `, followed by the original top-level item order.
+    - Pure text-only sequences do not use this rule; they remain preview-rendered values.
+- Explicit dotted references whose resolved leaf resolves to hoistable inline user content add a separate section line for that full dotted path (for example `holder.photo: BinaryContent = ` followed by inline user content).
+    - Only explicitly referenced dotted paths are added this way.
+    - This is a leaf-only rendering rule, not recursive object-graph extraction.
+    - Dotted-path resolution is attribute-oriented only. Each segment after the top-level name is resolved against discovered object fields using the same safe field sources as object capability rendering.
+    - Dotted-path resolution does not treat `Mapping` keys as attribute segments. For mapping access, use Python expressions or helper functions (for example `nh_eval("payload['photo']")`) rather than `<payload.photo>`.
+    - `list` / `tuple` leaves follow the same hoisting rule as top-level bindings: the sequence is hoisted when every item is valid Pydantic AI `UserContent` and at least one item is multimodal.
+    - Non-multimodal dotted references remain preview text inside object capability rendering.
+    - When a dotted multimodal reference is rendered as a separate section line, the corresponding field is omitted from the owning object capability block to avoid duplication. The field still consumes a slot in the `object_max_fields` budget.
 
 Callable disambiguation considers both top-level callable entries and object method entries in the same section.
 
@@ -289,6 +303,7 @@ Token budgeting:
 - Section budgets remain governed by `locals_max_tokens` / `globals_max_tokens` and item budgets by `locals_max_items` / `globals_max_items`.
 - Object method and field expansion is additionally governed by object-specific limits listed above.
 - Line-level token counting includes newline separators during budget checks.
+- Each rendered multimodal content item is charged a fixed internal budgeting heuristic against the section budget so that multimodal-heavy sections still trigger truncation. This is not a provider-side token estimate.
 
 Observability:
 
@@ -299,6 +314,7 @@ Truncation:
 
 - Rendering is bounded by `context_limits.locals_max_tokens` and `context_limits.locals_max_items`.
 - When the limit is reached before all entries are rendered, a `<snipped>` marker is appended and a diagnostic log message is emitted on the `nighthawk` logger.
+- Because section rendering remains lexicographic, tight item or token budgets can affect which bindings remain visible, including explicitly referenced dotted multimodal leaves.
 
 #### 8.2.3. Globals summary
 
@@ -307,7 +323,7 @@ The globals summary renders module-level names that are referenced in the Natura
 Reference extraction:
 
 - The Natural program text is scanned for unescaped `<name>` tokens (both read bindings `<name>` and dotted references `<name.field>`).
-- For dotted references, only the top-level name (before the first `.`) is extracted.
+- For dotted references, the top-level name (before the first `.`) participates in globals selection, and the full dotted path remains available for multimodal leaf rendering.
 - Escaped references (`\<name>`) are not extracted. The backslash is removed in the program text passed to the model.
 
 Selection:
@@ -392,6 +408,7 @@ Eval tool:
 
 - `nh_eval(expression: str) -> object`
     - Evaluate a Python expression and return the result. Use to inspect values, call functions, and mutate objects in-place.
+    - In-place mutations performed via `nh_eval` are not runtime-validated.
     - If the evaluated expression is awaitable, it is awaited before returning.
 
 Binding tool:
@@ -421,13 +438,16 @@ Semantics of `nh_assign`:
     - Traverse attributes for each intermediate segment.
     - Assign using attribute assignment on the final segment.
     - Validation:
-        - Validate only when runtime type metadata is available; otherwise assign without validation.
+        - Validate only the final assigned field when runtime type metadata is available; otherwise assign without validation.
 
 Commit and mutation notes:
 
 - Commit selection is controlled only by `<:name>` bindings.
 - `<:name>` selects which top-level names are committed from `step_locals` into Python locals at Natural block boundaries.
-- Dotted mutation is independent of `<:name>`.
+- Dotted `nh_assign` on a write binding root marks that root as dirty for commit selection.
+- Dotted `nh_assign` on a read binding root does not participate in commit selection.
+- Final validation is applied only to committed write bindings at step finalization.
+- Dotted mutation on read bindings and in-place mutation via `nh_eval` are outside the final validation guarantee.
 
 Write tool return value:
 
@@ -437,16 +457,47 @@ Write tool return value:
     - validation details (when relevant)
     - error details (on failure)
 
-Tool result JSON format:
-
-All tool results are wrapped in a JSON envelope with the following structure:
-
-- Success: `{"value": <bounded JSON rendering>, "error": null}`
-- Failure: `{"value": null, "error": {"kind": "<category>", "message": "<detail>", "guidance": "<recovery hint>"}}`
-
-Error kind categories: `invalid_input`, `resolution`, `execution`, `transient`, `internal`.
-
-The `value` field is bounded by `context_limits.tool_result_max_tokens` and may be summarized using [headson](https://github.com/kantord/headson) truncation when the full rendering exceeds the token budget. Headson is a structure-aware JSON summarizer: it parses the full JSON tree, then selects representative nodes to produce a compact preview that preserves the shape and key values of the data within a strict byte budget (analogous to `head`/`tail` but for structured data).
+Tool result transport contract:
+
+- Internally, tool execution produces a canonical `ToolOutcome` with:
+    - `payload`: the success payload, which may include native Pydantic AI multimodal values
+    - `error`: `null` on success or a structured error object on failure
+- The host also derives a projected preview observation for text-only transports, logging, and tracing.
+    - This projection may be derived lazily at the transport or tracing boundary rather than eagerly at tool execution time.
+- Text-projected backends that expose Nighthawk tools automatically add system-prompt guidance that tool-result previews may be lossy and are bounded by `context_limits.tool_result_max_tokens`.
+- The projected preview uses the following JSON shape:
+    - Success: `{"value": <bounded JSON rendering>, "error": null}`
+    - Failure: `{"value": null, "error": {"kind": "<category>", "message": "<detail>", "guidance": "<recovery hint>"}}`
+- Multimodal-capable transports MAY send top-level multimodal payload items natively instead of embedding them into the preview text.
+    - When they do, they preserve the original top-level content item order from the tool payload, including text/media adjacency for qualifying mixed `list` / `tuple` payloads.
+    - In v0.11.0, the MCP tool-return transport carries only image (`BinaryContent.is_image`) and audio (`BinaryContent.is_audio`) items natively (as `mcp.types.ImageContent` / `mcp.types.AudioContent`). All other `BinaryContent` and `FileUrl` items, including document and video, project to `mcp.types.TextContent` so the transport stays symmetric with text-projected backends. Future expansion of native carriage to document or video items via `mcp.types.EmbeddedResource` is intentionally out of scope in v0.11.0 and is not guaranteed by this specification. Multimodal-capable providers that bypass MCP still send those items natively via `ToolReturnPart.files`.
+- Provider-backed backends that use Pydantic AI's standard tool loop SHOULD surface general `ToolOutcome.error` failures as ordinary tool results rather than retry prompts.
+    - In v0.11.0, the dedicated retry-prompt path is reserved for tool argument validation failures before tool execution (for example via `RetryPromptPart.model_response()`).
+    - When a provider-backed backend surfaces a tool failure without native multimodal content, it SHOULD use the same structured preview envelope shape described above.
+- User-prompt transport is backend-dependent.
+    - Provider-backed executors that accept Pydantic AI `UserContent` MAY send user-prompt multimodal content natively.
+    - Text-projected backends (including coding agent backends that must talk to a CLI text channel) project multimodal user prompt content to text placeholders plus local file paths or URL references instead of sending native VLM input.
+- For tool results, backends SHOULD preserve top-level mixed text/multimodal order when the payload is a `list` / `tuple` whose items are all valid `UserContent` and at least one item is multimodal.
+- When that ordered-segmentation rule does not apply, text-projected transports SHOULD derive tool-return text from Pydantic AI's `ToolReturnPart.model_response_str_and_user_content()` and project the returned `user_content` separately.
+- MCP transports SHOULD use the same fallback split when ordered segmentation does not apply: one text observation derived from `tool_response_text`, followed by the extracted `user_content` items in order.
+- If a rich transport fails while projecting an otherwise recoverable tool result, the backend SHOULD degrade to the projected preview text rather than fail the step.
+- When Pydantic AI reports a successful empty split (`tool_response_text == ""` and extracted `user_content` is empty), backends MUST preserve that as an empty success rather than falling back to the projected preview envelope.
+    - Text-projected transports render only their normal tool-return framing with no preview JSON body.
+    - MCP-style native transports return an empty content list for that tool result.
+- `BinaryContent` values can be staged to local files for text-projected transports because the host already has the bytes.
+- URL-based values such as `ImageUrl` / `FileUrl` MAY be transported natively by multimodal-capable provider backends, but text-projected backends and the MCP tool-return transport treat them as URL references only.
+- In v0.11.0, nested multimodal values inside dict/model/object structure are not hoisted; they remain part of the preview rendering only, except for top-level or explicitly referenced dotted-leaf `list` / `tuple` bindings whose items are valid `UserContent`.
+- `UploadedFile` values are provider-owned references. Backends that cannot resolve the provider file identifier MUST reject them at the user-prompt boundary.
+- For tool results, backends that cannot resolve an `UploadedFile` MUST preserve the rest of the top-level payload and replace only that item with an explanatory text fallback instead of silently dropping it.
+
+Error kind categories: `invalid_input`, `resolution`, `execution`, `transient`, `internal`, `oversight`.
+
+Boundary rule for tool-call failures:
+
+- If the model can recover by changing tool arguments, choosing another tool, or continuing without the tool, the failure MUST be projected back to the model as a structured error observation.
+- Host invariant violations (for example, broken runtime contract or invalid host-side oversight hook contract) MAY propagate as Python exceptions to the host instead of being projected.
+
+The projected `value` field is bounded by `context_limits.tool_result_max_tokens` and may be summarized using [headson](https://github.com/kantord/headson) truncation when the full rendering exceeds the token budget. Headson is a structure-aware JSON summarizer: it parses the full JSON tree, then selects representative nodes to produce a compact preview that preserves the shape and key values of the data within a strict byte budget (analogous to `head`/`tail` but for structured data).
 
 Atomicity requirement:
 
@@ -570,10 +621,11 @@ The required runtime object for step execution is:
 
 - `step_executor` (required): a strategy object responsible for executing steps (Natural blocks).
 
-Runtime execution identity is modeled separately in `ExecutionContext`:
+Runtime execution identity is modeled separately in `ExecutionRef`:
 
 - `run_id`: the Id of the outermost run (trace root). This serves as the golden thread that connects distributed agent processes (e.g. parent, child, grandchild) across process boundaries in observability tools.
 - `scope_id`: the Id of the current (possibly nested) run scope. This serves as the identity of the current logical execution context.
+- `step_id`: the Id of the current step when available. Outside active step execution it is `None`.
 
 Nighthawk does not own workspace filesystem concerns (such as include resolution or host file operations). Those concerns belong to the host application layer that embeds Nighthawk.
 
@@ -582,14 +634,15 @@ API:
 
 - `nighthawk.run(step_executor: StepExecutor, *, run_id: str | None = None)`
     - Replaces the current context step executor with the provided step executor.
-    - Generates a new `ExecutionContext` for the duration of the `with`.
+    - Generates a new `ExecutionRef` for the duration of the `with`.
     - Uses provided `run_id` when given; otherwise generates a new `run_id` (trace root).
     - Always generates a fresh `scope_id`.
     - Can be used even when no step executor is currently set.
-- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
+- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, oversight: Oversight | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
     - Enter a nested scope within the current run.
     - Requires an existing step executor.
     - Generates a new `scope_id` (keeps the current `run_id`).
+    - `oversight` omitted means inherit the current hooks; explicit `None` clears them for the nested scope.
     - `mode="inherit"` (default):
         - Appends prompt suffix fragment lists.
         - Merges `implicit_references` additively with conflict checks.
@@ -601,7 +654,7 @@ API:
     - Yields the resolved `StepExecutor` for the scope.
 - `nighthawk.get_step_executor() -> StepExecutor`
     - Get the current step executor. Raises if unset.
-- `nighthawk.get_execution_context() -> ExecutionContext`
+- `nighthawk.get_execution_ref() -> ExecutionRef`
     - Get the current runtime execution identity. Raises if unset.
 
 ### 10.1. Observability contract (OpenTelemetry span/event)