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

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

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0]
+
+### Changed
+
+- Breaking: operation inspection now returns `Accept`, `RejectOperation`, or `AbortStep`. Commit inspection accepts `Accept`, `Rewrite`, or `AbortStep`. Replace terminal `Reject(reason)` decisions with `AbortStep(reason)`; there is no legacy alias or implicit change to recoverable behavior.
+- Breaking: `StepAbortedError` replaces `OversightRejectedError`. Terminal records use `failure_stage="oversight_abort"` and `abort_reason` instead of `oversight_rejection` and `rejection_reason`. Aborted operation records use status `"aborted"`; recoverable refusals use `"rejected"`.
+- Breaking: explicit commit `AbortStep` decisions also propagate `StepAbortedError` instead of an `ExecutionError` wrapper, matching operation inspection; terminal delivery may still supply a host exception.
+- Standard agent output processing resolves candidate expressions before leaving its model loop. Rejected return expressions can be corrected without recreating the step or replaying prior operations.
+- Rejection stops the remaining calls in the same visible model response before argument validation, records them as `"skipped"`, and discards that response's final candidates. Nighthawk makes `early` dispatch follow emission order; ordinary Pydantic AI runs retain their own strategies.
+- MCP/SDK tool responses carry error indicators and structured refusal information. Coding-agent internal batches and inference requests remain outside Core's visible response/request boundaries.
+
+### Added
+
+- `OperationRejection`, `OperationRejectedError`, and exported `OperationDeliveryError` support direct executor recovery and correlated failure diagnostics. Refusals retain live state, earlier effects, request accounting, and ordinary finalization.
+- Deterministic model, executor, lifecycle, ordering, and backend tests cover refusal feedback, skipped calls, cancellation, notification failures, limits, and nested execution. See [operation feedback](docs/operation-feedback.md) for examples and migration details.
+
 ## [0.16.0]
 
 ### Changed
@@ -364,7 +380,8 @@ Invalid initial results fail before oversight; use resilience retries to recover
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.16.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.15.0...v0.17.0
 [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

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.16.0
+Version: 0.17.0
 Summary: A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
 Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
 Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/docs/api.md

@@ -181,9 +181,11 @@
         - StepCommit
         - Rewrite
         - Accept
-        - Reject
+        - RejectOperation
+        - AbortStep
         - Oversight
-        - OversightRejectedError
+        - StepAbortedError
+        - OperationDecision
         - StepCommitDecision
 
 ## Lifecycle
@@ -257,6 +259,10 @@ See [Embedded execution](embedded-execution.md) for executable synchronous and a
         - OperationRequest
         - OperationFinished
         - OperationError
+        - OperationRejection
+        - OperationRejectedError
+        - OperationDeliveryError
+        - OperationStatus
 
 ::: nighthawk.runtime.expression
     options:

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/docs/coding-agent-backends.md

@@ -60,6 +60,11 @@ All three backends accept `working_directory` in their model settings. This abso
 
 If a backend CLI process fails (e.g., crashes, times out, or returns an invalid response), Nighthawk surfaces the failure as an `ExecutionError`. See [Patterns](patterns.md#error-handling) for error handling patterns.
 
+Operation inspection can return `RejectOperation` to deliver structured refusal through MCP/SDK error results while keeping the transport available for another inspected request.
+`AbortStep`, inspection failures, and operation notification failures terminate the step even if the coding agent catches a tool error.
+Core cannot identify a coding agent's invisible response batches or individually gate its internal inference requests.
+The [operation feedback support matrix](operation-feedback.md#ordering-and-backend-boundaries) describes these limits and the distinct behavior of directly visible Pydantic AI responses.
+
 ### Allowed tool names
 
 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.

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/docs/design-drivers.md

@@ -187,6 +187,26 @@ The deterministic evidence covers absent parent bindings, preparation failures,
 It does not establish that separating names prevents repeated model calls or improves judgments.
 Assess those hypotheses through application evaluations, including independent reuse and the effort needed to declare shared dependencies.
 
+## Correcting refused operations within a Natural step
+
+**Status:** Execution contracts have deterministic coverage in `tests/runtime/test_operation_recovery.py` and `tests/backends/test_rejection_feedback.py`, with executable [model and custom-executor examples](operation-feedback.md).
+No independent application case or comparative model-quality evaluation is recorded.
+
+A host may refuse a proposed operation while still permitting a different way to complete the task.
+Previously every operation-inspection rejection ended the step, even if an executor caught the exception.
+Ordinary helper return values can communicate expected domain findings, but cannot change that Core-owned inspection and finalization contract.
+Reimplementing the operation pipeline in application executors would duplicate state, notification, and termination responsibilities.
+
+Core therefore separates `RejectOperation`, which refuses one body and exposes deliberate feedback, from `AbortStep`, which ends the inspected step.
+The same step retains its live environment, prior effects, model history, and request controls while the model or custom executor chooses another operation.
+Refusal records survive successful finalization; failed notifications and terminal stops cannot become ordinary feedback.
+Visible model batches stop at refusal, while provider-internal batches remain a documented backend boundary.
+
+Applications own the policy, alternative operations, acceptance criteria, and any durable evidence or improvement process.
+Core does not infer that a later accepted output means the task was completed, automatically retry an operation, or add a separate repair agent or policy engine.
+The deterministic tests establish execution behavior, not improved judgment, accumulated capability, or comparative advantage.
+Further application evidence should compare successful corrections, unacceptable effects, authoring and maintenance burden, and inference cost against ordinary Python/model-library compositions.
+
 ## Using Nighthawk to develop Nighthawk
 
 **Status:** Conceptual application direction.

nighthawk_python-0.17.0/docs/operation-feedback.md

@@ -0,0 +1,229 @@
+# Operation feedback
+
+Use `RejectOperation` when an operation must not execute but another choice can still accomplish the task.
+Use `AbortStep` when the current Natural step must end.
+Both decisions run before the operation body, after admission and any native-tool argument validation.
+Earlier effects, validators, and trusted inspection hooks are not rolled back.
+
+Expected domain findings usually belong in ordinary Python return values.
+For example, a search helper can return an empty result and a checker can return typed findings.
+Operation oversight is the connection point for deciding whether an inspected operation may execute; Core does not supply domain policies, approval products, or automatic repair strategies.
+
+## Decisions and records
+
+| Decision | Operation body | Same step | Observation |
+| --- | --- | --- | --- |
+| `Accept()` | Runs normally | Continues | Ordinary operation result. |
+| `RejectOperation(reason, guidance=None)` | Does not start | May choose another operation | `OperationFinished.status == "rejected"`, with `rejection`; direct APIs raise `OperationRejectedError`. |
+| `AbortStep(reason)` | Does not start | Ends; success cannot replace the stop | `OperationFinished.status == "aborted"`; `StepAbortedError` and a failed terminal record. |
+
+`OperationRejectedError.rejection` and the operation record share the same `OperationRejection`.
+Its `request` identifies the operation and step; `reason` and `guidance` are deliberately model-visible.
+`model_feedback()` returns those public fields and execution-start information without exposing live tool arguments or diagnostic exceptions.
+Reasons are nonempty strings; guidance is an optional string.
+
+An inspector must return a decision normally.
+Unexpected exceptions, invalid decisions, and notification failures are terminal, including exceptions whose classes otherwise represent retries or recoverable input errors.
+`OperationDeliveryError.finished` retains the operation fact and `delivery_cause` retains its notification failure.
+Successful delivery is an in-process notification attempt, not an external storage transaction.
+
+## Synchronous and asynchronous model examples
+
+This deterministic example verifies execution semantics without a provider service.
+It is not evidence that a particular model reliably chooses a good alternative.
+
+```py
+import asyncio
+
+from pydantic_ai.messages import ModelMessage, ModelResponse, ToolCallPart, ToolReturnPart
+from pydantic_ai.models.function import AgentInfo, FunctionModel
+
+import nighthawk as nh
+from nighthawk.oversight import Accept, OperationDecision, Oversight, RejectOperation
+from nighthawk.runtime import OperationRequest
+
+
+effects: list[str] = []
+
+
+def forbidden() -> int:
+    effects.append("forbidden body")
+    return 2
+
+
+def inspect_operation(request: OperationRequest) -> OperationDecision:
+    if request.expression == "forbidden()":
+        return RejectOperation("This helper is unavailable.", "Evaluate 1 + 1 instead.")
+    return Accept()
+
+
+async def inspect_operation_async(request: OperationRequest) -> OperationDecision:
+    await asyncio.sleep(0)
+    return inspect_operation(request)
+
+
+@nh.natural_function
+def calculate() -> int:
+    """natural
+    Calculate the requested value using a permitted operation and return it.
+    """
+    return 0
+
+
+@nh.natural_function
+async def calculate_async() -> int:
+    """natural
+    Calculate the requested value using a permitted operation and return it.
+    """
+    return 0
+
+
+def make_executor() -> nh.AgentStepExecutor:
+    requests = 0
+
+    async def respond(messages: list[ModelMessage], information: AgentInfo) -> ModelResponse:
+        nonlocal requests
+        requests += 1
+        if requests == 1:
+            return ModelResponse(parts=[ToolCallPart("nh_eval", {"expression": "forbidden()"}, "proposal")])
+        assert requests == 2
+        assert any(isinstance(part, ToolReturnPart) and part.outcome == "denied" for message in messages for part in message.parts)
+        return ModelResponse(
+            parts=[ToolCallPart(information.output_tools[0].name, {"result": {"kind": "return", "return_expression": "1 + 1"}}, "finish")]
+        )
+
+    return nh.AgentStepExecutor.from_configuration(configuration=nh.StepExecutorConfiguration(model=FunctionModel(respond)))
+
+
+def run_sync_example() -> int:
+    with (
+        nh.run(make_executor()),
+        nh.scope(
+            task_references={"forbidden": forbidden},
+            oversight=Oversight(inspect_operation=inspect_operation),
+        ),
+    ):
+        return calculate()
+
+
+async def run_async_example() -> int:
+    with (
+        nh.run(make_executor()),
+        nh.scope(
+            task_references={"forbidden": forbidden},
+            oversight=Oversight(inspect_operation=inspect_operation_async),
+        ),
+    ):
+        return await calculate_async()
+
+
+assert run_sync_example() == 2
+assert asyncio.run(run_async_example()) == 2
+assert effects == []
+```
+
+The standard agent resolves return expressions inside its active output-processing loop as well.
+If the model proposes `forbidden()` as its return expression, it can receive the same refusal and submit a different expression.
+The resolved Python value then passes ordinary output validation and commit inspection without reevaluating the expression.
+`inspect_step_commit` accepts only `Accept`, `Rewrite`, or `AbortStep`; a refused commit does not reopen inference.
+Explicit `AbortStep` decisions propagate `StepAbortedError` from either inspector, unless terminal delivery raises a host exception.
+Its `subject` identifies `"operation"` or `"step_commit"`.
+
+## Custom executor example
+
+This example extends the definitions above.
+The executor owns its choice of the next operation and does not inspect or modify private failure state.
+
+```py
+from nighthawk.runtime import OperationRejectedError, Return, StepCandidate, StepRequest, eval_expression, eval_expression_async
+
+
+class CorrectingExecutor:
+    def run_step(self, *, request: StepRequest) -> StepCandidate:
+        try:
+            value = eval_expression(request.step_context, "forbidden()")
+        except OperationRejectedError as refusal:
+            assert refusal.rejection.reason == "This helper is unavailable."
+            value = eval_expression(request.step_context, "1 + 1")
+        return StepCandidate(outcome=Return(value))
+
+    async def run_step_async(self, *, request: StepRequest) -> StepCandidate:
+        try:
+            value = await eval_expression_async(request.step_context, "forbidden()")
+        except OperationRejectedError as refusal:
+            assert refusal.rejection.reason == "This helper is unavailable."
+            value = await eval_expression_async(request.step_context, "1 + 1")
+        return StepCandidate(outcome=Return(value))
+
+
+with (
+    nh.run(CorrectingExecutor()),
+    nh.scope(
+        task_references={"forbidden": forbidden},
+        oversight=Oversight(inspect_operation=inspect_operation_async),
+    ),
+):
+    assert calculate() == 2
+    assert asyncio.run(calculate_async()) == 2
+assert effects == []
+```
+
+A custom executor may instead report that no permitted solution exists, using its ordinary result contract.
+Refusal does not force an automatic retry or prove that a task was completed.
+Application acceptance checks still determine whether the final result is useful and its effects acceptable.
+
+## Ordering and backend boundaries
+
+For a visible model response containing operations A, B, C, and an output proposal, a refusal of B preserves completed A, records B as rejected, and records C and the output as skipped.
+Skipped calls do not run argument validators, inspectors, or bodies.
+Their `blocked_by_operation_id` points to B; skipped output proposals have request kind `"output"`.
+The model receives refusal and skipped-call feedback before choosing a new response.
+An earlier output candidate in that same response cannot override a later refusal; its completed expression effects are retained without replay.
+Tool calls follow emission order inside Nighthawk, including when the borrowed agent selects `early`.
+Pydantic AI's native-output precedence still applies: under `early`, structured text can be evaluated before co-emitted function calls; other strategies prioritize the calls.
+A refusal at that native-output boundary skips the co-emitted calls and consumes the ordinary output retry budget.
+
+| Execution route | Refusal feedback and correction | Batch boundary |
+| --- | --- | --- |
+| Standard Pydantic AI tools | Denied tool return, correlated feedback, same agent run. | Remaining calls in the visible response are skipped; `early` follows emission order inside Nighthawk. |
+| Standard structured/native output | Rejected candidate expressions return through output retry handling, before leaving the agent run. | The same visible response barrier applies when output and function calls coexist. |
+| Codex and Claude Code MCP/SDK tools | Error indicator and structured refusal, followed by separately inspected tool requests; transport remains open. | Internal provider response batches are not exposed, so Core cannot identify or skip invisible siblings. |
+| Direct operation API / custom executor | Catch `OperationRejectedError` and choose the next operation explicitly. | The executor owns call grouping and ordering. |
+| Borrowed protocol agent without Pydantic AI capabilities | The borrowed agent owns model feedback and candidate-recovery integration; an unhandled refusal propagates. | No automatic loop or replay is provided. |
+
+Python function composition also defines nesting.
+An `AbortStep` permanently ends its target step.
+An uncaught child failure fails the parent operation; a Python helper may explicitly catch that child failure and return an application result.
+It cannot change the child's terminal fact or resume that child execution.
+Run-wide cancellation is a separate host responsibility.
+
+## Limits and interruption
+
+Correction retains working values, object identity, active policy, request history, and usage counters.
+Each additional Core/Pydantic AI-visible request passes the existing capability admission and accounting boundary.
+Function-tool refusals consume ordinary request/tool-call usage; rejected output expressions also consume the configured output retry budget.
+Host stops and exhausted limits remain effective even if another output candidate was accepted earlier in that response.
+
+The aggregate `UsageMeter` is not an in-progress request gate.
+Use the existing [request usage and admission hooks](runtime-configuration.md#request-usage-and-admission) for controls between requests.
+Coding-agent internal inference calls retain the backend's own limits and observability; this feature does not claim to observe them individually.
+Unlimited configurations and arbitrary Python executor loops have no universal termination guarantee.
+
+Interruption does not authorize detached processing or skipped cleanup.
+Core retains its existing operation/terminal notification and asynchronous bridge responsibilities.
+Application callbacks remain responsible for correctly shielding their own asynchronous cleanup under their execution framework's cancellation rules.
+
+## Migration from 0.16
+
+| Previous API | Replacement |
+| --- | --- |
+| Terminal `Reject(reason)` in either inspector | `AbortStep(reason)`. |
+| `OversightRejectedError` | `StepAbortedError`. |
+| Commit rejection caught as `ExecutionError` | Catch `StepAbortedError` for an explicit `AbortStep`; arbitrary commit-inspector failures retain the ordinary terminal error contract. |
+| Operation rejection intended to permit another choice | Return `RejectOperation(reason, guidance=...)`; direct executors catch `OperationRejectedError`. |
+| Terminal `failure_stage="oversight_rejection"` and `rejection_reason` | `failure_stage="oversight_abort"` and `abort_reason`. |
+| Operation status `"rejected"` for a host termination | `"aborted"`; `"rejected"` now specifically identifies a recoverable operation refusal. |
+| Assuming every operation record represents an attempted body | Check `status`, `phase`, and `evaluation_started`; later model calls may be `"skipped"`. |
+
+The old symbols are removed; there is no compatibility mode that silently changes their meaning.
+Operation and terminal records are host-owned evidence, not automatic snapshots of a mutable object graph or durable exactly-once storage.

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/docs/runtime-configuration.md

@@ -330,15 +330,15 @@ import nighthawk as nh
 from nighthawk.runtime import OperationRequest, Return
 
 
-def inspect_operation(operation: OperationRequest) -> nh.oversight.Accept | nh.oversight.Reject:
+def inspect_operation(operation: OperationRequest) -> nh.oversight.OperationDecision:
     if operation.kind == "native_tool" and operation.tool_name == "delete_file":
-        return nh.oversight.Reject("Deletion requires host approval.")
+        return nh.oversight.RejectOperation("Deletion is unavailable.", "Choose an operation that preserves the file.")
     return nh.oversight.Accept()
 
 
 def inspect_step_commit(commit: nh.oversight.StepCommit) -> nh.oversight.StepCommitDecision:
     if isinstance(commit.outcome, Return) and commit.outcome.value is None:
-        return nh.oversight.Reject("A result is required.")
+        return nh.oversight.AbortStep("A result is required.")
     return nh.oversight.Accept()
 
 
@@ -350,7 +350,9 @@ oversight = nh.oversight.Oversight(
 
 Install the configuration with `nh.scope(oversight=oversight)` inside an active run.
 Operation inspection precedes execution and cannot undo earlier side effects.
-Rejection terminates the step; it is not a model retry.
+`RejectOperation` returns deliberate feedback without executing that operation, allowing another choice within the same step.
+`AbortStep` terminates the current step; catching its exception cannot make that step succeed.
+The [operation feedback guide](operation-feedback.md) covers synchronous/asynchronous hooks, custom executors, model correction, and backend limits.
 Commit inspection receives resolved `Pass`, `Return`, `Break`, `Continue`, or `Raise` outcomes and validated output values.
 `Raise.error_type` is an exception class; its constructor runs only after inspection.
 

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/docs/specification.md

@@ -913,7 +913,9 @@ Its commit mapping is empty.
 
 `Oversight.inspect_step_commit` receives one validated commit and may return its decision directly or asynchronously.
 `Accept` preserves validated values without repeating validators.
-`Reject` produces a failed terminal record before generated Python assignments.
+`AbortStep(reason)` produces a failed terminal record before generated Python assignments and propagates `StepAbortedError`.
+Commit inspection accepts `Accept`, `Rewrite`, or `AbortStep`; `RejectOperation` is invalid at this boundary.
+Commit refusal never reopens model inference.
 `Rewrite` accepts `outcome` and `binding_name_to_value`, each defaulting to `UNSET`; an empty rewrite is invalid.
 A supplied mapping completely replaces the committed writes, including when it is empty.
 `Rewrite(outcome=Return(None))` explicitly supplies `None`, subject to the return annotation and allowed-kind checks.
@@ -931,20 +933,44 @@ Finalization cannot undo earlier application calls, object mutation, or validato
 
 ### 10.3. Operation inspection
 
-`Oversight.inspect_operation(OperationRequest)` returns `Accept` or `Reject`, directly or asynchronously.
+`Oversight.inspect_operation(OperationRequest)` returns `OperationDecision = Accept | RejectOperation | AbortStep`, directly or asynchronously.
 Evaluation, assignment, model return-expression resolution, native tools, and inspection operations share this boundary.
 The request includes the execution reference, operation Id, kind, and applicable expression, assignment target, tool arguments, and expected type.
 Admission runs before inspection; inspection runs before any operation body or await of its result.
+`Accept` permits execution.
+`RejectOperation(reason, guidance=None)` prevents that operation's body and produces an `OperationRejection` with the request and deliberately model-visible feedback.
+Direct operation APIs raise `OperationRejectedError`, whose `rejection` exposes that same record; a custom executor may catch it and choose another operation in the same step.
+`OperationRejection.model_feedback()` exposes status, operation and step identities, reason, guidance, and `evaluation_started=False`, without serializing live arguments or diagnostic exceptions.
+Reasons must be nonempty strings; guidance is an optional string.
+`AbortStep(reason)` prevents execution and ends the current step with `StepAbortedError`.
+It does not cancel an enclosing run or prohibit a calling Python helper from deliberately handling the child's failure.
+An uncaught child failure also fails its parent operation; it is not a new inspection decision about the parent.
+
 Requests execute serially within each step: in emission order for an ordered model batch, and in admission order otherwise.
 Pydantic AI capability hooks cannot reorder an ordered batch across this boundary.
-Argument validation is included in that ordering: a rejected or terminally failed call stops subsequent validators as well as tool bodies.
-Operation dispatch preserves Pydantic AI validators, retries, deferrals, and completion strategies within the Nighthawk boundary.
+Argument validation is included in that ordering.
+After a recoverable rejection, the remaining calls in that model response are skipped before validation or execution, including output proposals and pending deferred calls.
+Each skipped call receives an operation Id and an `OperationFinished(status="skipped", phase="admission", evaluation_started=False)` with `blocked_by_operation_id` referring to the refused operation.
+Skipped output proposals use request kind `"output"`; an accepted candidate has no artificial output operation, but its expressions use the normal operation pipeline.
+An earlier accepted candidate in the same response is discarded if a later operation is rejected; its already completed expression effects remain.
+A subsequent model response makes new operation requests, each inspected normally.
+Inside Nighthawk, Pydantic AI's `early` strategy follows emission order as `graceful` does, so an output cannot bypass an earlier proposed action.
+`exhaustive` retains its output selection rules, subject to the rejection barrier and terminal limits.
+Operation dispatch preserves Pydantic AI validators, retry budgets, and explicit deferral signals.
 Pydantic AI runs outside that boundary use their own dispatch behavior.
 Under `exhaustive`, upfront Pydantic AI function-call events have `args_valid=None` until the corresponding ordered validation runs; Nighthawk operation records retain the actual admission result.
 Explicit Python concurrency inside a helper and separate child steps retain their own execution semantics.
+Direct executor calls do not implicitly form a model-response batch; the executor owns their selection and ordering.
+
+Recoverable rejection does not mark the step failed, restart it, roll back effects, repeat prior effects, or clear its working environment.
+Operation identities differ across attempts; step identity and live application values remain intact.
+Ordinary result validation, commit inspection, writeback, and one terminal delivery still apply.
+A model's decision to finish after a rejection does not establish task correctness; application acceptance checks remain necessary.
 
-Operation rejection and inspection failures are terminal for that step.
-Later queued operations cannot execute their bodies, and an executor cannot suppress the failure and finalize a successful candidate.
+`AbortStep`, inspection failures, operation delivery failures, and interruptions remain terminal for that step.
+Later queued operations cannot execute their bodies, and an executor cannot suppress a recorded terminal failure and finalize a successful candidate.
+Only a normally returned `RejectOperation` decision authorizes recoverable oversight feedback.
+An inspector raising `OperationRejectedError`, `OperationError`, or `ModelRetry` has failed; exception type alone never makes that inspection recoverable.
 Ordinary exceptions from application helpers and native tools propagate to Python.
 Runtime syntax, name-resolution, and value-validation errors provide recoverable operation feedback; Pydantic AI control signals retain their native meaning.
 Classify failures by origin, not exception class: `NameError` or `ValueError` from a helper body remains an application exception.
@@ -952,7 +978,12 @@ An uncaught child Natural exception preserves its child terminal event and also
 Return expected domain failures as ordinary helper results when the model should act on them; Python helpers may catch specific domain exceptions to construct those results.
 Preserve explicit `ModelRetry`, `CallDeferred`, and `ApprovalRequired` signals through Pydantic AI machinery, and distinguish Pydantic validation failures from propagated validator exceptions.
 Each completed operation delivers an `OperationFinished` fact with its phase, whether evaluation started, and its live result or original exception.
+Statuses are `succeeded`, `rejected`, `aborted`, `skipped`, `failed`, and `interrupted`.
+Recoverable rejection includes `rejection`; explicit `AbortStep` produces `aborted` and its original `StepAbortedError`.
 A notification failure does not change that fact or replay the operation.
+`OperationDeliveryError.finished` preserves the refusal or skipped-operation fact, and `delivery_cause` preserves the notification failure.
+Notification failure is never ordinary model feedback, even if the callback raises a retry or rejection exception.
+The existing interruption and cleanup responsibilities continue to apply.
 
 Pydantic AI validates native and provided tool arguments before entering the tool body boundary.
 A failed schema or argument-validator admission receives an operation Id and an `OperationFinished` record with `phase="admission"` and `evaluation_started=False`, retaining the original exception and unvalidated arguments.
@@ -961,13 +992,28 @@ Validation errors remain recoverable through Pydantic AI; ordinary exceptions pr
 If a capability repairs invalid arguments, the failed admission remains recorded and the repaired request enters a separately identified inspected operation; the tool body runs once.
 Approval and deferral during argument validation remain in Pydantic AI's designated machinery and do not fabricate a failed admission.
 
-Model adapters resolve return expressions through this pipeline once before returning a candidate.
+Standard Pydantic AI model adapters resolve candidate expressions through this pipeline inside output processing, before leaving the model loop.
+Recoverable refusal becomes model-visible feedback, allowing a corrected expression in the same agent run and step.
+Resolved candidates carry Python values to the runner; finalization never reevaluates their expressions.
+Function-tool refusals use denied tool returns, distinct from successful values, and include structured operation correlation.
+MCP and SDK transports set their error indicator and retain the canonical refusal feedback without lossy preview truncation.
+Coding-agent transports expose subsequent individual tool requests, but do not expose the provider's internal response batches; they cannot promise that invisible sibling calls are skipped.
+They do not silently convert recoverable refusal into a terminal error.
+Protocol agents supplied with `from_agent` that do not execute Pydantic AI capabilities own candidate-recovery integration; an unhandled rejection propagates instead of triggering automatic replay.
 Async Natural returns may await the expression result once; sync Natural returns reject awaitable expression results.
 Custom executors may directly construct `Return(value)` without evaluating an expression or creating an operation event.
 The runner independently validates the resolved value and all selected outputs before commit inspection.
 Expression-syntax policies belong in operation inspection; policies relating return values to committed outputs belong in commit inspection.
 A bindings-only rewrite can intentionally diverge from an earlier return value.
 
+Correction requests retain the same request admission hooks, usage accounting, retry limits, and active configuration.
+Function-tool refusals consume ordinary requests and tool-call usage; output-expression refusals also consume the existing output retry budget.
+Limits and host stop decisions cannot be overridden by another candidate from the same response.
+No refusal-specific budget or universal termination guarantee is added for unlimited configurations or arbitrary custom executors.
+The request boundary is the Core/Pydantic AI-visible request; internal coding-agent inference calls retain their backend-specific controls.
+`UsageMeter` aggregates completed agent runs and is not an in-progress per-request gate; use the request capability boundary for that purpose.
+See [operation feedback](operation-feedback.md) for executable examples and the backend support matrix.
+
 ### 10.4. Terminal delivery and host ledgers
 
 `nh.scope(lifecycle=nh.lifecycle.StepLifecycle(on_step_finished=callback))` installs a callback accepting `StepFinished` and returning `None` or an awaitable completion.
@@ -980,11 +1026,11 @@ Generated Python resolves the candidate, performs each selected write assignment
 
 `StepFinished` is the discriminated union of frozen `StepCompleted`, `StepRaised`, `StepFailed`, and `StepInterrupted`, with respective `kind` values `completed`, `raised`, `failed`, and `interrupted`. All carry `execution_reference`, `processed_natural_program`, `input_binding_name_to_value`, `allowed_step_kinds`, and `assigned_binding_name_to_value`. Preparation-dependent fields are `None` when not established; empty mappings or tuples mean known empty values. Runtime references require both step identity fields. Mapping and tuple structure is snapshotted; contained Python objects retain their exact types and identity. Hosts must serialize or copy deliberately for durable records.
 
-`StepCompleted.outcome` is the final Pass/Return/Break/Continue. `StepRaised` holds a final Raise and its successfully constructed `exception`, including domain exceptions subclassing NighthawkError. Model-selected exception expressions use the operation pipeline; exception constructor failures are `StepFailed` at `raise_construction`, not domain raises. `StepFailed` holds `original_exception`, `failure_stage`, optional `attempted_outcome`, and optional `validated_binding_name_to_value`. Explicit rejection additionally carries `inspection_subject` and `rejection_reason`. Invalid hook decisions remain inspection failures.
+`StepCompleted.outcome` is the final Pass/Return/Break/Continue. `StepRaised` holds a final Raise and its successfully constructed `exception`, including domain exceptions subclassing NighthawkError. Model-selected exception expressions use the operation pipeline; exception constructor failures are `StepFailed` at `raise_construction`, not domain raises. `StepFailed` holds `original_exception`, `failure_stage`, optional `attempted_outcome`, and optional `validated_binding_name_to_value`. An explicit `AbortStep` decision about this step additionally carries `inspection_subject` and `abort_reason`. Invalid hook decisions and exceptions raised by inspectors remain inspection failures.
 
-`FailureStage` identifies preparation, started_delivery, operation_inspection, operation_execution, operation_delivery, executor, outcome_validation, binding_validation, return_await, return_validation, commit_inspection, rewrite_validation, oversight_rejection, raise_construction, or binding_assignment.
+`FailureStage` identifies preparation, started_delivery, operation_inspection, operation_execution, operation_delivery, executor, outcome_validation, binding_validation, return_await, return_validation, commit_inspection, rewrite_validation, oversight_abort, raise_construction, or binding_assignment.
 Classification uses structured runtime state, not exception text.
-Terminal failures recorded by the operation pipeline propagate unchanged; other internal execution failures use `ExecutionError(step_failed)` chained from the original exception unless delivery supplies a host exception.
+Terminal failures recorded by the operation pipeline and explicit commit `AbortStep` decisions propagate unchanged; other internal execution failures use `ExecutionError(step_failed)` chained from the original exception unless delivery supplies a host exception.
 DSL Raise propagates its prepared exception.
 
 The callback may append the record to a host-owned authoritative ledger and raise a public host exception containing that exact stored event. For StepFailed, core explicitly chains the callback exception from `original_exception`; for StepRaised, from the prepared domain exception. If the callback rethrows the exact original exception object, core preserves its existing cause rather than chaining the exception to itself. Arbitrary callback exceptions are preserved and never reclassified or redelivered. `StepDeliveryError(execution_reference, cause)` is available for host adapters reporting storage failure; its `delivery_cause` does not imply a durable event exists. During ordinary execution failure, the outward chain prioritizes the execution exception and the storage cause remains available in `delivery_cause`.

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/evals/model_tools/inspection_study.py

@@ -33,7 +33,7 @@ from pydantic_ai.usage import UsageLimits
 import nighthawk as nh
 from nighthawk.json_renderer import render_json_text
 from nighthawk.lifecycle import StepLifecycle
-from nighthawk.oversight import Accept, Oversight, OversightRejectedError, Reject
+from nighthawk.oversight import AbortStep, Accept, Oversight, StepAbortedError
 from nighthawk.runtime import ContextRequest, OperationFinished, StepEnvironment, StepRequest, inspect_value
 from nighthawk.runtime.environment import EnvironmentSource
 from nighthawk.runtime.expression import compile_expression, evaluate_compiled_expression
@@ -134,7 +134,7 @@ class TrialState:
         # Its Python helper reads that shared object, not an implicit parent environment.
         self.workspace.step_name_to_value = self.context.environment.snapshot_working_state()
 
-    async def inspect_operation(self, request: Any) -> Accept | Reject:
+    async def inspect_operation(self, request: Any) -> Accept | AbortStep:
         expression = request.expression or ""
         called_names = set()
         try:
@@ -155,7 +155,7 @@ class TrialState:
                     called_names.add(selected.args[0].value)
         if "rejected_action" in called_names:
             self.approvals.append("rejected")
-            return Reject("Synthetic host policy rejected this action")
+            return AbortStep("Synthetic host policy rejected this action")
         if "approved_action" in called_names:
             await asyncio.sleep(0)
             self.approvals.append("approved")
@@ -429,7 +429,7 @@ async def run_trial(
                     value = TypeAdapter(state.workspace.output_name_to_type["result"]).validate_python(
                         state.context.environment.step_name_to_value["result"]
                     )
-    except OversightRejectedError:
+    except StepAbortedError:
         outcome = "rejected"
     except Exception as exception:
         exception_type = type(exception).__name__

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/mkdocs.yml

@@ -67,6 +67,7 @@ nav:
       - Natural blocks: natural-blocks.md
       - Executors: executors.md
       - Runtime configuration: runtime-configuration.md
+      - Operation feedback: operation-feedback.md
       - Embedded execution: embedded-execution.md
   - Patterns & verification:
       - Patterns: patterns.md

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.16.0"
+version = "0.17.0"
 description = "A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.16.0 → nighthawk_python-0.17.0}/src/nighthawk/backends/mcp_boundary.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 import tiktoken
 from opentelemetry import context as otel_context
@@ -29,6 +29,9 @@ from ._text_fallback import (
 )
 from .tool_bridge import ToolHandler
 
+if TYPE_CHECKING:
+    from mcp.types import CallToolResult
+
 _logger = logging.getLogger("nighthawk")
 
 
@@ -187,27 +190,51 @@ def tool_handler_result_to_low_level_mcp_content(
         return [mcp_types.TextContent(type="text", text=render_preview())]
 
 
+def tool_handler_result_to_low_level_mcp_result(
+    *,
+    tool_name: str,
+    tool_handler_result: ToolHandlerResult,
+    rendering_policy: ToolResultRenderingPolicy | None = None,
+) -> CallToolResult:
+    from mcp import types as mcp_types
+
+    content = tool_handler_result_to_low_level_mcp_content(
+        tool_name=tool_name, tool_handler_result=tool_handler_result, rendering_policy=rendering_policy
+    )
+    error = tool_handler_result["tool_outcome"]["error"] if tool_handler_result["kind"] == "tool_result" else None
+    return mcp_types.CallToolResult(
+        content=cast(list[mcp_types.ContentBlock], content),
+        is_error=tool_handler_result["kind"] != "tool_result" or error is not None,
+        structured_content={"error": dict(error)} if error is not None else None,
+    )
+
+
 def _tool_handler_result_to_claude_code_sdk_content(
     *,
     tool_name: str,
     tool_handler_result: ToolHandlerResult,
     rendering_policy: ToolResultRenderingPolicy | None = None,
 ) -> dict[str, object]:
-    content_block_list = tool_handler_result_to_low_level_mcp_content(
+    result = tool_handler_result_to_low_level_mcp_result(
         tool_name=tool_name,
         tool_handler_result=tool_handler_result,
         rendering_policy=rendering_policy,
     )
 
     dumped_content_block_list: list[dict[str, object]] = []
-    for content_block in content_block_list:
+    for content_block in result.content:
         model_dump = getattr(content_block, "model_dump", None)
         if callable(model_dump):
             dumped_content_block_list.append(cast(dict[str, object], model_dump(mode="json", by_alias=True, exclude_none=True)))
             continue
         raise TypeError(f"Unsupported MCP content block: {type(content_block).__name__}")
 
-    return {"content": dumped_content_block_list}
+    response: dict[str, object] = {"content": dumped_content_block_list}
+    if result.is_error:
+        response["isError"] = True
+    if result.structured_content is not None:
+        response["structuredContent"] = result.structured_content
+    return response
 
 
 async def _get_tool_handler_result(
@@ -252,14 +279,14 @@ async def call_tool_for_low_level_mcp_server(
     tool_handler: ToolHandler,
     parent_otel_context: OtelContext,
     rendering_policy: ToolResultRenderingPolicy | None = None,
-) -> list[object]:
+) -> CallToolResult:
     tool_handler_result = await _get_tool_handler_result(
         tool_name=tool_name,
         arguments=arguments,
         tool_handler=tool_handler,
         parent_otel_context=parent_otel_context,
     )
-    return tool_handler_result_to_low_level_mcp_content(
+    return tool_handler_result_to_low_level_mcp_result(
         tool_name=tool_name,
         tool_handler_result=tool_handler_result,
         rendering_policy=rendering_policy,