@dreb/coding-agent 2.40.2 → 2.42.0

package/docs/rpc.md

@@ -191,6 +191,9 @@ Response:
       {"provider": "anthropic", "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5", "reasoning": true, "thinkingLevel": "high"}
     ],
     "usingSubscription": false,
+    "tasks": [
+      {"id": "inspect", "title": "Inspect the implementation", "status": "in_progress"}
+    ],
     "thinkingLevel": "medium",
     "isStreaming": false,
     "isCompacting": false,
@@ -215,6 +218,25 @@ The `model` field is a full [Model](#model) object or `null`. `scopedModels` is
 
 `contextUsage` carries the same numbers the TUI footer shows, computed by the session itself — clients must render these rather than deriving their own estimate. `tokens` and `percent` are `null` when usage is unknown (right after compaction, before the next LLM response). The whole field is omitted when no model is set or the model has no context window.
 
+`tasks` is the current `RpcSessionState` task list. Every task has a stable `id`, `title`, and `pending`, `in_progress`, or `completed` status. It is replaced atomically by each [`tasks_update`](#event-types) event; clients restoring state after a hard refresh or recovery gap should use this snapshot rather than reconstructing tasks from a partial event history.
+
+#### get_dashboard_snapshot
+
+Capture the dashboard-visible parent-session state, full parent transcript, and background-agent registry at one RPC command boundary. This is for authoritative recovery, not ordinary incremental refreshes.
+
+```json
+{"id": "snapshot-7", "type": "get_dashboard_snapshot"}
+```
+
+The `RpcDashboardSnapshot` result is a `snapshotId`, a complete `RpcSessionState` (including `tasks`), `messages`, and `backgroundAgents`. The RPC child writes a `RpcDashboardSnapshotBarrierEvent` to stdout **immediately before** the matching response line:
+
+```json
+{"type":"dashboard_snapshot_barrier","snapshotId":"snapshot-7"}
+{"id":"snapshot-7","type":"response","command":"get_dashboard_snapshot","success":true,"data":{"snapshotId":"snapshot-7","state":{...},"messages":[...],"backgroundAgents":[...]}}
+```
+
+Stdout JSONL ordering is the contract: a relay records its current event-stream sequence when the marker arrives, before resolving the response, and pairs the snapshot only with that exact marker. The dashboard returns that captured sequence as `/api/resync.barrierSeq`; consumers discard queued events through it and replay only later events. The marker itself is not broadcast as another browser event, so one recovering client does not interrupt healthy clients. Do not infer ordering from request/response timing; see [dashboard recovery](dashboard.md#live-connection-and-recovery).
+
 #### get_resources
 
 Get loaded resource metadata for the current session. This returns paths/names/descriptions only — it does not include context file contents, prompt bodies, skill bodies, or system prompt text.
@@ -1219,16 +1241,17 @@ Note: with `summarize: true` the command is LLM-bound and can take a while. `Rpc
 
 ### Settings
 
-Persistent default settings, backed by the settings file (see [settings.md](settings.md)). These are distinct from live session state:
+Persistent settings, backed by the settings file (see [settings.md](settings.md)). They are normally distinct from live session state, with one security-policy exception:
 
-- **Persistent defaults** (`get_settings` / `set_settings`): the values stored in `settings.json` that seed fresh runtimes — default provider/model, default thinking level, queue modes, compaction/retry/image/context/skill/thinking-display/transport toggles, and per-agent model fallback lists. Writing them does **not** change the running session.
+- **Persistent defaults** (`get_settings` / `set_settings`): provider/model, thinking level, queue modes, compaction/retry/image/skill/thinking-display/transport toggles, and per-agent model fallback lists seed fresh runtimes. Writing these ordinary defaults does **not** change a running session.
+- **Global nested-context trust policy** (`autoLoadNestedContext`, `trustedContextFolders`, `effectiveTrustedContextRoots`, and the trust commands below): this is read from `~/.dreb/agent/settings.json` only, never project settings. Active main/subagent processes observe it for **future lazy nested/out-of-cwd loads**; it cannot remove content already injected into a conversation. It does not govern the separate initial upward context scan from the launch cwd.
 - **Runtime state** (`get_state` / `set_model` / `set_thinking_level` / `set_steering_mode` / `set_follow_up_mode` / `set_auto_compaction` / `set_auto_retry`): the state of the live session. Note that the runtime setters also persist their values as new defaults as a side effect.
 
-A dashboard settings tab typically reads both: `get_state` for what's active now, `get_settings` for what the next startup will use.
+A dashboard settings tab typically reads `get_state` for what is active now and `get_settings` for persistent defaults plus the current global context-trust policy.
 
 #### get_settings
 
-Get the persistent default settings (merged global + project view).
+Get persistent settings. Before replying, RPC flushes pending settings writes, reloads durable global and project settings, and then reads the merged view; reopening dashboard Settings therefore sees external file edits. A pending write failure, unreadable file, parse error, or reload failure returns an explicit RPC error rather than a stale snapshot. Ordinary fields are the merged global + project view; the nested-context trust fields are always global-only.
 
 ```json
 {"type": "get_settings"}
@@ -1251,7 +1274,9 @@ Response:
     "imageAutoResize": true,
     "blockImages": false,
     "enableSkillCommands": true,
-    "autoLoadNestedContext": true,
+    "autoLoadNestedContext": false,
+    "trustedContextFolders": ["/home/user/src/my-company"],
+    "effectiveTrustedContextRoots": ["/home/user/src/my-company"],
     "transport": "sse",
     "hideThinkingBlock": false,
     "agentModels": {
@@ -1263,6 +1288,8 @@ Response:
 
 `defaultProvider`, `defaultModel`, and `defaultThinkingLevel` are absent if never set. `agentModels` is the merged global + project view; project entries win per agent name.
 
+`trustedContextFolders` is the raw global configured list, including invalid legacy paths that are ignored fail-closed. `effectiveTrustedContextRoots` is the canonical, existing root set actually enforced after `~` expansion, native `realpath`, deduplication, and ancestor subsumption. `autoLoadNestedContext` defaults to `false`; when `true` it is global expert trust-all for every resolvable target, not a project override. Project `.dreb/settings.json` cannot affect any of these three fields.
+
 #### set_settings
 
 Update persistent default settings. Takes a partial payload — only the supplied keys change. The whole payload is validated before anything is applied: on any invalid field, nothing changes and the response is an explicit error. Writes target the global settings file (same scope as every runtime setter).
@@ -1271,6 +1298,14 @@ Update persistent default settings. Takes a partial payload — only the supplie
 {"type": "set_settings", "settings": {"defaultThinkingLevel": "low", "retryEnabled": false}}
 ```
 
+Replace the global trusted-root list atomically (paths must be existing directories and are persisted as canonical roots):
+
+```json
+{"type": "set_settings", "settings": {"trustedContextFolders": ["/home/user/src/my-company"]}}
+```
+
+Set `autoLoadNestedContext: true` only as an expert global trust-all choice: it permits lazy context from any resolvable directory, including untrusted prompt-injection content. `set_settings` writes this policy globally even when the RPC session has project settings; project `.dreb/settings.json` cannot add, override, or enable it. Active processes use the result for later lazy loads, not to retract prior injections. The separate initial upward scan from the launch cwd is unaffected.
+
 Setting the default model (both keys required together, validated against available models — the provider must have credentials configured, same rule as `set_model`):
 
 ```json
@@ -1311,7 +1346,9 @@ Response is the full settings snapshot after the write (same shape as `get_setti
     "imageAutoResize": true,
     "blockImages": false,
     "enableSkillCommands": true,
-    "autoLoadNestedContext": true,
+    "autoLoadNestedContext": false,
+    "trustedContextFolders": ["/home/user/src/my-company"],
+    "effectiveTrustedContextRoots": ["/home/user/src/my-company"],
     "transport": "sse",
     "hideThinkingBlock": false,
     "agentModels": {}
@@ -1334,7 +1371,9 @@ Project-shadow warning example (the global write still lands, but the returned m
     "imageAutoResize": true,
     "blockImages": false,
     "enableSkillCommands": true,
-    "autoLoadNestedContext": true,
+    "autoLoadNestedContext": false,
+    "trustedContextFolders": [],
+    "effectiveTrustedContextRoots": [],
     "transport": "sse",
     "hideThinkingBlock": false,
     "agentModels": {
@@ -1360,7 +1399,8 @@ Valid keys and values:
 | `imageAutoResize` | boolean |
 | `blockImages` | boolean |
 | `enableSkillCommands` | boolean |
-| `autoLoadNestedContext` | boolean |
+| `autoLoadNestedContext` | boolean; global-only expert trust-all for lazy nested/out-of-cwd loading; defaults to `false` |
+| `trustedContextFolders` | Replaces the global list atomically. Array of non-empty paths that expand to absolute, existing directories; each is canonicalized with native `realpath`, then deduplicated/subsumed. Relative, missing, non-directory, and broken-symlink entries are rejected. |
 | `transport` | `"sse"`, `"websocket"`, `"auto"` |
 | `hideThinkingBlock` | boolean |
 | `agentModels` | Plain object mapping agent names to arrays of non-empty model id strings; empty arrays remove the global entry for that agent |
@@ -1374,6 +1414,7 @@ Errors are explicit `success: false` responses (nothing is applied on any of the
 - Non-boolean toggle: `Invalid retryEnabled: "yes". Must be a boolean`
 - Invalid `agentModels` object: `Invalid agentModels: must be a plain object mapping agent names to model fallback arrays`
 - Invalid `agentModels` entry (the offending agent key is named): `Invalid agentModels["Explore"]: expected an array of non-empty strings`
+- Invalid trusted-root list: `trustedContextFolders must be an array of non-empty path strings` or `Invalid trustedContextFolders[0]: path must be absolute after ~ expansion` / `path must be an existing directory`
 - Provider without model (or vice versa): `defaultProvider and defaultModel must be set together`
 - Unavailable model: `Model not found: provider/model-id`
 - Corrupt settings file: `Cannot write settings: the global settings file failed to load (fix or remove the corrupt settings.json first)` — without this guard the write would silently no-op
@@ -1381,6 +1422,138 @@ Errors are explicit `success: false` responses (nothing is applied on any of the
 
 Unlike `set_thinking_level` (which silently clamps to the current model's capabilities), `set_settings` rejects invalid values loudly — a dashboard needs the error, not a silent correction.
 
+#### evaluate_context_trust
+
+Evaluate one directory against the current **global** lazy nested-context policy. This is useful for a Files view; it does not load context or change settings.
+
+```json
+{"type": "evaluate_context_trust", "path": "/home/user/src/my-company/package"}
+```
+
+Success response:
+
+```json
+{
+  "type": "response",
+  "command": "evaluate_context_trust",
+  "success": true,
+  "data": {
+    "canonicalTarget": "/home/user/src/my-company/package",
+    "state": "trusted-root",
+    "grantingRoot": "/home/user/src/my-company"
+  }
+}
+```
+
+`canonicalTarget` is the existing directory after strict native `realpath`. `state` is exactly one of:
+
+- `"untrusted"` — no global root covers the target.
+- `"trusted-root"` — a configured canonical root covers it; `grantingRoot` is present, including for inherited descendant access.
+- `"unrestricted"` — global `autoLoadNestedContext` is true; `grantingRoot` is omitted because folder roots are not the grant.
+
+Invalid paths return `success: false`: `path` must be a non-empty string, absolute after `~` expansion, and an existing directory. Error text is prefixed `Invalid context trust path: ` (for example, `Invalid context trust path: path must be an existing directory`). Symlinks are resolved before evaluation, so a lexical descendant that resolves outside a trusted root evaluates as untrusted.
+
+#### trust_context_folder
+
+Add a directory as a global trusted root, then durably flush the settings write. The request path has the same strict validation and canonicalization as `evaluate_context_trust`.
+
+```json
+{"type": "trust_context_folder", "path": "/home/user/src/my-company"}
+```
+
+Success response (the nested `settings` object is abbreviated here to its trust fields):
+
+```json
+{
+  "type": "response",
+  "command": "trust_context_folder",
+  "success": true,
+  "data": {
+    "evaluation": {
+      "canonicalTarget": "/home/user/src/my-company",
+      "state": "trusted-root",
+      "grantingRoot": "/home/user/src/my-company"
+    },
+    "addedRoot": "/home/user/src/my-company",
+    "settings": {
+      "autoLoadNestedContext": false,
+      "trustedContextFolders": ["/home/user/src/my-company"],
+      "effectiveTrustedContextRoots": ["/home/user/src/my-company"]
+    }
+  }
+}
+```
+
+`settings` is the complete `get_settings` snapshot after the durable global write. `addedRoot` is the canonical target when it is retained as a root; it is omitted when an existing ancestor already covers that target. Existing malformed legacy roots are discarded by this mutation; the resulting root list is canonical, deduplicated, and ancestor-subsumed. Invalid paths use the same `Invalid context trust path: ...` errors. A corrupt global settings file or failed durable write returns `success: false` with `Cannot write settings: ...` or `Failed to persist settings: ...`; no merely in-memory trust is reported as success.
+
+#### untrust_context_folder
+
+Remove the actual canonical root granting trust to a target, rather than only removing a selected descendant. This is the companion for an inherited Files-view trust badge.
+
+```json
+{"type": "untrust_context_folder", "path": "/home/user/src/my-company/package"}
+```
+
+If `/home/user/src/my-company` grants this descendant's access, a successful response is (with `settings` abbreviated to its trust fields):
+
+```json
+{
+  "type": "response",
+  "command": "untrust_context_folder",
+  "success": true,
+  "data": {
+    "evaluation": {
+      "canonicalTarget": "/home/user/src/my-company/package",
+      "state": "untrusted"
+    },
+    "removedRoot": "/home/user/src/my-company",
+    "settings": {
+      "autoLoadNestedContext": false,
+      "trustedContextFolders": [],
+      "effectiveTrustedContextRoots": []
+    }
+  }
+}
+```
+
+`removedRoot` is the canonical root removed for the target and therefore revokes its descendants too. If the target was already `untrusted`, this is a successful no-op: `settings` and an `untrusted` evaluation are returned without `removedRoot`. If global expert trust-all is enabled, it fails rather than pretending a folder change can narrow it:
+
+```json
+{"type":"response","command":"untrust_context_folder","success":false,"error":"Cannot untrust a context folder while unrestricted nested context loading is enabled; disable autoLoadNestedContext first"}
+```
+
+Invalid paths and write failures have the same semantics as `trust_context_folder`.
+
+#### remove_trusted_context_folder
+
+Remove a configured global trusted-folder string by **exact** match, then durably flush the settings write. This is intentionally different from `untrust_context_folder`: the request path is treated as the configured string to delete and performs no directory/path resolution — no `~` expansion, absolute-path requirement, directory existence check, symlink resolution, canonicalization, or granting-root lookup.
+
+```json
+{"type": "remove_trusted_context_folder", "path": "/legacy/or/moved/path"}
+```
+
+Success response (the nested `settings` object is abbreviated here to its trust fields):
+
+```json
+{
+  "type": "response",
+  "command": "remove_trusted_context_folder",
+  "success": true,
+  "data": {
+    "settings": {
+      "autoLoadNestedContext": false,
+      "trustedContextFolders": [],
+      "effectiveTrustedContextRoots": []
+    },
+    "removedFolder": "/legacy/or/moved/path"
+  }
+}
+```
+
+`settings` is the complete `get_settings` snapshot after the durable global write. `removedFolder` is the configured folder string requested for exact removal; the command is a successful no-op if the exact string was not present. Only a non-empty string `path` is required, so this command can revoke invalid, legacy, or stale configured entries that `untrust_context_folder` cannot validate or resolve. It is not gated by global expert trust-all (`autoLoadNestedContext: true`), because it edits the configured list directly rather than pretending to narrow unrestricted loading. A corrupt global settings file or failed durable write returns `success: false` with `Cannot write settings: ...` or `Failed to persist settings: ...`; no merely in-memory trust removal is reported as success.
+
+All four context-trust commands concern only future lazy nested/out-of-cwd loads in active main/subagent processes; they never alter the separate initial upward scan or retract context already injected into a conversation.
+
 ### Version
 
 #### get_version
@@ -1403,7 +1576,7 @@ Response:
 
 ## Events
 
-Events are streamed to stdout as JSON lines during agent operation. Events do NOT include an `id` field (only responses do).
+`RpcEvent` messages are streamed to stdout as JSON lines during agent operation. Agent/session events and `dashboard_snapshot_barrier` do not include an `id` field; extension UI requests include an `id` so clients can respond.
 
 ### Event Types
 
@@ -1430,7 +1603,8 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `background_agent_event` | Relayed event from a background subagent's own stream |
 | `parent_paused_for_background_agents` | Parent paused waiting on background agents |
 | `session_name_changed` | Session display name changed (manual rename, extension rename, or auto-title) |
-| `tasks_update` | Session task list replaced (see the `tasks_update` tool) |
+| `tasks_update` | Session task list atomically replaced (each task has `id`, `title`, and status) |
+| `dashboard_snapshot_barrier` | Ordering marker emitted immediately before a successful `get_dashboard_snapshot` response; pair only the matching `snapshotId` (see [Dashboard snapshots](#get_dashboard_snapshot)) |
 | `suggest_next` | Agent suggested a next command |
 | `extension_error` | Extension threw an error |
 

package/docs/settings.md

@@ -1,6 +1,6 @@
 # Settings
 
-dreb uses JSON settings files with project settings overriding global settings.
+dreb uses JSON settings files with project settings overriding global settings, except where a setting is explicitly global-only (notably nested-context trust).
 
 | Location | Scope |
 |----------|-------|
@@ -113,13 +113,36 @@ After the configured number of tool calls, dreb fires a single background LLM ca
 
 ### Context
 
+At startup, dreb always performs an **initial upward scan** from the launch cwd for `AGENTS.md`/`CLAUDE.md`. This is separate from lazy nested/out-of-cwd loading and is not enabled, disabled, or scoped by either context setting below. It is not a claim that the initial scan has a fixed boundary: it follows the startup upward-walk behavior for that cwd.
+
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `context.autoLoadNested` | boolean | `true` | Auto-load a directory's `AGENTS.md`/`CLAUDE.md` the first time a tool operates there |
+| `context.trustedFolders` | string[] | `[]` | **Global-only.** Explicit existing directory roots whose canonical descendants may lazy-load context |
+| `context.autoLoadNested` | boolean | `false` | **Global-only expert trust-all.** Allow lazy loading from every resolvable directory |
+
+Both settings belong only in `~/.dreb/agent/settings.json`. Project `.dreb/settings.json` cannot enable, disable, or extend nested-context trust: it cannot enable unrestricted loading, add trusted roots, override global roots, or otherwise widen this trust boundary. A cloned repository therefore cannot grant itself trust.
+
+#### `context.trustedFolders`
+
+Use explicit roots for directories whose instructions you control:
+
+```json
+{
+  "context": {
+    "trustedFolders": ["~/src/my-company", "/srv/controlled-repos"]
+  }
+}
+```
+
+Each root authorizes itself and its descendants for lazy loading. Paths are expanded (`~` is supported) and canonically resolved with native `realpath`; the target is independently canonicalized for every decision. Roots must be absolute after expansion, existing directories, and must not be broken symlinks. Invalid/missing legacy entries are ignored fail-closed; RPC/settings updates reject invalid entries atomically. Canonical duplicates are deduplicated, and a descendant root is subsumed by its trusted ancestor. This realpath matching prevents symlink escape: a path that is lexically below a trusted folder but resolves outside it is not trusted.
 
-When enabled, dreb loads nested context files that the startup upward-walk misses (e.g. a `CLAUDE.md` in a monorepo subpackage, or context in a different repo a subagent visits). The first tool to touch a directory triggers a walk up to a sensible ceiling — the session cwd for in-tree targets, otherwise the outermost git repo root, otherwise the outermost directory containing a context file — and the collected files are appended to that tool's result. Each file loads at most once per session. See [Context Files](../README.md#context-files).
+For a trusted target, the first matching path-bearing tool (`read`, `edit`, `write`, `grep`, `find`, `ls`) — or `bash` beginning with `cd <dir>` — can append its context to the tool result. The walk is bounded by the trusted root (or the normal cwd/repository/context-file ceiling when expert trust-all is in effect). Main agents and subagents read the same global policy. Active processes re-read it for later lazy-load decisions, so a trust/untrust change affects **future** loads without a restart; text already injected into a conversation cannot be retracted.
 
-**Security caution:** when working across untrusted or third-party repositories, their `AGENTS.md`/`CLAUDE.md` files may be auto-injected into the agent's context, which is a prompt-injection consideration. Set `context.autoLoadNested` to `false` to disable this behavior. Auto-loaded content is secret-scrubbed before injection, but extension `tool_result` transforms do not see it because nested context is injected after those transforms for cache safety.
+In the dashboard, the Files view is the primary grant flow: trust the displayed folder and descendants, or untrust the actual granting root. The Settings screen lists every configured trusted root for audit and revoke, and offers a simple add-by-path control. These controls change only lazy nested/out-of-cwd loading; they do not alter the separate initial upward scan described above.
+
+#### `context.autoLoadNested`
+
+**Expert setting — prompt-injection warning.** Set this to `true` only in global settings to allow lazy loading from **any** resolvable target directory:
 
 ```json
 {
@@ -129,6 +152,10 @@ When enabled, dreb loads nested context files that the startup upward-walk misse
 }
 ```
 
+This includes untrusted or third-party repositories and can inject prompt-injection content. Prefer `trustedFolders`; leave this setting `false` unless you intentionally trust all such targets. A project settings file cannot enable it.
+
+For either permitted lazy-load path, each context file is realpath-deduplicated and injected at most once per session; files already obtained during the initial upward scan are not repeated. If the triggering tool already returns a context file in full, it is marked loaded without a duplicate injection. Auto-loaded content is secret-scrubbed before injection and is appended after extension `tool_result` transforms, so those transforms intentionally do not see it. See [Context Files](../README.md#context-files).
+
 ### Compaction
 
 | Setting | Type | Default | Description |
@@ -357,7 +384,7 @@ See [packages.md](packages.md) for package management details.
 
 ## Project Overrides
 
-Project settings (`.dreb/settings.json`) override global settings. Nested objects are merged:
+Project settings (`.dreb/settings.json`) override global settings. Nested objects are merged. **Exception:** `context.trustedFolders` and `context.autoLoadNested` are global-only security policy: project settings cannot add, replace, override, or enable either one. Nested context from the initial startup upward scan remains separate from this lazy-load policy.
 
 ```json
 // ~/.dreb/agent/settings.json (global)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.40.2",
+	"version": "2.42.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {