feat(settings)!: report update mode and pending restart

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+The next release changes analysis-setting output (#9885). `update_analysis_settings`, `inspect_analysis_settings`, and limit errors no longer include `rea_restart_required`, `restart_required`, `restartRequired`, or `effect`. Read `update_mode` (`runtime`, `restart`, or `parameter`) and `pending_restart`. `runtime` means the setter can change the active value. `restart` means this process keeps the value it started with. `parameter` means this call supplied the value, so `update_analysis_settings` cannot change it; artifact reader limits, web-network capture budgets, and an explicit `analysis_timeout_ms`, `max_heap_mb`, or `command_timeout_ms` use it. There is no compatibility alias. Release Please should copy this migration into that release's breaking-changes section.
+
 ## [6.8.0](https://github.com/morluto/rea/compare/rea-agents-6.7.0...rea-agents-6.8.0) (2026-10-25)
 
 ### Highlights

docs/design/limits-and-recovery.md

@@ -257,8 +257,8 @@ are runtime-wide, not scoped to a target or an individual connection.
 ### Failure and retry
 
 An ASAR admission error supplies `details.limit` with the exact setting,
-effective value, units, bounds, scope, application point, restart requirement
-and, when known, required bytes and value source. The agent can immediately call:
+effective value, units, bounds, scope, application point, `update_mode`,
+`pending_restart` and, when known, required bytes and value source. The agent can immediately call:
 
 ```json
 {
@@ -275,13 +275,27 @@ that argument; raising a runtime default cannot override it.
 
 The resource owner constructs `details.limit` from the registry plus the budget
 it actually enforced. Metadata includes `agent_editable: true`,
-`scope: "rea-runtime"`, and `rea_restart_required: false`. Optional
+`scope: "rea-runtime"`, `update_mode`, and `pending_restart`. `update_mode`
+is `runtime` when `update_analysis_settings` can change the active value,
+`restart` when this process keeps the value it started with, and `parameter`
+when this call supplied the value. An explicit `analysis_timeout_ms`,
+`max_heap_mb`, or `command_timeout_ms`, plus artifact reader limits and
+web-network capture budgets, use `parameter`. `pending_restart` is false when
+that reported value is the one this process is using. Optional
 `required_value`, `source`, and `parameter` fields are supplied only where known
 or applicable. Do not infer a source because a value happens to equal a default.
 Error copying, attribution, redaction, and delivery must preserve these facts.
 Human-readable remediation explains the same failure; clients should not need
 to parse that sentence to identify an editable setting.
 
+This output is breaking. Results and errors no longer carry the previous
+restart boolean or a single effect field, and there is no compatibility alias.
+Read `update_mode` to see whether the setter can change the active value, and
+`pending_restart` to see whether a configured value is waiting. A configuration
+error for a Windows ChangeTime setting carries those two fields on
+`details.settings`, not only in the constraint sentence. The removed field names
+are listed in the changelog.
+
 `scope` and `applies_at` describe a continuing caller, such as an MCP
 connection. A one-shot invocation, such as a CLI command, has released its
 provider session and exited its runtime before its caller reads the failure,
@@ -290,8 +304,10 @@ so its adapter projects with an explicit `"invocation"` caller lifetime.
 `scope: "rea-invocation"`, `applies_at: "next_invocation"` and the launch
 `environment` seed when one exists. `agent_editable: true` still holds, because
 the caller chooses that environment value or per-call `parameter` for the new
-invocation; `rea_restart_required: false` means no running REA process needs a
-restart. A producer keeps guidance that holds only while its caller retains the
+invocation; `update_mode: "runtime"` and `pending_restart: false` mean the
+reported value is active in this process. `update_mode: "restart"` means
+`update_analysis_settings` does not change it. `update_mode: "parameter"` means
+this call supplied the value. A producer keeps guidance that holds only while its caller retains the
 session, such as "the Ghidra session remains usable" or a same-session runtime
 update, in `continuingCallerGuidance`; the shared presentation adds it only for
 a continuing caller. The producer's own message and remediation must stay true
@@ -501,7 +517,10 @@ own `expanded_bytes` controls its independently enforced bundle expansion.
 
 Failures preserve `details.reader_limit` with the exact parameter, effective
 value, units, supported range, required value when known, next-call scope and
-`can_increase`. When `can_increase` is true, raise that field and retry the same
+`can_increase`. `update_mode` is `parameter`: the caller selects the value on
+the next call, and `update_analysis_settings` does not accept it.
+`pending_restart` is false. Web-network capture budgets use the same mode.
+When `can_increase` is true, raise that field and retry the same
 complete artifact. At the supported maximum, or when the required representation
 exceeds it, the failure is not retryable by increasing that budget; inspect the
 declared dimensions and input validity, or explicitly choose a suitable reader.