From 47bf91693b1bfff5c7ab8782d40c43cbe2932772 Mon Sep 17 00:00:00 2001
From: ymote <151983+ymote@users.noreply.github.com>
Date: Mon, 28 Sep 2026 23:19:22 -0700
Subject: [PATCH] =?UTF-8?q?toolbox-peers:=20offer=20the=20system=20toolbox?=
 =?UTF-8?q?=20to=20app=20agents=20(ADR=200002=20=C2=A76,=20ADR=200004=20?=
 =?UTF-8?q?=C2=A712)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-port of #108 onto main's octos#2567 shell side (#145), behind the
`toolbox-peers` feature (off by default):

- the toolbox is one more owning app (`toolbox`) in the shell's host-tool
  relay: its tools are declared once in the catalog (`app: "toolbox"`,
  shareable), each app is granted exactly what it declares AND the person
  granted, and `ToolboxExecutor` (crates/ai-host) runs the calls the relay
  routes to it; main's broker registers them after every prepare and
  reconnect. #108's own registration and routing are not ported;
- no hard-coded exclusions: #108's "never offer octos deep_research"
  (its empty generic_tools) is gone;
- the #120 first-use consent gates the toolbox: nothing offered
  (Catalog::offered) and nothing run (the relay's consent_pending) before
  the person allowed the app's agent;
- ported from #108: crates/toolbox `peer` (plus a shared `catalog`),
  read_links/narrow_crawl, ModelHostClient, toolbox_folder, the 256 KiB host
  model input, the mock model's CALL_TOOL rule; tests against a scripted
  kernel through main's broker, the relay, and a real octos kernel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/apps.yml                    |   6 +
 .github/workflows/phone.yml                   |   1 +
 Cargo.lock                                    |   2 +
 .../host-service/src/complete/mod.rs          |  13 +-
 .../host-service/tests/complete.rs            |  22 +
 crates/ai-host/Cargo.toml                     |  16 +
 crates/ai-host/README.md                      |  58 +-
 crates/ai-host/src/lib.rs                     |  33 +
 crates/ai-host/src/toolbox_peers.rs           | 455 +++++++++++
 crates/ai-host/tests/toolbox_peers.rs         | 540 +++++++++++++
 crates/ai-host/tests/toolbox_real_kernel.rs   | 207 +++++
 .../tests/fixtures/mock_agent_llm.py          |  15 +-
 crates/shell/Cargo.toml                       |   4 +
 crates/shell/src/host_tools/mod.rs            |  12 +-
 crates/shell/src/host_tools/relay.rs          |  27 +-
 crates/shell/src/host_tools/tests.rs          |  83 ++
 crates/shell/src/host_tools/toolbox.rs        |  70 ++
 crates/shell/src/module_host.rs               |   4 +
 crates/toolbox/README.md                      |   4 +-
 crates/toolbox/src/lib.rs                     |   1 +
 crates/toolbox/src/peer.rs                    | 722 ++++++++++++++++++
 crates/toolbox/src/research/mod.rs            |  26 +
 crates/toolbox/src/research/octos.rs          |  99 ++-
 crates/toolbox/src/scope.rs                   |  71 ++
 crates/toolbox/src/scope/compat.rs            |  29 +-
 crates/toolbox/tests/peer.rs                  | 168 ++++
 desktop/Cargo.toml                            |   2 +
 phone/Cargo.toml                              |   2 +
 28 files changed, 2678 insertions(+), 14 deletions(-)
 create mode 100644 crates/ai-host/src/toolbox_peers.rs
 create mode 100644 crates/ai-host/tests/toolbox_peers.rs
 create mode 100644 crates/ai-host/tests/toolbox_real_kernel.rs
 create mode 100644 crates/shell/src/host_tools/toolbox.rs
 create mode 100644 crates/toolbox/src/peer.rs
 create mode 100644 crates/toolbox/tests/peer.rs

diff --git a/.github/workflows/apps.yml b/.github/workflows/apps.yml
index 55f49f0e..27bdf62c 100644
--- a/.github/workflows/apps.yml
+++ b/.github/workflows/apps.yml
@@ -144,6 +144,12 @@ jobs:
           cargo test --locked -p octosense-ai-host
           cargo test --locked -p octosense-ai-host --features octos-core,llm
           cargo clippy --locked -p octosense-ai-host --all-targets --features octos-core,llm --no-deps -- -D warnings
+          # The system toolbox for app agents (off by default): its grants and
+          # executor through main's broker, against the scripted kernel. The
+          # real-kernel test (tests/toolbox_real_kernel.rs) needs an octos
+          # binary and passes without.
+          cargo test --locked -p octosense-ai-host --features toolbox-peers
+          cargo clippy --locked -p octosense-ai-host --all-targets --features toolbox-peers --no-deps -- -D warnings
       - name: AppCard runtime setup safeguards
         working-directory: apps/appcard
         run: PYTHONPATH=tools python3 -m unittest core.test_native_runtime
diff --git a/.github/workflows/phone.yml b/.github/workflows/phone.yml
index 6364070f..0b67b3c2 100644
--- a/.github/workflows/phone.yml
+++ b/.github/workflows/phone.yml
@@ -88,5 +88,6 @@ jobs:
           cargo test --locked --features mobile-apps -p octosense-shell -p octosense-home -p octosense-app-policy -p octosense-app-hub -p octosense-appcard -p octosense-ai-host
           # The opt-in AppCard build: its module registers into the shell.
           cargo test --locked --features mobile-apps,app-appcard -p octosense-shell appcard
+          cargo test --locked --features mobile-apps,toolbox-peers -p octosense-shell host_tools
           cargo test --locked -p makepad-widgets splash_policy
           cargo test --locked -p makepad-script-std gate::tests
diff --git a/Cargo.lock b/Cargo.lock
index 4e2b4edc..f119a8d4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7284,7 +7284,9 @@ dependencies = [
  "octosense-kernel",
  "octosense-llm-config",
  "octosense-llm-service",
+ "octosense-toolbox",
  "serde_json",
+ "tokio",
 ]
 
 [[package]]
diff --git a/apps/ai-providers/host-service/src/complete/mod.rs b/apps/ai-providers/host-service/src/complete/mod.rs
index b96449f7..8d0fe695 100644
--- a/apps/ai-providers/host-service/src/complete/mod.rs
+++ b/apps/ai-providers/host-service/src/complete/mod.rs
@@ -53,7 +53,9 @@
 //! to call it too, so direct calls and template calls share one budget per
 //! app: its `ModelRequest {system, user, output_schema}` maps onto a
 //! [`Request`] with `system` set and `input` the user document ([`host`]
-//! hands out the registered host).
+//! hands out the registered host). A host caller's input may be up to
+//! [`HOST_INPUT_MAX`] (a digest carries its articles' evidence); an app's
+//! stays at [`INPUT_MAX`].
 use crate::model::{effective_model, ProfileStore};
 use crate::probe;
 use crate::vault::Vault;
@@ -77,6 +79,10 @@ pub const FAMILY: &str = "model";
 pub const TASK_MAX: usize = 4 * 1024;
 /// The input, as compact JSON, in bytes.
 pub const INPUT_MAX: usize = 32 * 1024;
+/// The input of a host caller's call (`system` set: the toolbox's digests,
+/// whose user document carries the articles' evidence), which
+/// `host.request` can never make.
+pub const HOST_INPUT_MAX: usize = 256 * 1024;
 /// The model's reply text (after a code fence is removed), in bytes: the
 /// host's hard cap on what an app gets back.
 pub const OUTPUT_MAX: usize = 16 * 1024;
@@ -219,8 +225,9 @@ impl Request {
             return Err(bad(format!("task is over {TASK_MAX} bytes")));
         }
         let input = self.input.to_string().len();
-        if input > INPUT_MAX {
-            return Err(bad(format!("input is {input} bytes; the most is {INPUT_MAX}")));
+        let max = if self.system.is_some() { HOST_INPUT_MAX } else { INPUT_MAX };
+        if input > max {
+            return Err(bad(format!("input is {input} bytes; the most is {max}")));
         }
         if self.schema.is_null() {
             return Err(bad("schema is required".into()));
diff --git a/apps/ai-providers/host-service/tests/complete.rs b/apps/ai-providers/host-service/tests/complete.rs
index 975af1d3..779ff5bd 100644
--- a/apps/ai-providers/host-service/tests/complete.rs
+++ b/apps/ai-providers/host-service/tests/complete.rs
@@ -466,3 +466,25 @@ fn a_host_caller_shares_the_same_ledger() {
     assert_eq!(body["messages"][1]["content"], "{\"query\":\"x\"}");
     assert_eq!(Code::Budget.as_str(), "budget");
 }
+
+#[test]
+fn a_host_caller_may_send_a_larger_input_than_an_app() {
+    // A toolbox digest carries the articles' evidence (up to 6 KB each):
+    // over an app's 32 KiB, within the host's 256 KiB.
+    let rig = Rig::new("host-input", vec![deepseek("deepseek-v4-flash")]);
+    rig.fake.says(GOOD);
+    let big = "x".repeat(complete::INPUT_MAX + 1024);
+    let request = |system: Option<&str>| Request {
+        class: complete::Class::Fast,
+        task: if system.is_some() { String::new() } else { "t".into() },
+        input: json!(big),
+        schema: args()["schema"].clone(),
+        allow_urls: true,
+        system: system.map(str::to_owned),
+    };
+    let refused = rig.host.complete(APP, request(None)).unwrap_err();
+    assert_eq!(refused.code, Code::BadRequest);
+    rig.host.complete(APP, request(Some("You write a digest."))).unwrap();
+    let huge = Request { input: json!("x".repeat(complete::HOST_INPUT_MAX + 1)), ..request(Some("s")) };
+    assert_eq!(rig.host.complete(APP, huge).unwrap_err().code, Code::BadRequest);
+}
diff --git a/crates/ai-host/Cargo.toml b/crates/ai-host/Cargo.toml
index ac0f73e0..77f6f5ab 100644
--- a/crates/ai-host/Cargo.toml
+++ b/crates/ai-host/Cargo.toml
@@ -21,6 +21,10 @@
 #   dependencies below): `cfg(kernel)` in the source, set by build.rs.
 # - `llm`: register the `llm` host service (a shell's `app-hub` feature turns
 #   it on; phones always).
+# - `toolbox-peers`: the system toolbox offered to app agents as host-routed
+#   tools (octos#2567): the grants, and the executor the shell's host-tool
+#   relay routes the `toolbox` owner's calls to. Off by default; the shell's
+#   feature of the same name turns it on.
 #
 # The kernel is crates/kernel, the app-peers contract and broker
 # crates/app-peers, the `llm` service and its config apps/ai-providers/*;
@@ -38,6 +42,16 @@ license.workspace = true
 default = []
 octos-core = ["dep:octosense-kernel", "octosense-app-peers/octos-core", "octosense-llm-service?/octos-core"]
 llm = ["dep:octosense-llm-service"]
+# The system toolbox for app agents (ADR 0002 section 6, ADR 0004 section
+# 12): `toolbox_peers`, over the octos research engine and the `model`
+# service's host.
+toolbox-peers = [
+    "octos-core",
+    "llm",
+    "dep:octosense-toolbox",
+    "octosense-toolbox/octos-engine",
+    "dep:tokio",
+]
 
 [dependencies]
 makepad-widgets = { workspace = true }
@@ -51,6 +65,8 @@ octosense-appstore = { workspace = true }
 serde_json = { workspace = true }
 octosense-kernel = { workspace = true, optional = true }
 octosense-llm-service = { workspace = true, optional = true }
+octosense-toolbox = { workspace = true, optional = true }
+tokio = { workspace = true, optional = true, features = ["rt", "sync", "macros"] }
 
 # Native mobile builds always carry the kernel (Android bundles liboctos.so,
 # OpenHarmony links the core in-process, iOS runs none) and, when the `llm`
diff --git a/crates/ai-host/README.md b/crates/ai-host/README.md
index fc24b87a..b566d7a6 100644
--- a/crates/ai-host/README.md
+++ b/crates/ai-host/README.md
@@ -38,11 +38,63 @@ QrImport` (`platform()` or `paste_only()`); `policy: Policy`
 (`Policy::shipped()` grants Rinx the `octos.*` services).
 
 Features: `octos-core` (the kernel, app-peers broker, llm restart; native
-mobile targets always have it — `cfg(kernel)`, set by build.rs) and `llm`
-(register the `llm` service; a shell's `app-hub` turns it on).
+mobile targets always have it — `cfg(kernel)`, set by build.rs), `llm`
+(register the `llm` service; a shell's `app-hub` turns it on) and
+`toolbox-peers` (below; off by default, turned on by the shell's feature of
+the same name).
+
+## The system toolbox for app agents (`toolbox-peers`)
+
+ADR 0002 section 6 and ADR 0004 section 12. The toolbox is one more owner of
+host-routed tools in the shell's host-tool relay (octos#2567's shell side,
+`crates/shell/src/host_tools/`): main's broker registers them after every
+`peer/prepare` and reconnect (`generic_tools` omitted), and the relay
+authorizes each call and routes it to the toolbox's executor. This crate adds
+only the toolbox's part (`src/toolbox_peers.rs`, over `crates/toolbox`'s
+`peer` module):
+
+| Declared and granted | Offered (risk), each `app: "toolbox"` |
+| --- | --- |
+| neither | nothing |
+| `research` | `workflow.run` (read), `workflow.fork` (act), `toolbox.search` (read), `toolbox.web_read` (read) |
+| `crawl`, with `max_depth` and `max_pages` above 0 in the scope | `toolbox.deep_crawl` (read) |
+
+- `catalog()`: every toolbox tool, `shareable`, owned by `toolbox`; the relay
+  declares it once and grants each app its `ToolboxGrant::tools()`.
+- `ToolboxGrant`: what the app declares AND the person granted
+  (`ToolboxGrant::new(app, declared, granted, scope)`). A native module's
+  declared capabilities are reviewed with the shell (`for_module`). A script
+  app's manifest (`for_manifest`: `research`/`crawl` in `capabilities`, the
+  scope in octos's `Scope` shape under the top-level `research` object, App
+  Hub #26's shape) is, **temporarily**, granted only to system apps (`os.*`)
+  until the shells' App Hub pin includes #26 and the host reads its verified
+  grant.
+- `ToolboxExecutor`: the relay's executor for the `toolbox` owner. It checks
+  the calling app's grant again (a forged `toolbox.deep_crawl` is
+  `not_granted`), runs the call with the app's `AppContext` (id, grants,
+  octos `Scope`) on a worker thread per app, answers once, and never answers
+  a cancelled call. Template model calls go through the `model` service's
+  `ModelHost::complete`: the person's providers and the app's daily budget,
+  in the same ledger as `model.complete`.
+- Consent (the #120 first-use sheet) is the relay's: no toolbox tool is
+  offered to an app, or run for it, before the person allowed its agent.
+
+Nothing else is held back: octos's own generic tools (`deep_research` among
+them) are the kernel's, and which of them a peer gets is its `generic_tools`
+list, which the broker does not set.
+
+Results are written to the host-owned `<apps root>/.host/toolbox/<app id>`
+(`toolbox_folder`, always compiled; run results under
+`toolbox/runs/<template>/<run>.json`, research items under `research/`),
+outside the app's jail, where the glance screen's `sys.digest` (OctoSense
+#87) reads them.
 
 Tests: `cargo test -p octosense-ai-host --features octos-core,llm` (and
-without features for a kernel-less desktop). The module-host tests that
+without features for a kernel-less desktop); `--features toolbox-peers` adds
+the toolbox's grants and executor through the broker against a scripted
+kernel with the toolbox's fixture backends, and, when
+`OCTOS_APP_PEERS_TEST_KERNEL` names an `octos` binary at the pinned revision,
+`tests/toolbox_real_kernel.rs` against the real kernel. The module-host tests that
 create real instances (Rinx included) live with each shell's
 `module_host.rs`.
 
diff --git a/crates/ai-host/src/lib.rs b/crates/ai-host/src/lib.rs
index 8449a754..a14b0f7f 100644
--- a/crates/ai-host/src/lib.rs
+++ b/crates/ai-host/src/lib.rs
@@ -45,10 +45,17 @@
 //!   runner hosts that declare `octos.*` get their own peer (`card.<app id>`)
 //!   under the same contract, while [`Policy::contained_apps`] is on. Tool
 //!   approvals are declined until the Card runner has an approval sheet.
+//! - **The system toolbox for app agents** (feature `toolbox-peers`, off by
+//!   default): the toolbox's grants and the executor the shell's host-tool
+//!   relay runs its calls on ([`toolbox_peers`]). Its results live in each
+//!   app's host-owned toolbox folder ([`toolbox_folder`]), which exists with
+//!   or without the feature.
 
 mod bridge;
 pub mod contained;
 mod qr;
+#[cfg(feature = "toolbox-peers")]
+pub mod toolbox_peers;
 
 pub use bridge::{Bridge, Done};
 pub use qr::{ImageSource, PickError, QrImport, DROP_APP};
@@ -394,6 +401,32 @@ pub fn kernel_running() -> bool {
     false
 }
 
+// ---- the system toolbox's folders ------------------------------------------
+
+/// The host's folder for every app's toolbox, under the apps root:
+/// `<apps root>/.host/toolbox`. Outside every app's jail
+/// (`<apps root>/<app id>`), so an app cannot write a digest the glance
+/// screen would show as the host's.
+pub const TOOLBOX_HOST_DIR: [&str; 2] = [".host", "toolbox"];
+
+/// `<apps root>/.host/toolbox` ([`TOOLBOX_HOST_DIR`]). The glance screen's
+/// `sys.digest` resolver (OctoSense #87) reads run results under it.
+pub fn toolbox_root(apps_root: &std::path::Path) -> PathBuf {
+    TOOLBOX_HOST_DIR.iter().fold(apps_root.to_path_buf(), |dir, part| dir.join(part))
+}
+
+/// One app's toolbox folder, `<apps root>/.host/toolbox/<app id>`: run
+/// results in `toolbox/runs/<template>/<run>.json`, forks in
+/// `toolbox/templates/`, research items in `research/`. `None` for an id
+/// that is not one safe path segment.
+pub fn toolbox_folder(apps_root: &std::path::Path, app_id: &str) -> Option<PathBuf> {
+    let valid = !app_id.is_empty()
+        && app_id.len() <= 64
+        && !app_id.starts_with('.')
+        && app_id.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'));
+    valid.then(|| toolbox_root(apps_root).join(app_id))
+}
+
 // ---- apps' assistant access -------------------------------------------------
 
 /// The host policy in force: [`Policy::shipped`] until [`start`] installs
diff --git a/crates/ai-host/src/toolbox_peers.rs b/crates/ai-host/src/toolbox_peers.rs
new file mode 100644
index 00000000..55859c75
--- /dev/null
+++ b/crates/ai-host/src/toolbox_peers.rs
@@ -0,0 +1,455 @@
+//! The system toolbox for app agents (ADR 0002 section 6, ADR 0004 section
+//! 12; octos UPCR-2026-035 / octos#2567). Feature `toolbox-peers`.
+//!
+//! The toolbox is one more owner of host-routed tools in the shell's
+//! host-tool relay (`crates/shell/src/host_tools`, octos#2567's shell side).
+//! The broker registers and the relay routes; this module adds only what is
+//! the toolbox's:
+//!
+//! - **What an app is offered** ([`ToolboxGrant`]): exactly what it declares
+//!   AND the person granted. `research` gives `workflow.run` (read),
+//!   `workflow.fork` (act), `toolbox.search` (read) and `toolbox.web_read`
+//!   (read); `crawl`, with `max_depth`/`max_pages` above 0 in its scope,
+//!   gives `toolbox.deep_crawl` (read). Each is marked with its owning app,
+//!   `toolbox` ([`octosense_toolbox::peer::OWNER`]); the relay declares the
+//!   toolbox's [`catalog`] once and grants each app its [`ToolboxGrant::tools`].
+//!   Nothing is excluded beyond that: octos's generic tools (its
+//!   `deep_research` among them) stay the kernel's, and the broker registers
+//!   with `generic_tools` omitted.
+//! - **How a call runs** ([`ToolboxExecutor`], the relay's executor for the
+//!   `toolbox` owner): the toolbox with the calling app's [`AppContext`] (id,
+//!   grants, octos `Scope`, and its host-owned folder), over the octos
+//!   research engine (`OctosResearch`), with the templates' model calls going
+//!   through the `model` service's host ([`ModelHostClient`] over
+//!   `ModelHost::complete`), so they use the person's providers and count
+//!   against the app's daily budget in the same ledger as `model.complete`.
+//!   The executor checks the grant again: a call the app was not granted is
+//!   `not_granted`, whatever reached it.
+//!
+//! Consent (the #120 first-use sheet) is the relay's: it offers no toolbox
+//! tool to an app, and runs none for it, before the person allowed that
+//! app's agent.
+//!
+//! **Results** are written under [`crate::toolbox_folder`]
+//! (`<apps root>/.host/toolbox/<app>`), outside the app's jail
+//! (`<apps root>/<app>`), where the glance screen's `sys.digest` reads them
+//! (OctoSense #87): an app cannot forge a digest.
+//!
+//! **Where grants come from.** A native module declares `research`/`crawl`
+//! among its capabilities, compiled in and reviewed with the shell
+//! ([`ToolboxGrant::for_module`]; no manifest scope, so octos's defaults and
+//! no crawl limits). A script app declares them in its manifest's
+//! `capabilities`, with its scope in the manifest's top-level [`SCOPE_KEY`]
+//! object, App Hub #26's shape ([`ToolboxGrant::for_manifest`]).
+//! **TEMPORARY, until the shells' App Hub pin includes App Hub #26 (which
+//! checks and pins those capabilities and lets the person grant them) and
+//! the host reads its verified `AppPolicy::research`:** a script app's
+//! declaration is granted only to system apps (`os.*`, shipped inside the
+//! shell and reviewed with it), so a store app cannot grant itself research
+//! by writing it into its manifest ([`system_app_only`]).
+
+use octosense_app_peers::host_tools::{HostToolCall, ToolExecutor, ToolOutcome, ToolReply};
+use octosense_llm_service::complete::{self, Class, Code, ModelHost};
+use octosense_toolbox::host::{CallContext, HostError, HostFuture};
+use octosense_toolbox::peer::{self, PeerToolbox, CRAWL, RESEARCH};
+use octosense_toolbox::research::octos::{OctosConfig, OctosResearch};
+use octosense_toolbox::research::{ModelClient, ModelRequest};
+use octosense_toolbox::{scope, AppContext, Library, Scope};
+use serde_json::{json, Value};
+use std::collections::{BTreeSet, HashMap};
+use std::path::{Path, PathBuf};
+use std::rc::Rc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use tokio::sync::{mpsc, Notify};
+
+pub use octosense_toolbox::peer::OWNER;
+
+/// The manifest object that holds the `research`/`crawl` scope (octos's
+/// `Scope` fields): App Hub #26's shape (`capabilities: ["research",
+/// "crawl"]` plus one top-level `research` object).
+pub const SCOPE_KEY: &str = "research";
+
+/// Every toolbox tool, as the relay's catalog declares it (owned by
+/// [`OWNER`], `shareable`). Empty when the template library cannot load.
+pub fn catalog() -> Vec<Value> {
+    Library::builtin().map(|l| peer::catalog(&l)).unwrap_or_default()
+}
+
+/// An app's toolbox grant: what it declares AND the person granted.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ToolboxGrant {
+    /// `research` and/or `crawl`.
+    pub grants: BTreeSet<String>,
+    pub scope: Scope,
+    /// Why a declaration was not granted, for the log.
+    pub notes: Vec<String>,
+}
+
+impl ToolboxGrant {
+    /// Nothing granted.
+    pub fn none(note: Option<String>) -> Self {
+        Self { grants: BTreeSet::new(), scope: scope::unrestricted(), notes: note.into_iter().collect() }
+    }
+
+    /// The toolbox capabilities in both `declared` and `granted`, with the
+    /// scope (a scope octos refuses grants nothing).
+    pub fn new<'a, 'b>(
+        app_id: &str,
+        declared: impl IntoIterator<Item = &'a str>,
+        granted: impl IntoIterator<Item = &'b str>,
+        scope: Option<&Value>,
+    ) -> Self {
+        let granted: BTreeSet<&str> = granted.into_iter().collect();
+        let grants: BTreeSet<String> = declared
+            .into_iter()
+            .filter(|c| (*c == RESEARCH || *c == CRAWL) && granted.contains(c))
+            .map(str::to_owned)
+            .collect();
+        if grants.is_empty() {
+            return Self::none(None);
+        }
+        match scope::parse(scope.unwrap_or(&json!({}))) {
+            Ok(scope) => Self { grants, scope, notes: Vec::new() },
+            Err(why) => Self::none(Some(format!("{app_id}: its research scope is refused ({why})"))),
+        }
+    }
+
+    /// A native module's grant from its declared capabilities: reviewed
+    /// with the shell (`native-apps.json`), so what it declares is granted;
+    /// no manifest scope, so octos's defaults and no crawl limits.
+    pub fn for_module(app_id: &str, capabilities: &[&str]) -> Self {
+        Self::new(app_id, capabilities.iter().copied(), capabilities.iter().copied(), None)
+    }
+
+    /// A script app's grant from its manifest: `research`/`crawl` in its
+    /// `capabilities`, the scope under [`SCOPE_KEY`]. A manifest for another
+    /// id, a scope octos refuses, or (for now) an app that is not a system
+    /// app gets nothing.
+    pub fn for_manifest(app_id: &str, manifest: &Value) -> Self {
+        if manifest.get("id").and_then(Value::as_str) != Some(app_id) {
+            return Self::none(Some(format!("{app_id}: the manifest names another app")));
+        }
+        let declared: Vec<&str> = manifest["capabilities"]
+            .as_array()
+            .map(|c| c.iter().filter_map(Value::as_str).collect())
+            .unwrap_or_default();
+        let wants = declared.iter().any(|c| *c == RESEARCH || *c == CRAWL);
+        if wants && !system_app_only(app_id) {
+            return Self::none(Some(format!(
+                "{app_id} declares research or crawl, but App Hub does not verify those capabilities on this pin yet: until it does only system apps (os.*) get them"
+            )));
+        }
+        // TEMPORARY: until App Hub's verified grant, a system app's
+        // declaration is its grant.
+        Self::new(app_id, declared.iter().copied(), declared.iter().copied(), manifest.get(SCOPE_KEY))
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.grants.is_empty()
+    }
+
+    /// The toolbox's [`AppContext`] for `app_id`: these grants and scope, and
+    /// its host-owned folder under `apps_root`. `None` for an id that is not
+    /// one path segment.
+    pub fn app_context(&self, app_id: &str, apps_root: &Path) -> Option<AppContext> {
+        Some(self.context(app_id, crate::toolbox_folder(apps_root, app_id)?))
+    }
+
+    fn context(&self, app_id: &str, folder: PathBuf) -> AppContext {
+        let mut app = AppContext::new(app_id, folder).with_scope(self.scope.clone());
+        for g in &self.grants {
+            app = app.grant(g.clone());
+        }
+        app
+    }
+
+    /// The toolbox tool names this grant offers.
+    pub fn tools(&self) -> BTreeSet<&'static str> {
+        peer::tool_names(&self.context("", PathBuf::new()))
+    }
+}
+
+/// TEMPORARY (see the module docs): whether a script app `app_id` may have
+/// what it declares without App Hub's check. System apps only.
+pub fn system_app_only(app_id: &str) -> bool {
+    app_id.starts_with("os.")
+}
+
+/// The toolbox's `ModelClient` over the `model` service's host: the
+/// person's providers, the app's daily budget, one ledger
+/// (`<apps root>/.host/model/ledger.json`).
+pub struct ModelHostClient {
+    host: Option<Arc<ModelHost>>,
+    /// `<apps root>/.host`, where the ledger lives.
+    host_dir: PathBuf,
+}
+
+impl ModelHostClient {
+    /// Over the host the shell registered (`complete::host()`, looked up at
+    /// each call: the `llm` service registers it at start).
+    pub fn registered(apps_root: &Path) -> Self {
+        Self { host: None, host_dir: apps_root.join(".host") }
+    }
+
+    /// Over this host (tests).
+    pub fn new(host: Arc<ModelHost>, apps_root: &Path) -> Self {
+        Self { host: Some(host), host_dir: apps_root.join(".host") }
+    }
+
+    /// The toolbox's request as a host caller's `model.complete`: the
+    /// template's prompt as the host-only `system`, its user document as the
+    /// input, its output schema, and URLs allowed (the toolbox's own
+    /// `validate_digest` checks the reply after).
+    pub fn request(request: &ModelRequest) -> complete::Request {
+        complete::Request {
+            // Both tasks are bounded by their schema; the fast class is what
+            // the templates were validated on (deepseek-v4-flash).
+            class: Class::Fast,
+            task: String::new(),
+            input: Value::String(request.user.clone()),
+            schema: request.output_schema.clone(),
+            allow_urls: true,
+            system: Some(request.system.clone()),
+        }
+    }
+}
+
+impl ModelClient for ModelHostClient {
+    fn complete<'a>(&'a self, ctx: &'a CallContext, request: ModelRequest) -> HostFuture<'a, Result<String, HostError>> {
+        Box::pin(async move {
+            let Some(host) = self.host.clone().or_else(complete::host) else {
+                return Err(HostError::Denied("no_provider: the model service is not running in this shell".into()));
+            };
+            host.attach(&self.host_dir);
+            let app = ctx.app.app_id.clone();
+            let request = Self::request(&request);
+            let answer = tokio::task::spawn_blocking(move || host.complete(&app, request))
+                .await
+                .map_err(|e| HostError::Failed(format!("model call: {e}")))?;
+            match answer {
+                Ok(done) => Ok(done.output.to_string()),
+                Err(refusal) => Err(match refusal.code {
+                    Code::Budget | Code::Rate | Code::Capability | Code::NoProvider => HostError::Denied(refusal.to_string()),
+                    _ => HostError::Failed(refusal.to_string()),
+                }),
+            }
+        })
+    }
+}
+
+/// One call's cancel: fired by the relay's cancel, awaited by the worker.
+#[derive(Default)]
+struct Cancel {
+    fired: AtomicBool,
+    notify: Notify,
+}
+
+impl Cancel {
+    fn fire(&self) {
+        self.fired.store(true, Ordering::Release);
+        self.notify.notify_waiters();
+    }
+    fn is_fired(&self) -> bool {
+        self.fired.load(Ordering::Acquire)
+    }
+    async fn fired(&self) {
+        loop {
+            let notified = self.notify.notified();
+            if self.is_fired() {
+                return;
+            }
+            notified.await;
+        }
+    }
+}
+
+/// Builds an app's toolbox, on its worker thread.
+pub type MakeToolbox = Arc<dyn Fn() -> Result<PeerToolbox, String> + Send + Sync>;
+
+struct Job {
+    call: HostToolCall,
+    reply: ToolReply,
+    cancel: Arc<Cancel>,
+}
+
+struct AppEntry {
+    grant: ToolboxGrant,
+    /// The app's worker, started at its first call.
+    jobs: Option<mpsc::UnboundedSender<Job>>,
+}
+
+struct Inner {
+    apps_root: PathBuf,
+    make: MakeToolbox,
+    apps: Mutex<HashMap<String, AppEntry>>,
+    running: Mutex<HashMap<String, Arc<Cancel>>>,
+}
+
+/// The relay's executor for the `toolbox` owner: runs each call with the
+/// calling app's grant. The toolbox's futures are not `Send` (the template
+/// VM stays on its thread), so each app's toolbox lives on a worker thread
+/// of its own; calls reach it over a channel, and a cancel stops a call
+/// there. A cancelled call is never answered.
+#[derive(Clone)]
+pub struct ToolboxExecutor(Arc<Inner>);
+
+impl ToolboxExecutor {
+    /// Toolboxes built by `make`, with results under `apps_root`.
+    pub fn new(apps_root: &Path, make: MakeToolbox) -> Self {
+        Self(Arc::new(Inner {
+            apps_root: apps_root.to_path_buf(),
+            make,
+            apps: Mutex::new(HashMap::new()),
+            running: Mutex::new(HashMap::new()),
+        }))
+    }
+
+    /// The shell's: the octos research engine, and the person's providers
+    /// through the `model` service.
+    pub fn shell(apps_root: &Path) -> Self {
+        let root = apps_root.to_path_buf();
+        Self::new(
+            apps_root,
+            Arc::new(move || {
+                let library = Library::builtin().map_err(|e| e.to_string())?;
+                let backend = Arc::new(OctosResearch::new(OctosConfig::from_env()));
+                Ok(PeerToolbox::new(library, backend, Arc::new(ModelHostClient::registered(&root))))
+            }),
+        )
+    }
+
+    /// Set `app_id`'s grant (a module's id, or a contained app's id without
+    /// its peer's `card.` prefix). Returns the tool names it offers. A
+    /// changed grant starts a new worker at the next call.
+    pub fn set_grant(&self, app_id: &str, grant: ToolboxGrant) -> BTreeSet<&'static str> {
+        let tools = grant.tools();
+        let mut apps = self.0.apps.lock().unwrap_or_else(|e| e.into_inner());
+        match apps.get_mut(app_id) {
+            Some(entry) if entry.grant == grant => {}
+            _ => {
+                apps.insert(app_id.to_owned(), AppEntry { grant, jobs: None });
+            }
+        }
+        tools
+    }
+
+    /// The tool names `app_id` is granted (empty for an app never granted).
+    pub fn tools(&self, app_id: &str) -> BTreeSet<&'static str> {
+        self.0.apps.lock().unwrap_or_else(|e| e.into_inner()).get(app_id).map(|e| e.grant.tools()).unwrap_or_default()
+    }
+
+    /// Calls running now.
+    pub fn running(&self) -> usize {
+        self.0.running.lock().unwrap_or_else(|e| e.into_inner()).len()
+    }
+
+    fn worker_for(&self, app_id: &str) -> Result<mpsc::UnboundedSender<Job>, ToolOutcome> {
+        let mut apps = self.0.apps.lock().unwrap_or_else(|e| e.into_inner());
+        let Some(entry) = apps.get_mut(app_id) else {
+            return Err(ToolOutcome::error("not_granted", format!("{app_id} has no toolbox grant")));
+        };
+        if let Some(jobs) = entry.jobs.as_ref().filter(|j| !j.is_closed()) {
+            return Ok(jobs.clone());
+        }
+        let app = entry
+            .grant
+            .app_context(app_id, &self.0.apps_root)
+            .ok_or_else(|| ToolOutcome::error("not_granted", format!("{app_id} cannot have a toolbox folder")))?;
+        let (jobs, rx) = mpsc::unbounded_channel();
+        let make = self.0.make.clone();
+        let inner = Arc::downgrade(&self.0);
+        std::thread::Builder::new()
+            .name(format!("toolbox-{app_id}"))
+            .spawn(move || worker(app, make, rx, inner))
+            .map_err(|e| ToolOutcome::error("unavailable", format!("no toolbox worker: {e}")))?;
+        entry.jobs = Some(jobs.clone());
+        Ok(jobs)
+    }
+}
+
+impl ToolExecutor for ToolboxExecutor {
+    fn execute(&self, call: HostToolCall, reply: ToolReply) {
+        if !reply.is_open() {
+            return;
+        }
+        // The relay authorized the call; the toolbox checks its own grant.
+        let app = app_of_peer(&call.calling_app).to_owned();
+        if !self.tools(&app).contains(call.name.as_str()) {
+            reply.finish(ToolOutcome::error("not_granted", format!("{} is not among {app}'s toolbox tools", call.name)));
+            return;
+        }
+        let jobs = match self.worker_for(&app) {
+            Ok(jobs) => jobs,
+            Err(outcome) => {
+                reply.finish(outcome);
+                return;
+            }
+        };
+        let cancel = Arc::new(Cancel::default());
+        self.0.running.lock().unwrap_or_else(|e| e.into_inner()).insert(call.call_id.clone(), cancel.clone());
+        let call_id = call.call_id.clone();
+        if jobs.send(Job { call, reply: reply.clone(), cancel }).is_err() {
+            self.0.running.lock().unwrap_or_else(|e| e.into_inner()).remove(&call_id);
+            reply.finish(ToolOutcome::error("unavailable", "the toolbox is not running"));
+        }
+    }
+
+    fn cancel(&self, call_id: &str) {
+        if let Some(cancel) = self.0.running.lock().unwrap_or_else(|e| e.into_inner()).remove(call_id) {
+            cancel.fire();
+        }
+    }
+}
+
+/// A contained app's peer is `card.<app id>`; its grant is the app's.
+fn app_of_peer(app: &str) -> &str {
+    app.strip_prefix(crate::contained::PEER_PREFIX).unwrap_or(app)
+}
+
+fn worker(app: AppContext, make: MakeToolbox, mut jobs: mpsc::UnboundedReceiver<Job>, inner: std::sync::Weak<Inner>) {
+    let runtime = match tokio::runtime::Builder::new_current_thread().enable_all().build() {
+        Ok(rt) => rt,
+        Err(e) => {
+            makepad_widgets::log!("toolbox: no runtime for {}: {e}", app.app_id);
+            return;
+        }
+    };
+    let local = tokio::task::LocalSet::new();
+    local.block_on(&runtime, async move {
+        let toolbox = make().map(Rc::new);
+        if let Err(why) = &toolbox {
+            makepad_widgets::log!("toolbox: {} has no toolbox: {why}", app.app_id);
+        }
+        let app = Rc::new(app);
+        while let Some(Job { call, reply, cancel }) = jobs.recv().await {
+            let toolbox = toolbox.clone();
+            let app = app.clone();
+            let inner = inner.clone();
+            tokio::task::spawn_local(async move {
+                let outcome = if cancel.is_fired() {
+                    None
+                } else {
+                    match &toolbox {
+                        Err(why) => Some(ToolOutcome::error("unavailable", why.clone())),
+                        Ok(toolbox) => tokio::select! {
+                            result = toolbox.call(&app, &call.name, call.args) => Some(match result {
+                                Ok(data) => ToolOutcome::Ok(data),
+                                Err(e) => ToolOutcome::error(&e.kind, e.message),
+                            }),
+                            // Never finish a call the kernel stopped waiting for.
+                            _ = cancel.fired() => None,
+                        },
+                    }
+                };
+                if let Some(inner) = inner.upgrade() {
+                    inner.running.lock().unwrap_or_else(|e| e.into_inner()).remove(&call.call_id);
+                }
+                if let Some(outcome) = outcome {
+                    // False (nothing sent) when the call was cancelled meanwhile.
+                    reply.finish(outcome);
+                }
+            });
+        }
+    });
+}
diff --git a/crates/ai-host/tests/toolbox_peers.rs b/crates/ai-host/tests/toolbox_peers.rs
new file mode 100644
index 00000000..9e31b4a1
--- /dev/null
+++ b/crates/ai-host/tests/toolbox_peers.rs
@@ -0,0 +1,540 @@
+//! The system toolbox for app agents (feature `toolbox-peers`): the grants,
+//! and the executor the shell's host-tool relay routes the `toolbox`
+//! owner's calls to, driven through main's broker (its registration after
+//! `peer/prepare`, its `peer/tool/call` handling) against a scripted kernel
+//! speaking octos UPCR-2026-034/035. The `ToolHost` here stands in for the
+//! shell's relay (`crates/shell/src/host_tools`, tested there): the
+//! toolbox's catalog narrowed to the app's grant, nothing before consent.
+//! The toolbox runs over its fixture backends (recorded searches and pages,
+//! `FakeModel`) or the `model` service's host over a fake provider. No
+//! network, no kernel binary.
+#![cfg(feature = "toolbox-peers")]
+
+use std::collections::{BTreeSet, VecDeque};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use octosense_ai_host::app_peers::broker::{BoxFuture, Broker, BrokerConfig, Connector, Link, ToolHostHandle};
+use octosense_ai_host::app_peers::host_tools::{HostToolCall, ToolExecutor, ToolHost, ToolOutcome, ToolReply};
+use octosense_ai_host::app_peers::{Deployment, OCTOS_SERVICES};
+use octosense_ai_host::toolbox_peers::{catalog, ModelHostClient, ToolboxExecutor, ToolboxGrant, OWNER};
+use octosense_llm_config::Provider;
+use octosense_llm_service::complete::{self, ledger::Limits, Candidate, ModelHost, Providers, Transport};
+use octosense_toolbox::fixture::{self, FixtureBackend, FixtureCase, FixtureData};
+use octosense_toolbox::host::CallContext;
+use octosense_toolbox::peer::{PeerToolbox, DEEP_CRAWL, FORK, RUN, SEARCH, WEB_READ};
+use octosense_toolbox::research::{ModelClient, ModelRequest, ModelTask};
+use octosense_toolbox::Library;
+use serde_json::{json, Value};
+use tokio::sync::mpsc;
+
+const TOKEN: &str = "fixture-host-token";
+const APP: &str = "os.news";
+
+// ---- a scripted kernel ---------------------------------------------------------
+
+#[derive(Default)]
+struct Script {
+    calls: Vec<(String, Value)>,
+    out: Option<mpsc::UnboundedSender<String>>,
+}
+
+struct FakeConnector(Arc<Mutex<Script>>);
+
+struct FakeLink {
+    to_kernel: mpsc::UnboundedSender<String>,
+    from_kernel: mpsc::UnboundedReceiver<String>,
+}
+
+impl Link for FakeLink {
+    fn send(&mut self, frame: String) -> Result<(), String> {
+        self.to_kernel.send(frame).map_err(|_| "gone".to_owned())
+    }
+    fn recv(&mut self) -> BoxFuture<'_, Result<String, String>> {
+        Box::pin(async move { self.from_kernel.recv().await.ok_or_else(|| "closed".to_owned()) })
+    }
+}
+
+impl Connector for FakeConnector {
+    fn available(&self) -> Result<(), String> {
+        Ok(())
+    }
+    fn connect(&self) -> BoxFuture<'static, Result<Box<dyn Link>, String>> {
+        let script = self.0.clone();
+        Box::pin(async move {
+            let (to_kernel, mut kernel_in) = mpsc::unbounded_channel::<String>();
+            let (kernel_out, from_kernel) = mpsc::unbounded_channel::<String>();
+            script.lock().unwrap().out = Some(kernel_out.clone());
+            tokio::spawn(async move {
+                while let Some(frame) = kernel_in.recv().await {
+                    let frame: Value = serde_json::from_str(&frame).unwrap();
+                    let Some(method) = frame["method"].as_str().map(str::to_owned) else { continue };
+                    let params = frame["params"].clone();
+                    script.lock().unwrap().calls.push((method.clone(), params.clone()));
+                    let result = match method.as_str() {
+                        "peer/prepare" => json!({"slug": "news-1", "cwd": "/kernel/ws",
+                            "memory_namespace": params["memory_namespace"], "host_token": TOKEN}),
+                        "peer/tools/register" => json!({"slug": "news-1", "version": 1, "tools": params["tools"], "generic_tools": null, "applies": "next_turn"}),
+                        "peer/tool/result" => json!({"call_id": params["call_id"], "accepted": true}),
+                        _ => json!({}),
+                    };
+                    let _ = kernel_out.send(json!({"jsonrpc": "2.0", "id": frame["id"], "result": result}).to_string());
+                }
+            });
+            Ok(Box::new(FakeLink { to_kernel, from_kernel }) as Box<dyn Link>)
+        })
+    }
+    fn owns_runtime(&self) -> bool {
+        false
+    }
+    fn shutdown(&self) {}
+}
+
+// ---- the shell's relay, as far as the toolbox needs it --------------------------
+
+/// The relay's part for the `toolbox` owner (`crates/shell/src/host_tools`):
+/// the catalog narrowed to the app's grant, offered and run only once the
+/// person allowed the app's agent; calls and cancels go to the executor.
+struct Relay {
+    executor: ToolboxExecutor,
+    consent: AtomicBool,
+    ran: Mutex<Vec<String>>,
+}
+
+impl ToolHost for Relay {
+    fn declarations(&self, app_id: &str, _account: &str) -> Result<Vec<Value>, String> {
+        if !self.consent.load(Ordering::SeqCst) {
+            return Ok(Vec::new());
+        }
+        let granted = self.executor.tools(app_id);
+        Ok(catalog().into_iter().filter(|d| d["name"].as_str().is_some_and(|n| granted.contains(n))).collect())
+    }
+    fn tool_call(&self, call: HostToolCall, reply: ToolReply) {
+        if !self.consent.load(Ordering::SeqCst) {
+            reply.finish(ToolOutcome::error("consent_pending", "the person has not allowed this app's agent"));
+            return;
+        }
+        if call.app != OWNER || !self.executor.tools(&call.calling_app).contains(call.name.as_str()) {
+            reply.finish(ToolOutcome::error("not_granted", format!("{} is not granted", call.name)));
+            return;
+        }
+        self.ran.lock().unwrap().push(call.name.clone());
+        self.executor.execute(call, reply);
+    }
+    fn tool_cancel(&self, _app_id: &str, call_id: &str, _reason: &str) {
+        self.executor.cancel(call_id);
+    }
+}
+
+fn relay(executor: ToolboxExecutor) -> Arc<Relay> {
+    Arc::new(Relay { executor, consent: AtomicBool::new(true), ran: Mutex::new(Vec::new()) })
+}
+
+/// A broker for `os.news` whose tool host is `host`, bound to its peer.
+fn bound(host: Arc<Relay>) -> (Broker, Arc<Mutex<Script>>) {
+    let script = Arc::new(Mutex::new(Script::default()));
+    let services: BTreeSet<String> = OCTOS_SERVICES.iter().map(|s| s.to_string()).collect();
+    let mut cfg = BrokerConfig::new(Deployment::Hosted, "_main", "_main:api:octosense#system", APP, "News", services);
+    cfg.tool_host = Some(ToolHostHandle(host));
+    let broker = Broker::new(cfg, Arc::new(FakeConnector(script.clone())));
+    octosense_ai_host::app_peers::OctosAppService::set_account(&broker, Some("device"));
+    broker.bind().unwrap();
+    (broker, script)
+}
+
+fn registered(script: &Arc<Mutex<Script>>) -> Vec<Value> {
+    let calls = script.lock().unwrap().calls.clone();
+    let (_, params) = calls.iter().rev().find(|(m, _)| m == "peer/tools/register").expect("a registration");
+    assert_eq!(params["host_token"], TOKEN);
+    assert!(params.get("generic_tools").is_none(), "omitted: the peer keeps its kernel roster");
+    params["tools"].as_array().unwrap().clone()
+}
+
+fn registered_names(script: &Arc<Mutex<Script>>) -> Vec<String> {
+    registered(script).iter().map(|t| t["name"].as_str().unwrap().to_owned()).collect()
+}
+
+fn inject(script: &Arc<Mutex<Script>>, method: &str, params: Value) {
+    let out = script.lock().unwrap().out.clone().expect("a link");
+    out.send(json!({"jsonrpc": "2.0", "method": method, "params": params}).to_string()).unwrap();
+}
+
+static CALLS: AtomicU32 = AtomicU32::new(0);
+
+/// Sends one `peer/tool/call` for a toolbox tool, as the kernel does (the
+/// owning app from the declaration); its call id.
+fn call(script: &Arc<Mutex<Script>>, name: &str, args: Value) -> String {
+    let n = CALLS.fetch_add(1, Ordering::Relaxed);
+    let call_id = format!("call-{n}");
+    inject(
+        script,
+        "peer/tool/call",
+        json!({"peer": "news-1", "session_id": "_main:api:octosense#peer-news-1", "context_id": null,
+               "turn_id": "turn-1", "call_id": call_id, "tool_call_id": format!("tc-{n}"), "args_digest": "d",
+               "name": name, "app": OWNER, "caller": {"kind": "app_peer", "peer": "news-1"},
+               "args": args, "risk": "read", "confirm_required": false,
+               "timeout_ms": 60_000, "tools_version": 1}),
+    );
+    call_id
+}
+
+fn result_of(script: &Arc<Mutex<Script>>, call_id: &str) -> Option<Value> {
+    script
+        .lock()
+        .unwrap()
+        .calls
+        .iter()
+        .find(|(m, p)| m == "peer/tool/result" && p["call_id"] == call_id)
+        .map(|(_, p)| p.clone())
+}
+
+fn wait(script: &Arc<Mutex<Script>>, call_id: &str) -> Value {
+    let deadline = Instant::now() + Duration::from_secs(20);
+    loop {
+        if let Some(result) = result_of(script, call_id) {
+            return result;
+        }
+        assert!(Instant::now() < deadline, "no result for {call_id}");
+        std::thread::sleep(Duration::from_millis(20));
+    }
+}
+
+// ---- fixtures -------------------------------------------------------------------
+
+fn temp(tag: &str) -> PathBuf {
+    static N: AtomicU32 = AtomicU32::new(0);
+    let dir = std::env::temp_dir().join(format!("toolbox-peers-{tag}-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    dir
+}
+
+fn case(template: &str, name: &str) -> FixtureCase {
+    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../toolbox/templates")
+        .join(template)
+        .join("fixtures")
+        .join(format!("{name}.json"));
+    serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap()
+}
+
+fn manifest(capabilities: &[&str], scope: Option<Value>) -> Value {
+    let mut m = json!({"id": APP, "capabilities": capabilities});
+    if let Some(scope) = scope {
+        m["research"] = scope;
+    }
+    m
+}
+
+/// The toolbox executor over recorded searches and pages and the fake model.
+fn fixture_executor(root: &Path, data: FixtureData) -> ToolboxExecutor {
+    ToolboxExecutor::new(
+        root,
+        Arc::new(move || {
+            let library = Library::builtin().map_err(|e| e.to_string())?;
+            let backend = Arc::new(FixtureBackend::new(data.clone()));
+            Ok(PeerToolbox::from_host(library, fixture::host(&data), backend))
+        }),
+    )
+}
+
+/// A broker for News with `grant`, over the fixture toolbox.
+fn news(root: &Path, data: FixtureData, grant: ToolboxGrant) -> (Broker, Arc<Mutex<Script>>, Arc<Relay>) {
+    let executor = fixture_executor(root, data);
+    executor.set_grant(APP, grant);
+    let host = relay(executor);
+    let (broker, script) = bound(host.clone());
+    (broker, script, host)
+}
+
+// ---- registration ---------------------------------------------------------------
+
+#[test]
+fn a_peer_is_offered_exactly_its_declared_and_granted_toolbox_tools() {
+    let root = temp("register");
+    let data = case("news-digest", "city-infrastructure").fixture;
+    let names = |grant: ToolboxGrant| -> Vec<String> { registered_names(&news(&root, data.clone(), grant).1) };
+    let crawl_scope = Some(json!({"max_depth": 2, "max_pages": 5}));
+    // research: the templates and the single research tools.
+    assert_eq!(names(ToolboxGrant::for_manifest(APP, &manifest(&["storage", "research"], None))), [RUN, FORK, SEARCH, WEB_READ]);
+    // research and crawl, with crawl limits.
+    assert_eq!(
+        names(ToolboxGrant::for_manifest(APP, &manifest(&["research", "crawl"], crawl_scope.clone()))),
+        [RUN, FORK, SEARCH, WEB_READ, DEEP_CRAWL]
+    );
+    // crawl alone: only the crawl.
+    assert_eq!(names(ToolboxGrant::for_manifest(APP, &manifest(&["crawl"], crawl_scope.clone()))), [DEEP_CRAWL]);
+    // crawl without limits in the scope: no crawling.
+    assert!(names(ToolboxGrant::for_manifest(APP, &manifest(&["research", "crawl"], None))).iter().all(|n| n != DEEP_CRAWL));
+    // No grant: the empty set is still registered.
+    assert!(names(ToolboxGrant::for_manifest(APP, &manifest(&["storage", "net"], None))).is_empty());
+    // Declared but not granted, or granted but not declared: nothing.
+    assert!(names(ToolboxGrant::new(APP, ["research", "crawl"], ["storage"], crawl_scope.as_ref())).is_empty());
+    assert!(names(ToolboxGrant::new(APP, ["storage"], ["research", "crawl"], crawl_scope.as_ref())).is_empty());
+    // Declared and granted in part: only the intersection.
+    assert_eq!(names(ToolboxGrant::new(APP, ["research", "crawl"], ["crawl"], crawl_scope.as_ref())), [DEEP_CRAWL]);
+    // A native module: what it declares (reviewed with the shell).
+    assert_eq!(ToolboxGrant::for_module("rinx", &["octos.turn.start"]).tools(), BTreeSet::new());
+    assert_eq!(ToolboxGrant::for_module("reference", &["research"]).tools(), BTreeSet::from([RUN, FORK, SEARCH, WEB_READ]));
+    // Each registered tool names its owning app and is what the kernel takes.
+    let full = ToolboxGrant::for_manifest(APP, &manifest(&["research", "crawl"], crawl_scope));
+    for d in registered(&news(&root, data, full).1) {
+        assert_eq!(d["app"], OWNER, "{d}");
+        assert_eq!(d["risk"], if d["name"] == FORK { "act" } else { "read" }, "{d}");
+        assert_eq!((d["background"].as_bool(), d["outward"].as_bool(), d["confirm"].as_str()), (Some(true), Some(false), Some("host")));
+    }
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn no_toolbox_tool_is_offered_or_run_before_consent() {
+    let root = temp("consent");
+    let case = case("news-digest", "city-infrastructure");
+    let executor = fixture_executor(&root, case.fixture.clone());
+    executor.set_grant(APP, ToolboxGrant::for_manifest(APP, &manifest(&["research"], None)));
+    let host = relay(executor);
+    host.consent.store(false, Ordering::SeqCst);
+    let (broker, script) = bound(host.clone());
+    assert!(registered_names(&script).is_empty(), "nothing offered before consent");
+    let id = call(&script, SEARCH, json!({"query": "city infrastructure", "lang": "en"}));
+    let refused = wait(&script, &id);
+    assert_eq!(refused["error"]["kind"], "consent_pending", "{refused}");
+    assert!(host.ran.lock().unwrap().is_empty(), "nothing ran");
+    assert!(!root.join(".host/toolbox/os.news").exists(), "nothing written");
+    // Once allowed, the next registration (a new peer or a reconnect) offers them.
+    host.consent.store(true, Ordering::SeqCst);
+    drop(broker);
+    let (_broker, script) = bound(host);
+    assert_eq!(registered_names(&script), [RUN, FORK, SEARCH, WEB_READ]);
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn until_app_hub_verifies_the_grant_only_system_apps_get_what_their_manifest_declares() {
+    let store = json!({"id": "com.example.news", "capabilities": ["research", "crawl"], "research": {"max_depth": 1, "max_pages": 3}});
+    let grant = ToolboxGrant::for_manifest("com.example.news", &store);
+    assert!(grant.is_empty());
+    assert!(grant.notes[0].contains("only system apps"), "{:?}", grant.notes);
+    // A manifest for another app, or a scope octos refuses, grants nothing.
+    assert!(ToolboxGrant::for_manifest("os.mail", &manifest(&["research"], None)).is_empty());
+    let bad = ToolboxGrant::for_manifest(APP, &manifest(&["research"], Some(json!({"languages": ["en"]}))));
+    assert!(bad.is_empty() && bad.notes[0].contains("old toolbox shape"), "{:?}", bad.notes);
+    let good = ToolboxGrant::for_manifest(APP, &manifest(&["research"], Some(json!({"langs": ["en"], "max_age_days": 2}))));
+    assert_eq!(good.grants, BTreeSet::from(["research".to_owned()]));
+    assert_eq!(good.scope.langs, ["en"]);
+}
+
+// ---- calls ----------------------------------------------------------------------
+
+#[test]
+fn a_workflow_run_is_executed_by_the_toolbox_and_its_result_lands_in_the_host_folder() {
+    let root = temp("run");
+    let case = case("news-digest", "city-infrastructure");
+    let (_broker, script, _) = news(&root, case.fixture.clone(), ToolboxGrant::for_manifest(APP, &manifest(&["research"], None)));
+    let id = call(&script, RUN, json!({"id": "news-digest", "params": case.params, "run_id": "glance"}));
+    let result = wait(&script, &id);
+    assert_eq!(result["ok"], true, "{result}");
+    let data = &result["data"];
+    assert_eq!(data["status"], "ready", "{data}");
+    assert_eq!(data["run_id"], "glance");
+    assert_eq!(data["result"], "toolbox/runs/news-digest/glance.json");
+    assert!(!data["sources"].as_array().unwrap().is_empty());
+    // In the host's folder, where sys.digest reads; never in the app's jail.
+    let file = octosense_ai_host::toolbox_folder(&root, APP).unwrap().join("toolbox/runs/news-digest/glance.json");
+    assert_eq!(file, root.join(".host/toolbox/os.news/toolbox/runs/news-digest/glance.json"));
+    let saved: Value = serde_json::from_str(&std::fs::read_to_string(&file).unwrap()).unwrap();
+    assert_eq!(saved["app_id"], APP);
+    assert!(!root.join(APP).exists(), "nothing is written into the app's jail");
+
+    // A fork is written there too, and is runnable by its new id.
+    let id = call(&script, FORK, json!({"id": "news-digest", "new_id": "my-digest"}));
+    let fork = wait(&script, &id);
+    assert_eq!(fork["ok"], true, "{fork}");
+    assert!(root.join(".host/toolbox/os.news/toolbox/templates/my-digest/template.json").exists());
+
+    // The single tools save their items in the host folder too.
+    let id = call(&script, SEARCH, json!({"query": "city infrastructure", "lang": "en", "count": 2}));
+    let search = wait(&script, &id);
+    assert_eq!(search["ok"], true, "{search}");
+    assert_eq!(search["data"]["items"].as_array().unwrap().len(), 2);
+    let saved = search["data"]["file"].as_str().unwrap();
+    assert!(saved.starts_with("research/search-"), "{saved}");
+    assert!(root.join(".host/toolbox/os.news").join(saved).exists());
+    let id = call(&script, WEB_READ, json!({"url": "https://example.invalid/news/buses"}));
+    let read = wait(&script, &id);
+    assert_eq!(read["ok"], true, "{read}");
+    assert!(read["data"]["text"].as_str().unwrap().contains("electric buses"));
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn calls_outside_the_scope_are_refused() {
+    let root = temp("scope");
+    let case = case("news-digest", "city-infrastructure");
+    let grant = ToolboxGrant::for_manifest(APP, &manifest(&["research"], Some(json!({"langs": ["en"], "domains_deny": ["example.invalid"]}))));
+    let (_broker, script, _) = news(&root, case.fixture.clone(), grant);
+    let id = call(&script, SEARCH, json!({"query": "infrastructure", "lang": "fr"}));
+    let refused = wait(&script, &id);
+    assert_eq!(refused["ok"], false);
+    assert_eq!(refused["error"]["kind"], "denied");
+    assert!(refused["error"]["message"].as_str().unwrap().contains("not in this app's research grant"));
+    let id = call(&script, WEB_READ, json!({"url": "https://example.invalid/news/buses"}));
+    let refused = wait(&script, &id);
+    assert_eq!(refused["error"]["kind"], "denied", "{refused}");
+    // A template run keeps to the scope too: every read is refused, so the
+    // run has nothing to digest.
+    let id = call(&script, RUN, json!({"id": "news-digest", "params": case.params}));
+    let run = wait(&script, &id);
+    assert_eq!(run["ok"], true, "{run}");
+    assert_ne!(run["data"]["status"], "ready", "{run}");
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn an_app_without_crawl_cannot_crawl_even_with_a_forged_call() {
+    let root = temp("crawl");
+    let data = case("news-digest", "city-infrastructure").fixture;
+    let grant = ToolboxGrant::for_manifest(APP, &manifest(&["research"], Some(json!({"max_depth": 2, "max_pages": 5}))));
+    let executor = fixture_executor(&root, data);
+    executor.set_grant(APP, grant);
+    let (_broker, script) = bound(relay(executor.clone()));
+    assert!(!registered_names(&script).iter().any(|n| n == DEEP_CRAWL));
+    // The kernel would not send it; if it did, the relay refuses it.
+    let id = call(&script, DEEP_CRAWL, json!({"url": "https://example.invalid/"}));
+    assert_eq!(wait(&script, &id)["error"]["kind"], "not_granted");
+    // And the toolbox's executor refuses it on its own, whoever asks.
+    let sent = Arc::new(Mutex::new(Vec::<Value>::new()));
+    let s = sent.clone();
+    let mut forged = HostToolCall::parse(&json!({"peer": "news-1", "session_id": "s", "turn_id": "t", "call_id": "forged", "name": DEEP_CRAWL, "app": OWNER, "caller": {"kind": "app_peer"}, "args": {"url": "https://example.invalid/"}})).unwrap();
+    forged.calling_app = APP.into();
+    executor.execute(forged, ToolReply::new("forged", move |v| s.lock().unwrap().push(v)));
+    assert_eq!(sent.lock().unwrap()[0]["error"]["kind"], "not_granted");
+    assert!(!root.join(".host/toolbox/os.news/research").exists());
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+#[test]
+fn a_cancelled_run_is_stopped_and_never_answered() {
+    let root = temp("cancel");
+    let case = case("news-digest", "city-infrastructure");
+    let mut data = case.fixture.clone();
+    for search in &mut data.searches {
+        search.delay_ms = 5_000;
+    }
+    let (_broker, script, host) = news(&root, data, ToolboxGrant::for_manifest(APP, &manifest(&["research"], None)));
+    let id = call(&script, RUN, json!({"id": "news-digest", "params": case.params, "run_id": "cancelled"}));
+    std::thread::sleep(Duration::from_millis(200));
+    assert_eq!(host.executor.running(), 1);
+    inject(&script, "peer/tool/cancel", json!({"call_id": id, "reason": "cancelled"}));
+    std::thread::sleep(Duration::from_millis(800));
+    assert!(result_of(&script, &id).is_none());
+    assert_eq!(host.executor.running(), 0, "stopped");
+    assert!(!root.join(".host/toolbox/os.news/toolbox/runs/news-digest/cancelled.json").exists());
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+// ---- model calls through the model service's host ----------------------------
+
+/// A provider answering OpenAI chat completions from a queue.
+#[derive(Default)]
+struct FakeProvider {
+    answers: Mutex<VecDeque<String>>,
+    seen: Mutex<Vec<Value>>,
+}
+
+impl Transport for FakeProvider {
+    fn post(&self, _url: &str, _headers: &[(String, String)], body: &str) -> Result<(u16, Vec<u8>), String> {
+        self.seen.lock().unwrap().push(serde_json::from_str(body).unwrap());
+        let content = self.answers.lock().unwrap().pop_front().ok_or("connection refused")?;
+        let reply = json!({"choices": [{"message": {"content": content}}], "usage": {"prompt_tokens": 100, "completion_tokens": 20}});
+        Ok((200, reply.to_string().into_bytes()))
+    }
+}
+
+struct Fixed;
+impl Providers for Fixed {
+    fn candidates(&self) -> Result<Vec<Candidate>, String> {
+        Ok(vec![Candidate {
+            provider: Provider::new("deepseek", Some("deepseek-v4-flash".into())),
+            key: Some("sk-test-deepseek-0000aaaa1234".into()),
+        }])
+    }
+}
+
+fn model_host(provider: Arc<FakeProvider>) -> Arc<ModelHost> {
+    Arc::new(ModelHost::new(
+        &complete::Options::default().providers(Arc::new(Fixed)).transport(provider).clock(|| 1_790_000_000_000),
+    ))
+}
+
+#[test]
+fn template_model_calls_use_the_model_service_and_the_apps_daily_budget() {
+    let root = temp("budget");
+    let provider = Arc::new(FakeProvider::default());
+    let host = model_host(provider.clone());
+    let client = ModelHostClient::new(host.clone(), &root);
+    let grant = ToolboxGrant::for_manifest(APP, &manifest(&["research"], None));
+    let app = grant.app_context(APP, &root).unwrap();
+    let ctx = CallContext {
+        app: Arc::new(app),
+        run_id: "r".into(),
+        template_id: "news-digest".into(),
+        template_digest: String::new(),
+        budget: octosense_toolbox::Budget { max_calls: 8, max_model_calls: 2, max_reads: 4, max_ms: 60_000, max_concurrency: 1 },
+        remaining: octosense_toolbox::host::Remaining { calls: 8, model_calls: 2, reads: 4, ms: 60_000 },
+        call_index: 0,
+    };
+    let request = ModelRequest {
+        task: ModelTask::TranslateQuery,
+        system: "Translate the research query.".into(),
+        user: json!({"query": "typhoon", "language": "zh"}).to_string(),
+        max_output_tokens: None,
+        output_schema: json!({"type": "object", "required": ["query"], "properties": {"query": {"type": "string"}}}),
+    };
+    provider.answers.lock().unwrap().push_back(json!({"query": "台风"}).to_string());
+    let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
+    let reply = runtime.block_on(client.complete(&ctx, request.clone())).unwrap();
+    assert_eq!(serde_json::from_str::<Value>(&reply).unwrap()["query"], "台风");
+    // The template's own prompt and document went out, and no token cap.
+    let sent = provider.seen.lock().unwrap()[0].clone();
+    assert!(sent["messages"][0]["content"].as_str().unwrap().starts_with("Translate the research query."));
+    assert!(sent.get("max_tokens").is_none());
+    // Charged to the app in the model service's ledger, under the host dir.
+    assert_eq!(host.budget(APP).calls_today, 1);
+    assert_eq!(host.budget(APP).tokens_today, 120);
+    let ledger: Value = serde_json::from_str(&std::fs::read_to_string(root.join(".host/model/ledger.json")).unwrap()).unwrap();
+    assert_eq!(ledger["apps"][APP]["calls"], 1, "{ledger}");
+
+    // The day's budget is spent: the next model call is refused as budget.
+    host.set_limits(APP, Limits { per_minute: 6, calls_per_day: 1, tokens_per_day: 100_000 });
+    let refused = runtime.block_on(client.complete(&ctx, request)).unwrap_err();
+    assert!(refused.to_string().contains("budget"), "{refused}");
+    assert!(matches!(refused, octosense_toolbox::HostError::Denied(_)));
+
+    // A template run through the peer gets the refusal, not a digest.
+    let data = case("news-digest", "city-infrastructure");
+    let fixture = data.fixture.clone();
+    let root2 = root.clone();
+    let executor = ToolboxExecutor::new(
+        &root,
+        Arc::new(move || {
+            let backend = Arc::new(FixtureBackend::new(fixture.clone()));
+            let model = Arc::new(ModelHostClient::new(host.clone(), &root2));
+            Ok(PeerToolbox::new(Library::builtin().map_err(|e| e.to_string())?, backend, model))
+        }),
+    );
+    executor.set_grant(APP, grant);
+    let (_broker, script) = bound(relay(executor));
+    let id = call(&script, RUN, json!({"id": "news-digest", "params": data.params, "run_id": "over-budget"}));
+    let run = wait(&script, &id);
+    assert_eq!(run["ok"], true, "{run}");
+    // news-digest lists its sources without a digest when the model call
+    // fails: partial, and no model text.
+    assert_eq!(run["data"]["status"], "partial", "{run}");
+    assert!(run["data"]["data"]["digest"].is_null(), "{run}");
+    let saved = std::fs::read_to_string(root.join(".host/toolbox/os.news/toolbox/runs/news-digest/over-budget.json")).unwrap();
+    assert!(saved.contains("budget"), "the refusal is in the run's diagnostics: {saved}");
+    let _ = std::fs::remove_dir_all(&root);
+}
diff --git a/crates/ai-host/tests/toolbox_real_kernel.rs b/crates/ai-host/tests/toolbox_real_kernel.rs
new file mode 100644
index 00000000..3d08f0b4
--- /dev/null
+++ b/crates/ai-host/tests/toolbox_real_kernel.rs
@@ -0,0 +1,207 @@
+//! The toolbox's tools against a REAL octos kernel with host-registered
+//! peer tools (octos#2567, UPCR-2026-035): main's broker registers them
+//! after `peer/prepare`, a real turn calls them, and the toolbox's executor
+//! runs them (over its fixture backends), with a scripted model
+//! (`crates/app-peers/tests/fixtures/mock_agent_llm.py`). The `ToolHost`
+//! stands in for the shell's relay (`crates/shell/src/host_tools`): the
+//! toolbox's catalog narrowed to the app's grant, nothing before consent.
+//! Runs when `OCTOS_APP_PEERS_TEST_KERNEL` names an `octos` binary at the
+//! pinned revision; otherwise it says so and passes:
+//!
+//! ```sh
+//! OCTOS_APP_PEERS_TEST_KERNEL=<octos build>/octos \
+//!   cargo test -p octosense-ai-host --features toolbox-peers --test toolbox_real_kernel -- --nocapture
+//! ```
+#![cfg(feature = "toolbox-peers")]
+
+use std::collections::BTreeSet;
+use std::io::BufRead;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use octosense_ai_host::app_peers::broker::{Broker, BrokerConfig, ToolHostHandle};
+use octosense_ai_host::app_peers::connectors::CoreConnector;
+use octosense_ai_host::app_peers::host_tools::{HostToolCall, ToolExecutor, ToolHost, ToolOutcome, ToolReply};
+use octosense_ai_host::app_peers::{ContextEvent, ContextOp, ContextSpec, Deployment, OctosAppService, OCTOS_SERVICES};
+use octosense_ai_host::kernel::{Core, Options};
+use octosense_ai_host::toolbox_peers::{catalog, ToolboxExecutor, ToolboxGrant, OWNER};
+use octosense_toolbox::fixture::{self, FixtureBackend, FixtureCase};
+use octosense_toolbox::peer::PeerToolbox;
+use octosense_toolbox::Library;
+use serde_json::{json, Value};
+
+struct Model(std::process::Child);
+impl Drop for Model {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+        let _ = self.0.wait();
+    }
+}
+
+/// The shell's relay for the `toolbox` owner, as far as this test needs it.
+struct Relay {
+    executor: ToolboxExecutor,
+    consent: AtomicBool,
+    ran: Mutex<Vec<String>>,
+}
+
+impl ToolHost for Relay {
+    fn declarations(&self, app_id: &str, _account: &str) -> Result<Vec<Value>, String> {
+        if !self.consent.load(Ordering::SeqCst) {
+            return Ok(Vec::new());
+        }
+        let granted = self.executor.tools(app_id);
+        Ok(catalog().into_iter().filter(|d| d["name"].as_str().is_some_and(|n| granted.contains(n))).collect())
+    }
+    fn tool_call(&self, call: HostToolCall, reply: ToolReply) {
+        if !self.consent.load(Ordering::SeqCst) {
+            reply.finish(ToolOutcome::error("consent_pending", "the person has not allowed this app's agent"));
+            return;
+        }
+        assert_eq!(call.app, OWNER, "the kernel names the owning app");
+        self.ran.lock().unwrap().push(call.name.clone());
+        self.executor.execute(call, reply);
+    }
+    fn tool_cancel(&self, _app_id: &str, call_id: &str, _reason: &str) {
+        self.executor.cancel(call_id);
+    }
+}
+
+fn offered(log: &Path, marker: &str) -> BTreeSet<String> {
+    let text = std::fs::read_to_string(log).unwrap_or_default();
+    let request = text
+        .lines()
+        .rev()
+        .map(|l| serde_json::from_str::<Value>(l).unwrap())
+        .find(|r| r["user"].as_str().unwrap_or("").contains(marker))
+        .unwrap_or_else(|| panic!("no model request for {marker}"));
+    request["tools"].as_array().unwrap().iter().filter_map(Value::as_str).map(str::to_owned).collect()
+}
+
+/// The toolbox's tools as the model sees them (`workflow.run` is `workflow_run`).
+fn toolbox_names(tools: &BTreeSet<String>) -> BTreeSet<String> {
+    let all: BTreeSet<String> = catalog().iter().map(|d| d["name"].as_str().unwrap().replace('.', "_")).collect();
+    tools.intersection(&all).cloned().collect()
+}
+
+#[test]
+fn a_real_peer_is_offered_exactly_its_granted_toolbox_tools_after_consent_and_a_real_turn_runs_them() {
+    let Some(program) = std::env::var_os("OCTOS_APP_PEERS_TEST_KERNEL").map(PathBuf::from) else {
+        eprintln!("OCTOS_APP_PEERS_TEST_KERNEL is not set: skipping the real-kernel toolbox test");
+        return;
+    };
+    let dir = std::env::temp_dir().join(format!("toolbox-real-kernel-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    std::fs::create_dir_all(&dir).unwrap();
+    let log = dir.join("offered.jsonl");
+    let script = Path::new(env!("CARGO_MANIFEST_DIR")).join("../app-peers/tests/fixtures/mock_agent_llm.py");
+    let mut child = std::process::Command::new("python3")
+        .arg(script)
+        .env("MOCK_LLM_TOOLS_LOG", &log)
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::inherit())
+        .spawn()
+        .expect("python3");
+    let mut line = String::new();
+    std::io::BufReader::new(child.stdout.take().unwrap()).read_line(&mut line).unwrap();
+    let port: u16 = line.trim().parse().unwrap();
+    let _model = Model(child);
+
+    let core_dir = dir.join("octos-home/.octos");
+    std::fs::create_dir_all(core_dir.join("profiles")).unwrap();
+    let profile = json!({
+        "id": "_main", "name": "Main", "enabled": true,
+        "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z",
+        "config": {"llm": {"primary": {"family_id": "local", "model_id": "mock-model",
+            "route": {"base_url": format!("http://127.0.0.1:{port}/v1"), "api_type": "openai"}}}}
+    });
+    std::fs::write(core_dir.join("profiles/_main.json"), profile.to_string()).unwrap();
+    let core = Core::new(Options::default().core_dir(&core_dir).program(&program));
+
+    let apps_root = dir.join("apps");
+    let case: FixtureCase = serde_json::from_str(
+        &std::fs::read_to_string(Path::new(env!("CARGO_MANIFEST_DIR")).join("../toolbox/templates/news-digest/fixtures/city-infrastructure.json")).unwrap(),
+    )
+    .unwrap();
+    let data = case.fixture.clone();
+    let executor = ToolboxExecutor::new(
+        &apps_root,
+        Arc::new(move || {
+            let backend = Arc::new(FixtureBackend::new(data.clone()));
+            Ok(PeerToolbox::from_host(Library::builtin().map_err(|e| e.to_string())?, fixture::host(&data), backend))
+        }),
+    );
+    // News declares research (and not crawl); research is granted.
+    executor.set_grant("os.news", ToolboxGrant::for_manifest("os.news", &json!({"id": "os.news", "capabilities": ["research"]})));
+    let host = Arc::new(Relay { executor, consent: AtomicBool::new(false), ran: Mutex::new(Vec::new()) });
+
+    let services: BTreeSet<String> = OCTOS_SERVICES.iter().map(|s| s.to_string()).collect();
+    let news = || {
+        let mut cfg = BrokerConfig::new(Deployment::Hosted, "_main", "_main:api:octosense#system", "os.news", "News", services.clone());
+        cfg.state_dir = Some(dir.join("host-state"));
+        cfg.tool_host = Some(ToolHostHandle(host.clone() as Arc<dyn ToolHost>));
+        let broker = Broker::new(cfg, Arc::new(CoreConnector::shared(core.clone())));
+        broker.set_account(Some("device"));
+        broker.bind().expect("the peer binds and its tools are registered");
+        broker
+    };
+    let turn = |broker: &Broker, instance: &str, text: String| -> String {
+        let ctx = broker.open_context(ContextSpec { account: "device".into(), instance: instance.into(), services: services.clone() }).unwrap();
+        let (tx, rx) = std::sync::mpsc::channel();
+        let tx = Mutex::new(tx);
+        ctx.call(
+            ContextOp::Turn { text },
+            Arc::new(move |e| {
+                let _ = tx.lock().unwrap().send(e);
+            }),
+        )
+        .unwrap();
+        loop {
+            match rx.recv_timeout(Duration::from_secs(90)).expect("the turn completes") {
+                ContextEvent::Complete(r) => return r.expect("the turn succeeds")["text"].as_str().unwrap_or_default().to_owned(),
+                ContextEvent::Data(_) => continue,
+            }
+        }
+    };
+
+    // Before the person allowed News's agent: no toolbox tool is offered,
+    // and none runs.
+    let before = news();
+    let said = turn(&before, "news#0", r#"CALL_TOOL:toolbox_search {"query": "city infrastructure"}"#.into());
+    assert!(said.starts_with("NO TOOL toolbox_search"), "{said}");
+    assert!(toolbox_names(&offered(&log, "CALL_TOOL:toolbox_search")).is_empty());
+    assert!(host.ran.lock().unwrap().is_empty());
+    before.release();
+    drop(before);
+
+    // Allowed: the next registration offers exactly the granted tools.
+    host.consent.store(true, Ordering::SeqCst);
+    let news = news();
+    let searched = turn(&news, "news#1", r#"CALL_TOOL:toolbox_search {"query": "city infrastructure", "lang": "en", "count": 2}"#.into());
+    assert!(searched.starts_with("TOOL SAID"), "{searched}");
+    assert!(searched.contains("Harbor City approves electric bus order"), "{searched}");
+    let tools = offered(&log, "CALL_TOOL:toolbox_search {\"query\": \"city infrastructure\", \"lang\"");
+    let expected: BTreeSet<String> = ["workflow_run", "workflow_fork", "toolbox_search", "toolbox_web_read"].iter().map(|s| s.to_string()).collect();
+    assert_eq!(toolbox_names(&tools), expected, "exactly the granted toolbox tools: {tools:?}");
+    // Registration is additive: the kernel's own tools stay (generic_tools
+    // omitted), and OctoSense holds none back, octos's deep_research
+    // included wherever the kernel offers it to a peer.
+    eprintln!("offered to the peer: {tools:?}");
+    assert!(tools.len() > expected.len(), "the peer keeps its kernel tools: {tools:?}");
+
+    let run = turn(&news, "news#2", format!("CALL_TOOL:workflow_run {}", json!({"id": "news-digest", "params": case.params, "run_id": "real-kernel"})));
+    assert!(run.starts_with("TOOL SAID") && run.contains("\"status\":\"ready\""), "{run}");
+    assert!(apps_root.join(".host/toolbox/os.news/toolbox/runs/news-digest/real-kernel.json").exists());
+
+    // Not granted crawl: not offered.
+    let crawl = turn(&news, "news#3", r#"CALL_TOOL:toolbox_deep_crawl {"url": "https://example.invalid/"}"#.into());
+    assert!(crawl.starts_with("NO TOOL toolbox_deep_crawl"), "{crawl}");
+    assert_eq!(*host.ran.lock().unwrap(), ["toolbox.search", "workflow.run"]);
+
+    news.release();
+    drop(news);
+    core.shutdown_within(Duration::from_secs(5));
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/crates/app-peers/tests/fixtures/mock_agent_llm.py b/crates/app-peers/tests/fixtures/mock_agent_llm.py
index 0e29801d..3bc6c9fe 100644
--- a/crates/app-peers/tests/fixtures/mock_agent_llm.py
+++ b/crates/app-peers/tests/fixtures/mock_agent_llm.py
@@ -3,8 +3,12 @@
 peer for the question/answer test. No network, no keys; standard library.
 
 Rules, looking at the request's messages and offered tools:
-  - after a tool result: finish with text ("PEER GOT <answer>" when the
-    result carries the system agent's answer, else "OK");
+  - after a tool result: finish with text ("TOOL SAID <result>" after a
+    CALL_TOOL, "PEER GOT <answer>" when the result carries the system agent's
+    answer, else "OK");
+  - "CALL_TOOL:<model name> <json args>": call that tool when it is offered
+    (a host-registered peer tool, UPCR-2026-035), else say "NO TOOL <name>
+    AMONG <offered tools>";
   - a user text "TELL_PEER:<slug>" with peer_send_input offered: send the peer
     "QUESTION_ME" ("TELL_PEER_HOLD:<slug>": "QUESTION_HOLD", never answered);
   - "TELL_PEER_AGAIN:<slug>": send the peer "SECOND_INPUT";
@@ -52,6 +56,8 @@ def decide(body):
     everything = "\n".join(text_of(m) for m in messages)
     if last.get("role") == "tool":
         result = text_of(last)
+        if "CALL_TOOL:" in everything:
+            return {"text": "TOOL SAID " + result}
         if "42" in result and "QUESTION_ME" in everything:
             return {"text": "PEER GOT 42"}
         return {"text": "OK"}
@@ -60,6 +66,11 @@ def decide(body):
         if m.get("role") == "user":
             last_user = text_of(m)
             break
+    host_tool = re.search(r"CALL_TOOL:([a-z0-9_]+) (\{.*\})", last_user)
+    if host_tool:
+        if host_tool.group(1) in tools:
+            return {"tool": host_tool.group(1), "args": json.loads(host_tool.group(2))}
+        return {"text": "NO TOOL " + host_tool.group(1) + " AMONG " + ",".join(sorted(t for t in tools if t))}
     again = re.search(r"TELL_PEER_AGAIN:([a-z0-9-]+)", last_user)
     if again and "peer_send_input" in tools:
         return {"tool": "peer_send_input", "args": {"slug": again.group(1), "message": "SECOND_INPUT"}}
diff --git a/crates/shell/Cargo.toml b/crates/shell/Cargo.toml
index 3dd22460..6c0db68b 100644
--- a/crates/shell/Cargo.toml
+++ b/crates/shell/Cargo.toml
@@ -107,3 +107,7 @@ app-aichat = ["dep:makepad-aichat"]
 # development builds without it (build.rs); a release build without it
 # honours only the `--dev-grant-all` launch flag.
 dev-mode = []
+# The system toolbox offered to app agents as host-routed tools (ADR 0002
+# §6, ADR 0004 §12; src/host_tools/toolbox.rs): the `toolbox` owner in the
+# host-tool relay. Off by default.
+toolbox-peers = ["octosense-ai-host/toolbox-peers"]
diff --git a/crates/shell/src/host_tools/mod.rs b/crates/shell/src/host_tools/mod.rs
index 3ee616c5..24933d80 100644
--- a/crates/shell/src/host_tools/mod.rs
+++ b/crates/shell/src/host_tools/mod.rs
@@ -10,6 +10,7 @@
 //! | `approval/requested` `host_tool` | the approval router ([`crate::approvals::approval_requested`]); its decision answers the kernel |
 //! | `peer/input` | admitted here (consent, a suspended account); the broker starts the turn |
 //! | the system session's `terminal.run` (Setup › Assistant › Command execution) | [`crate::system_chat`] registers it; its calls come here |
+//! | the system toolbox's tools (feature `toolbox-peers`) | the `toolbox` owner: its tools declared once, granted per app, offered after consent, run by its executor ([`toolbox`]) |
 //!
 //! **Threads.** Brokers call in on their own threads and the system chat on
 //! its own; every call, cancel and approval is queued and handled on the UI
@@ -29,6 +30,8 @@
 //! router here ([`SheetBridge`]).
 
 pub mod relay;
+#[cfg(feature = "toolbox-peers")]
+pub mod toolbox;
 
 #[cfg(test)]
 mod tests;
@@ -42,7 +45,7 @@ use serde_json::Value;
 use crate::ai_host::app_peers::host_tools::{self, ApprovalAnswer, ConfirmRequest, ConfirmSheet, HostToolApproval, HostToolCall, PeerInput, ToolExecutor, ToolHost, ToolOutcome, ToolReply};
 use crate::approvals::{self, Caller, Decision, RequestContext, RequestId, Route, ToolSpec};
 use crate::peer_link::{self, KernelToolCall, Refused, ToolCallResult};
-pub use relay::{app_of_peer, Event, Relay, APPROVAL_PREFIX, BUS_PREFIX, CONFIRM_PREFIX, SYSTEM, TERMINAL_RUN};
+pub use relay::{app_of_peer, Event, Relay, APPROVAL_PREFIX, BUS_PREFIX, CONFIRM_PREFIX, SYSTEM, TERMINAL_RUN, TOOLBOX};
 
 static RELAY: Mutex<Option<Relay>> = Mutex::new(None);
 static INBOX: Mutex<Vec<Event>> = Mutex::new(Vec::new());
@@ -82,6 +85,8 @@ pub fn init() {
         host_tools::set_host(Arc::new(ShellToolHost));
         approvals::set_relay(Box::new(DecisionRelay));
         peer_link::set_tool_relay(Box::new(LinkRelay));
+        #[cfg(feature = "toolbox-peers")]
+        toolbox::init();
     });
 }
 
@@ -144,7 +149,10 @@ impl ToolHost for ShellToolHost {
     fn declarations(&self, app_id: &str, _account: &str) -> Result<Vec<Value>, String> {
         let app = app_of_peer(app_id).to_string();
         let dev = crate::dev_mode::grants_all(&app);
-        Ok(with_relay(|r| r.catalog.declarations(&app, dev)))
+        // The toolbox's tools only once the person allowed this app's agent
+        // (ADR 0004 §4); its calls are refused before that too (the relay).
+        let consented = approvals::consent_granted(&app) || dev;
+        Ok(with_relay(|r| r.catalog.offered(&app, dev, consented)))
     }
 
     fn agent_workspace(&self, app_id: &str, account: &str) -> Option<PathBuf> {
diff --git a/crates/shell/src/host_tools/relay.rs b/crates/shell/src/host_tools/relay.rs
index aba89c05..723496c8 100644
--- a/crates/shell/src/host_tools/relay.rs
+++ b/crates/shell/src/host_tools/relay.rs
@@ -43,6 +43,10 @@ pub const SYSTEM: &str = "system";
 pub const TERMINAL_RUN: &str = "terminal.run";
 /// Developer mode's command tool (§13).
 pub const DEV_RUN: &str = "dev.run";
+/// The system toolbox (ADR 0002 §6), the owning app of the toolbox tools
+/// (`workflow.run`, `toolbox.search`, …; [`super::toolbox`] with the
+/// `toolbox-peers` feature).
+pub const TOOLBOX: &str = "toolbox";
 
 /// A script app's peer is `card.<app id>`; its tools are `<app id>.*`.
 pub fn app_of_peer(app: &str) -> &str {
@@ -113,18 +117,29 @@ impl Catalog {
     pub fn grant(&mut self, caller: &str, tool: &str) {
         self.grants.entry(caller.to_string()).or_default().insert(tool.to_string());
     }
+    /// `caller`'s grants of `owner`'s tools become exactly `tools` (a
+    /// toolbox grant computed again).
+    pub fn set_grants(&mut self, caller: &str, owner: &str, tools: &[&str]) {
+        let owned: BTreeSet<String> = self.tools.get(owner).into_iter().flatten().filter_map(|e| e["name"].as_str().map(str::to_string)).collect();
+        let grants = self.grants.entry(caller.to_string()).or_default();
+        grants.retain(|t| !owned.contains(t));
+        grants.extend(tools.iter().map(|t| t.to_string()));
+    }
     pub fn entry(&self, owner: &str, tool: &str) -> Option<&Value> {
         self.tools.get(owner)?.iter().find(|e| e["name"] == tool)
     }
     fn shareable(entry: &Value) -> bool {
         entry["shareable"] == true
     }
-    /// Whether `caller`'s agent may call `owner`'s `tool`.
+    /// Whether `caller`'s agent may call `owner`'s `tool`. Developer mode
+    /// grants every shareable tool, except the toolbox's: those run under
+    /// the grant's scope, which developer mode cannot invent.
     pub fn may_call(&self, caller: &str, owner: &str, tool: &str, dev_all: bool) -> bool {
         let Some(entry) = self.entry(owner, tool) else { return false };
         if owner == caller {
             return true;
         }
+        let dev_all = dev_all && owner != TOOLBOX;
         Self::shareable(entry) && (dev_all || self.grants.get(caller).is_some_and(|g| g.contains(tool)))
     }
     /// What `app`'s peer registers: its own tools, and the shareable tools of
@@ -144,6 +159,16 @@ impl Catalog {
         }
         out
     }
+    /// What `app`'s peer is offered now: [`Catalog::declarations`], without
+    /// the toolbox's tools until the person allowed `app`'s agent (the #120
+    /// first-use consent; `consented`).
+    pub fn offered(&self, app: &str, dev_all: bool, consented: bool) -> Vec<Value> {
+        let mut out = self.declarations(app, dev_all);
+        if !consented {
+            out.retain(|d| d["app"] != TOOLBOX);
+        }
+        out
+    }
 }
 
 /// `terminal.run` as the Terminal declares it for the host: destructive, the
diff --git a/crates/shell/src/host_tools/tests.rs b/crates/shell/src/host_tools/tests.rs
index 32cd2cf3..6cdc3ef5 100644
--- a/crates/shell/src/host_tools/tests.rs
+++ b/crates/shell/src/host_tools/tests.rs
@@ -377,3 +377,86 @@ fn the_shipped_catalog_offers_the_terminals_run_to_those_granted_it() {
     assert!(catalog.declarations("rinx", false).is_empty(), "nobody gets it without a grant");
     assert_eq!(catalog.declarations("rinx", true).len(), 1, "developer mode grants every shareable tool");
 }
+
+/// The system toolbox's tools as its catalog declares them (the real ones
+/// with the `toolbox-peers` feature): owned by `toolbox`, shareable, read
+/// except `workflow.fork`.
+fn toolbox_catalog() -> Vec<Value> {
+    #[cfg(feature = "toolbox-peers")]
+    return crate::ai_host::toolbox_peers::catalog();
+    #[cfg(not(feature = "toolbox-peers"))]
+    ["workflow.run", "workflow.fork", "toolbox.search", "toolbox.web_read", "toolbox.deep_crawl"]
+        .iter()
+        .map(|name| {
+            let risk = if *name == "workflow.fork" { "act" } else { "read" };
+            json!({"name": name, "app": super::TOOLBOX, "description": "d", "input_schema": {"type": "object"}, "risk": risk, "background": true, "outward": false, "confirm": "host", "shareable": true})
+        })
+        .collect()
+}
+
+fn offered_names(relay: &Relay, app: &str, dev: bool, consented: bool) -> Vec<String> {
+    let mut names: Vec<String> = relay.catalog.offered(app, dev, consented).iter().map(|d| d["name"].as_str().unwrap().to_string()).collect();
+    names.sort();
+    names
+}
+
+#[test]
+fn a_peer_is_offered_exactly_its_granted_toolbox_tools_marked_with_their_owner_and_only_after_consent() {
+    let (mut relay, _) = relay_with(super::TOOLBOX, toolbox_catalog());
+    relay.catalog.declare("os.news", vec![decl("news.item.save", false, "host")]);
+    // `research` granted: its four tools; `crawl` not granted: no deep_crawl.
+    relay.catalog.set_grants("os.news", super::TOOLBOX, &["workflow.run", "workflow.fork", "toolbox.search", "toolbox.web_read"]);
+    // Before the person allowed News's agent: its own tools, no toolbox tool.
+    assert_eq!(offered_names(&relay, "os.news", false, false), ["news.item.save"]);
+    // After: exactly the granted ones, each marked with its owning app.
+    assert_eq!(offered_names(&relay, "os.news", false, true), ["news.item.save", "toolbox.search", "toolbox.web_read", "workflow.fork", "workflow.run"]);
+    for d in relay.catalog.offered("os.news", false, true).iter().filter(|d| d["name"] != "news.item.save") {
+        assert_eq!(d["app"], super::TOOLBOX, "{d}");
+        assert_eq!(d["risk"], if d["name"] == "workflow.fork" { "act" } else { "read" }, "{d}");
+    }
+    // A grant computed again (crawl now granted) replaces the old one.
+    relay.catalog.set_grants("os.news", super::TOOLBOX, &["toolbox.deep_crawl"]);
+    assert_eq!(offered_names(&relay, "os.news", false, true), ["news.item.save", "toolbox.deep_crawl"]);
+    // No grant, no toolbox tools; developer mode does not invent a grant
+    // (the toolbox needs its scope), though it grants other shareable tools.
+    assert!(offered_names(&relay, "calendar", false, true).is_empty());
+    assert_eq!(offered_names(&relay, "calendar", true, true), [TERMINAL_RUN]);
+}
+
+#[test]
+fn no_toolbox_call_runs_before_consent_or_without_a_grant() {
+    let (mut relay, exec) = relay_with(super::TOOLBOX, toolbox_catalog());
+    relay.catalog.set_grants("os.news", super::TOOLBOX, &["toolbox.search"]);
+    let mut w = World::new(FixedDevMode::off());
+    let toolbox_call = |id: &str, name: &str, calling: &str| {
+        let mut c = call(id, name, calling);
+        c.app = super::TOOLBOX.into();
+        c.risk = "read".into();
+        c
+    };
+    w.consent = false;
+    let (r, sent) = reply("c1");
+    relay.handle(Event::Call { call: toolbox_call("c1", "toolbox.search", "os.news"), reply: r }, &mut w);
+    assert_eq!(sent.lock().unwrap()[0]["error"]["kind"], "consent_pending");
+    assert!(exec.0.lock().unwrap().is_empty(), "nothing ran before consent");
+    w.consent = true;
+    // Not granted (a forged call): refused before the toolbox sees it.
+    let (r, sent) = reply("c2");
+    relay.handle(Event::Call { call: toolbox_call("c2", "toolbox.deep_crawl", "os.news"), reply: r }, &mut w);
+    assert_eq!(sent.lock().unwrap()[0]["error"]["kind"], "not_granted");
+    w.dev_all = true;
+    let (r, sent) = reply("c3");
+    relay.handle(Event::Call { call: toolbox_call("c3", "toolbox.search", "calendar"), reply: r }, &mut w);
+    assert_eq!(sent.lock().unwrap()[0]["error"]["kind"], "not_granted", "developer mode grants no toolbox scope");
+    w.dev_all = false;
+    assert!(exec.0.lock().unwrap().is_empty());
+    // Consented and granted: routed to the toolbox's executor, once.
+    let (r, _) = reply("c4");
+    relay.handle(Event::Call { call: toolbox_call("c4", "toolbox.search", "os.news"), reply: r }, &mut w);
+    let calls = exec.0.lock().unwrap().clone();
+    assert_eq!(calls.len(), 1);
+    assert_eq!((calls[0].0.name.as_str(), calls[0].0.calling_app.as_str()), ("toolbox.search", "os.news"));
+    // A cancel reaches the toolbox.
+    relay.handle(Event::Cancel { call_id: "c4".into(), reason: "timeout".into() }, &mut w);
+    assert_eq!(*exec.1.lock().unwrap(), ["c4"]);
+}
diff --git a/crates/shell/src/host_tools/toolbox.rs b/crates/shell/src/host_tools/toolbox.rs
new file mode 100644
index 00000000..5670362d
--- /dev/null
+++ b/crates/shell/src/host_tools/toolbox.rs
@@ -0,0 +1,70 @@
+//! The system toolbox as an owner of host-routed tools (ADR 0002 §6, ADR
+//! 0004 §12; feature `toolbox-peers`).
+//!
+//! The toolbox is one more owning app in the relay, [`super::TOOLBOX`]:
+//!
+//! - its tools are declared once in the catalog
+//!   (`octosense_ai_host::toolbox_peers::catalog`: `workflow.run`,
+//!   `workflow.fork`, `toolbox.search`, `toolbox.web_read`,
+//!   `toolbox.deep_crawl`, each `app: "toolbox"` and `shareable`);
+//! - each app is granted exactly the ones it declares AND the person
+//!   granted ([`grant_module`], [`grant_manifest`]), so the broker's
+//!   registration (after every prepare and reconnect) carries them, marked
+//!   with their owner;
+//! - they are offered only once the person allowed the app's agent (the
+//!   #120 first-use consent, `Catalog::offered`), and the relay refuses a
+//!   call before that (`consent_pending`), as for every host tool;
+//! - calls reach the toolbox's executor (`ToolboxExecutor`) through the
+//!   relay like any in-process app's, which runs them with the calling
+//!   app's grant and scope and answers once.
+
+use std::sync::OnceLock;
+
+use serde_json::Value;
+
+use crate::ai_host::toolbox_peers::{self, ToolboxExecutor, ToolboxGrant};
+
+static EXECUTOR: OnceLock<ToolboxExecutor> = OnceLock::new();
+
+/// Where toolbox results live: the host's apps root (`<apps root>/.host/
+/// toolbox/<app>`), outside every app's jail.
+fn apps_root() -> std::path::PathBuf {
+    crate::app_storage::host()
+        .map(|s| s.layout().apps_root().to_path_buf())
+        .unwrap_or_else(|| crate::octosense::paths::home().join("apps"))
+}
+
+/// With the relay's `init`: declare the toolbox's tools and install its
+/// executor as the `toolbox` owner's.
+pub fn init() {
+    let executor = EXECUTOR.get_or_init(|| ToolboxExecutor::shell(&apps_root())).clone();
+    super::with_relay(|r| {
+        r.catalog.declare(super::TOOLBOX, toolbox_peers::catalog());
+        r.set_executor(super::TOOLBOX, Some(std::sync::Arc::new(executor)));
+    });
+}
+
+/// `app`'s toolbox grant becomes `grant`: the catalog grants it exactly
+/// those tools, and the executor runs them with its scope.
+pub fn set_grant(app: &str, grant: ToolboxGrant) {
+    for note in &grant.notes {
+        makepad_widgets::log!("toolbox: {note}");
+    }
+    let tools: Vec<&str> = match EXECUTOR.get() {
+        Some(executor) => executor.set_grant(app, grant).into_iter().collect(),
+        None => Vec::new(),
+    };
+    super::with_relay(|r| r.catalog.set_grants(app, super::TOOLBOX, &tools));
+}
+
+/// A native module's grant, from the capabilities it declares (reviewed
+/// with the shell), before its instance is offered the assistant.
+pub fn grant_module(app: &str, capabilities: &[&str]) {
+    set_grant(app, ToolboxGrant::for_module(app, capabilities));
+}
+
+/// A script app's grant from its manifest (App Hub #26's shape; system
+/// apps only until the shells' App Hub pin verifies it).
+pub fn grant_manifest(app: &str, manifest: &Value) {
+    set_grant(app, ToolboxGrant::for_manifest(app, manifest));
+}
diff --git a/crates/shell/src/module_host.rs b/crates/shell/src/module_host.rs
index b4ebbca4..774f9326 100644
--- a/crates/shell/src/module_host.rs
+++ b/crates/shell/src/module_host.rs
@@ -361,6 +361,10 @@ impl ModuleHost {
         // create only; the module takes it there or never gets it.
         // In developer mode a covered module gets every service it declares
         // (dev_mode.rs); the grant lives and dies with this instance.
+        // The system toolbox's tools it declares (the broker registers them
+        // once the person allowed its agent).
+        #[cfg(feature = "toolbox-peers")]
+        crate::host_tools::toolbox::grant_module(module.id(), module.capabilities());
         let offer = crate::ai_host::offer_with(module, &scope, crate::dev_mode::grants_all(module.id()));
         // Consent at first use (ADR 0004 §4, approvals/consent.rs): a module
         // the person has not allowed an agent is not offered one. The first
diff --git a/crates/toolbox/README.md b/crates/toolbox/README.md
index 2eae14cc..523e8aeb 100644
--- a/crates/toolbox/README.md
+++ b/crates/toolbox/README.md
@@ -231,6 +231,8 @@ The tests show this rule deciding real cases:
 
 `handle_json(app, {"tool": "workflow.run", "arguments": {…}})` routes the same calls as JSON and returns errors as `{"error": {kind, message}}`. `api::tool_descriptors()` gives the four tools' names, risk and input schemas for registration with a peer. The risk levels are the ones octos#2567 and App Hub's `tools.json` accept: `workflow.list`, `workflow.run` and `workflow.evaluate` are `read`, and `workflow.fork` is `act` (it writes only into the calling app's folder). The descriptors carry no `confirm` field.
 
+`peer` is what an app's peer is offered (octos#2567, ADR 0004 §12). `peer::catalog(library)` gives every toolbox tool's `tools.json` entry, each marked with its owning app (`app: "toolbox"`), `shareable`, `background`, not `outward`, `confirm: host`: the shell's host-tool relay declares them and grants each app exactly what it declares and the person granted. `peer::tool_decls(app, library)` is that catalog narrowed to the app's grants (`research`: `workflow.run`, `workflow.fork`, `toolbox.search`, `toolbox.web_read`; `crawl` with crawl limits in the scope: `toolbox.deep_crawl`). Nothing else is held back: octos's own generic tools, `deep_research` among them, are the kernel's. `peer::PeerToolbox::call(app, name, args)` checks the name against the grants again (`not_granted` otherwise) and runs it: the two workflow tools through `handle_json` (the agent gets the data, sources and the result's path; the trace stays in the file), the single tools on the same `ResearchBackend` as `mod.research`, narrowed by the scope (`scope::narrow_search`, `check_domain`, `scope::narrow_crawl`), with their items saved under `research/` in the app's folder. `toolbox.deep_crawl` reads pages with `ResearchBackend::read_links` (the octos engine keeps each page's HTML for its links) and stays on the start's site, under `path_prefix`, inside the domains and within `max_depth` and `max_pages`.
+
 ## How an app agent will use it
 
 This flow needs the wiring in [What remains](#what-remains):
@@ -369,7 +371,7 @@ After the [status rules](#status) and the [summary check](#modresearch-v1): four
 
 ## What remains
 
-- **Peer tool wiring**, after octos#2567 (host-registered peer tools): register `tool_descriptors()` for granted peers in `crates/ai-host`, route each call to `Toolbox::handle_json` with the peer's `AppContext`, and supply the real `ModelClient` from the person's providers.
+- **Peer tool wiring** is in place behind the shell's `toolbox-peers` feature (`crates/ai-host`'s `toolbox_peers`, the shell's `host_tools::toolbox`, and the `peer` module here: the tools per grant, `PeerToolbox::call`, and `toolbox.deep_crawl` over `ResearchBackend::read_links`). Script apps' grants wait for the shells' App Hub pin to include App Hub #26 (`research`/`crawl`).
 - **Engine**: the octos research engine is behind `ResearchBackend` (`octos-engine`). Still to do:
   - drop the interim adapter once the shells use it;
   - add metasearch (octos#2582) and publisher feeds (octos#2585);
diff --git a/crates/toolbox/src/lib.rs b/crates/toolbox/src/lib.rs
index 29a0260d..f0530680 100644
--- a/crates/toolbox/src/lib.rs
+++ b/crates/toolbox/src/lib.rs
@@ -33,6 +33,7 @@ pub mod json;
 pub mod library;
 pub mod manifest;
 pub mod modules;
+pub mod peer;
 pub mod research;
 pub mod runner;
 pub mod scope;
diff --git a/crates/toolbox/src/peer.rs b/crates/toolbox/src/peer.rs
new file mode 100644
index 00000000..76120646
--- /dev/null
+++ b/crates/toolbox/src/peer.rs
@@ -0,0 +1,722 @@
+//! The toolbox as app peers' host-routed tools (ADR 0002 section 6, ADR
+//! 0004 section 12; octos UPCR-2026-035, octos#2567).
+//!
+//! The kernel offers an app's peer the tools its host registers and sends
+//! every call back to the host. The shell's broker registers them and its
+//! host-tool relay routes the calls (`crates/app-peers`,
+//! `crates/shell/src/host_tools`); this module is what the toolbox adds to
+//! that: the tools, marked with their owning app [`OWNER`], and how one call
+//! runs.
+//!
+//! - [`catalog`]: every toolbox tool, as the relay's catalog declares it
+//!   (`app: "toolbox"`, `shareable`, so an app's peer gets exactly the ones
+//!   granted to it).
+//! - [`tool_decls`]: the ones an app is offered: **exactly what it declares
+//!   and the person granted** ([`AppContext::grants`] holds that
+//!   intersection). `research` gives `workflow.run` and `workflow.fork`
+//!   (the template library, [`crate::api`]), `toolbox.search` and
+//!   `toolbox.web_read`; `crawl` gives `toolbox.deep_crawl` while the
+//!   scope's crawl limits are not 0 (0 means crawling is not granted). No
+//!   grant, no tools. Nothing else is excluded here: octos's generic tools
+//!   (`deep_research` among them) are the kernel's and are not filtered by
+//!   the toolbox.
+//! - [`PeerToolbox::call`]: one call, checked **again** against the grants
+//!   (a call the registration did not offer is refused as `not_granted`,
+//!   whatever the kernel sent) and run with the app's [`AppContext`]: its
+//!   id, grants, octos `Scope`, budget and folder.
+//!
+//! Tool names are `<segment>.<tool>` for octos (2-4 `.`-separated segments);
+//! the owning app is `app: "toolbox"` on every declaration, so the kernel
+//! and the host both see the toolbox as the owner. The model sees
+//! `workflow_run`, `toolbox_search`, ...
+//!
+//! **Risk**: `read` for everything except `workflow.fork` (`act`: it writes a
+//! copy into the app's own toolbox folder). None is `outward` or
+//! `destructive`, so the kernel never gates them and `confirm` (`host`, the
+//! default: the host runs them, the app has no sheet for them) never comes
+//! into play. All are `background`: an app's agent runs them on its own
+//! triggers (News M3), with nobody present.
+//!
+//! **Results** go where the app cannot write: the app's toolbox folder is
+//! the host's (`<apps root>/.host/toolbox/<app>`, chosen by the caller), so
+//! run results (`toolbox/runs/<template>/<run>.json`, read by the glance
+//! screen's `sys.digest`) and research items (`research/*.json`) cannot be
+//! forged by the app. Each reply carries the file's path relative to that
+//! folder and a compact summary for the agent.
+
+use crate::api::Toolbox;
+use crate::host::{url_host, AppContext, CallContext, HostError, Remaining};
+use crate::library::{hex, Library};
+use crate::manifest::Budget;
+use crate::research::{
+    cap_evidence, item_id, FoundItem, ModelClient, ResearchBackend, ResearchHost, SearchQuery,
+    MAX_EVIDENCE_BYTES, MAX_EXCERPT_BYTES, MAX_SEARCH_FETCHES,
+};
+use crate::scope;
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::collections::{BTreeSet, VecDeque};
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+/// The owning app of every toolbox tool (`app` on its declaration).
+pub const OWNER: &str = "toolbox";
+
+/// The capability that grants the research tools and the templates.
+pub const RESEARCH: &str = "research";
+/// The capability that grants `toolbox.deep_crawl`.
+pub const CRAWL: &str = "crawl";
+
+pub const RUN: &str = "workflow.run";
+pub const FORK: &str = "workflow.fork";
+pub const SEARCH: &str = "toolbox.search";
+pub const WEB_READ: &str = "toolbox.web_read";
+pub const DEEP_CRAWL: &str = "toolbox.deep_crawl";
+
+/// Results one `toolbox.search` returns when the call asks for no count.
+pub const DEFAULT_SEARCH_COUNT: u32 = 10;
+/// Page text one `toolbox.web_read` returns to the agent (the whole text is
+/// in the saved file).
+pub const WEB_READ_TEXT_MAX: usize = 16 * 1024;
+/// Links queued per crawl page at most, and the whole frontier.
+const CRAWL_LINKS_PER_PAGE: usize = 200;
+const CRAWL_FRONTIER_MAX: usize = 2000;
+/// How long one single research call may take (a run's own `max_ms` bounds
+/// the templates).
+const TOOL_MS: u64 = 120_000;
+
+/// Whether the app's scope lets it crawl at all.
+pub fn crawl_allowed(app: &AppContext) -> bool {
+    app.grants.contains(CRAWL) && app.scope.max_depth > 0 && app.scope.max_pages > 0
+}
+
+/// Every toolbox tool, in registration order.
+pub const TOOLS: [&str; 5] = [RUN, FORK, SEARCH, WEB_READ, DEEP_CRAWL];
+
+/// The tool names an app with these grants is offered.
+pub fn tool_names(app: &AppContext) -> BTreeSet<&'static str> {
+    let mut names = BTreeSet::new();
+    if app.grants.contains(RESEARCH) {
+        names.extend([RUN, FORK, SEARCH, WEB_READ]);
+    }
+    if crawl_allowed(app) {
+        names.insert(DEEP_CRAWL);
+    }
+    names
+}
+
+/// The `tools.json` entries (octos `peer/tools/register` `tools`) of an app
+/// with these grants, in a fixed order: [`catalog`] narrowed to
+/// [`tool_names`]. Empty without a grant.
+pub fn tool_decls(app: &AppContext, library: &Library) -> Vec<Value> {
+    let names = tool_names(app);
+    catalog(library)
+        .into_iter()
+        .filter(|d| d["name"].as_str().is_some_and(|n| names.contains(n)))
+        .collect()
+}
+
+/// Every toolbox tool's declaration, owned by [`OWNER`] and `shareable`
+/// (the host grants each to the apps whose grants allow it).
+pub fn catalog(library: &Library) -> Vec<Value> {
+    let mut decls = Vec::new();
+    let decl = |name: &str, risk: &str, description: String, input_schema: Value| {
+        json!({
+            "name": name,
+            "app": OWNER,
+            "description": description,
+            "input_schema": input_schema,
+            "risk": risk,
+            "background": true,
+            "outward": false,
+            "confirm": "host",
+            "shareable": true,
+        })
+    };
+    let workflow = crate::api::tool_descriptors();
+    let schema_of = |name: &str| {
+        workflow
+            .as_array()
+            .and_then(|tools| tools.iter().find(|t| t["name"] == name))
+            .map(|t| t["input_schema"].clone())
+            .unwrap_or_else(|| json!({"type": "object"}))
+    };
+    {
+        let mut listed = String::new();
+        for t in library.templates() {
+            let line = format!("{} ({}); ", t.manifest.id, t.manifest.title);
+            if listed.len() + line.len() > 1200 {
+                break;
+            }
+            listed.push_str(&line);
+        }
+        decls.push(decl(
+            RUN,
+            "read",
+            format!(
+                "Run a toolbox workflow template with parameters (each template's `params` schema is in its manifest). \
+                 The result, with its sources, is saved in this app's toolbox folder and summarized here. \
+                 Templates: {}or a fork of one made with workflow.fork.",
+                listed
+            ),
+            schema_of(RUN),
+        ));
+    }
+    {
+        decls.push(decl(
+            FORK,
+            "act",
+            "Copy a library template into this app's toolbox folder to change it; the copy keeps lineage to its parent and never gains more than it had.".into(),
+            schema_of(FORK),
+        ));
+    }
+    {
+        decls.push(decl(
+            SEARCH,
+            "read",
+            "Search free news sources (Google News, GDELT, publisher feeds) within this app's granted languages, regions, domains and recency; returns dated items with their sources, saved in this app's toolbox folder.".into(),
+            json!({
+                "type": "object", "required": ["query"], "additionalProperties": false,
+                "properties": {
+                    "query": {"type": "string", "minLength": 1, "maxLength": 300},
+                    "lang": {"type": "string", "description": "BCP-47 language to search in (must be granted to the app)"},
+                    "region": {"type": "string", "description": "ISO 3166-1 alpha-2 region"},
+                    "max_age_days": {"type": "integer", "minimum": 1, "description": "only material this recent"},
+                    "count": {"type": "integer", "minimum": 1, "maximum": 30}
+                }
+            }),
+        ));
+    }
+    {
+        decls.push(decl(
+            WEB_READ,
+            "read",
+            "Read one page (rendered by a real browser when needed) inside this app's granted domains and return its main text; the page is saved in this app's toolbox folder.".into(),
+            json!({
+                "type": "object", "required": ["url"], "additionalProperties": false,
+                "properties": {"url": {"type": "string", "minLength": 1, "maxLength": 2048}}
+            }),
+        ));
+    }
+    {
+        decls.push(decl(
+            DEEP_CRAWL,
+            "read",
+            "Crawl one site within this app's granted limits (same site, at most the granted link hops and pages, optionally under a path prefix); the pages are saved in this app's toolbox folder.".into(),
+            json!({
+                "type": "object", "required": ["url"], "additionalProperties": false,
+                "properties": {
+                    "url": {"type": "string", "minLength": 1, "maxLength": 2048},
+                    "max_depth": {"type": "integer", "minimum": 1},
+                    "max_pages": {"type": "integer", "minimum": 1},
+                    "path_prefix": {"type": "string"}
+                }
+            }),
+        ));
+    }
+    decls
+}
+
+/// A refused or failed call: `kind` is `[a-z0-9_]{1,32}` (octos passes it to
+/// the model as `host:<kind>`).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PeerError {
+    pub kind: String,
+    pub message: String,
+}
+
+impl PeerError {
+    pub fn new(kind: &str, message: impl Into<String>) -> Self {
+        Self {
+            kind: kind.to_owned(),
+            message: message.into(),
+        }
+    }
+}
+
+impl std::fmt::Display for PeerError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}: {}", self.kind, self.message)
+    }
+}
+
+fn host_error(e: HostError) -> PeerError {
+    match e {
+        HostError::Denied(m) => PeerError::new("denied", m),
+        HostError::Failed(m) => PeerError::new("failed", m),
+        HostError::TimedOut(m) => PeerError::new("timeout", m),
+    }
+}
+
+/// The toolbox one host runs for app peers: the template library over
+/// `mod.research`, and the same research backend for the single tools.
+pub struct PeerToolbox {
+    toolbox: Toolbox<ResearchHost>,
+    backend: Arc<dyn ResearchBackend>,
+    clock: Arc<dyn Fn() -> chrono::DateTime<chrono::Utc>>,
+}
+
+impl PeerToolbox {
+    /// The toolbox over `backend` (the octos research engine in a shell) with
+    /// `model` for the templates' model calls (the person's providers).
+    pub fn new(
+        library: Library,
+        backend: Arc<dyn ResearchBackend>,
+        model: Arc<dyn ModelClient>,
+    ) -> Self {
+        let host = ResearchHost::new(backend.clone(), model);
+        Self::from_host(library, host, backend)
+    }
+
+    /// The toolbox over an already built `mod.research` host (fixtures set
+    /// its clock); `backend` must be the one `host` uses.
+    pub fn from_host(
+        library: Library,
+        host: ResearchHost,
+        backend: Arc<dyn ResearchBackend>,
+    ) -> Self {
+        Self {
+            toolbox: Toolbox::new(library, host),
+            backend,
+            clock: Arc::new(chrono::Utc::now),
+        }
+    }
+
+    /// Replaces the clock of saved research items (tests).
+    pub fn with_clock(
+        mut self,
+        clock: impl Fn() -> chrono::DateTime<chrono::Utc> + 'static,
+    ) -> Self {
+        self.clock = Arc::new(clock);
+        self
+    }
+
+    pub fn library(&self) -> &Library {
+        self.toolbox.library()
+    }
+
+    /// The app's `tools.json` entries ([`tool_decls`]).
+    pub fn decls(&self, app: &AppContext) -> Vec<Value> {
+        tool_decls(app, self.library())
+    }
+
+    /// Runs one peer tool call for `app`. The call is checked against the
+    /// app's grants again: a tool it was not offered is `not_granted`.
+    pub async fn call(
+        &self,
+        app: &AppContext,
+        name: &str,
+        args: Value,
+    ) -> Result<Value, PeerError> {
+        if !tool_names(app).contains(name) {
+            return Err(PeerError::new(
+                "not_granted",
+                format!("{name} is not among this app's toolbox tools"),
+            ));
+        }
+        if !args.is_object() {
+            return Err(PeerError::new("bad_request", "arguments must be an object"));
+        }
+        match name {
+            RUN | FORK => self.workflow(app, name, args).await,
+            SEARCH => self.search(app, &args).await,
+            WEB_READ => self.web_read(app, &args).await,
+            DEEP_CRAWL => self.deep_crawl(app, &args).await,
+            _ => Err(PeerError::new(
+                "not_granted",
+                format!("no toolbox tool {name}"),
+            )),
+        }
+    }
+
+    async fn workflow(
+        &self,
+        app: &AppContext,
+        name: &str,
+        args: Value,
+    ) -> Result<Value, PeerError> {
+        let reply = self
+            .toolbox
+            .handle_json(app, json!({"tool": name, "arguments": args}))
+            .await;
+        if let Some(error) = reply.get("error") {
+            let kind = error["kind"].as_str().unwrap_or("failed");
+            return Err(PeerError::new(
+                kind,
+                error["message"]
+                    .as_str()
+                    .unwrap_or("the toolbox refused the call"),
+            ));
+        }
+        if name == FORK {
+            return Ok(json!({
+                "id": reply["template"]["id"],
+                "version": reply["template"]["version"],
+                "lineage": reply["template"]["lineage"],
+                "path": reply["path"],
+            }));
+        }
+        // The agent gets the data and where the full result is; the trace,
+        // diagnostics and evidence stay in the file.
+        let sources: Vec<Value> = reply["provenance"]
+            .as_array()
+            .map(|p| {
+                p.iter()
+                    .map(|s| {
+                        json!({"id": s["id"], "url": s["url"], "title": s["title"],
+                               "source": s["source"], "published_at": s["published_at"]})
+                    })
+                    .collect()
+            })
+            .unwrap_or_default();
+        Ok(json!({
+            "run_id": reply["run_id"],
+            "template": reply["template"],
+            "status": reply["status"],
+            "status_reasons": reply["status_reasons"],
+            "data": reply["data"],
+            "sources": sources,
+            "stats": reply["stats"],
+            "result": reply["result_path"],
+        }))
+    }
+
+    fn context(&self, app: &AppContext, tool: &str, reads: u32) -> CallContext {
+        CallContext {
+            app: Arc::new(app.clone()),
+            run_id: format!("{tool}-{}", (self.clock)().format("%Y%m%dT%H%M%S%3fZ")),
+            template_id: tool.to_owned(),
+            template_digest: String::new(),
+            budget: Budget {
+                max_calls: reads.max(1),
+                max_model_calls: 0,
+                max_reads: reads,
+                max_ms: TOOL_MS,
+                max_concurrency: 1,
+            },
+            remaining: Remaining {
+                calls: reads.max(1),
+                model_calls: 0,
+                reads,
+                ms: TOOL_MS,
+            },
+            call_index: 0,
+        }
+    }
+
+    async fn search(&self, app: &AppContext, args: &Value) -> Result<Value, PeerError> {
+        let query = args["query"].as_str().unwrap_or("").trim();
+        let lang = args["lang"].as_str();
+        let region = args["region"].as_str();
+        let max_age_hours = args["max_age_days"]
+            .as_u64()
+            .map(|d| d.min(3650) as u32 * 24);
+        let count = args["count"]
+            .as_u64()
+            .map_or(DEFAULT_SEARCH_COUNT, |c| c.clamp(1, 30) as u32);
+        let narrowed = scope::narrow_search(&app.scope, query, lang, region, max_age_hours, count)
+            .map_err(|e| PeerError::new("denied", e))?;
+        let ctx = self.context(app, SEARCH, 0);
+        let found = self
+            .backend
+            .search(
+                &ctx,
+                SearchQuery {
+                    topic: query.to_owned(),
+                    language: lang.map(str::to_owned).filter(|l| !l.is_empty()),
+                    region: region.map(str::to_owned).filter(|r| !r.is_empty()),
+                    limit: narrowed.limit,
+                    max_age_hours: narrowed.max_age_hours,
+                    max_fetches: MAX_SEARCH_FETCHES,
+                },
+            )
+            .await
+            .map_err(host_error)?;
+        let mut notes = narrowed.notes;
+        notes.extend(found.notes);
+        let items: Vec<Value> = found
+            .items
+            .iter()
+            .filter(|i| app.scope.check_domain(&i.url).is_ok())
+            .take(narrowed.limit as usize)
+            .enumerate()
+            .map(|(n, i)| {
+                json!({"n": n + 1, "id": item_id(&i.url), "title": i.title, "url": i.url,
+                       "source": i.source, "language": i.language, "published_at": i.published_at,
+                       "readable": i.readable, "via": i.via})
+            })
+            .collect();
+        let now = self.stamp();
+        let doc = json!({
+            "kind": "search", "app_id": app.app_id, "query": query, "retrieved_at": now,
+            "items": items, "providers": found.providers, "partial": found.partial, "notes": notes,
+        });
+        let file = save(&app.folder, "search", query, &doc)?;
+        let mut reply = doc;
+        reply["file"] = json!(file);
+        Ok(reply)
+    }
+
+    async fn web_read(&self, app: &AppContext, args: &Value) -> Result<Value, PeerError> {
+        let url = args["url"].as_str().unwrap_or("").trim();
+        if url_host(url).is_none() {
+            return Err(PeerError::new("bad_request", "url must be an http(s) URL"));
+        }
+        app.scope
+            .check_domain(url)
+            .map_err(|e| PeerError::new("denied", e))?;
+        let ctx = self.context(app, WEB_READ, 1);
+        let item = FoundItem {
+            url: url.to_owned(),
+            title: String::new(),
+            source: url_host(url).unwrap_or_default(),
+            language: String::new(),
+            published_at: String::new(),
+            via: "web_read".into(),
+            readable: true,
+            snippet: String::new(),
+        };
+        let page = self.backend.read(&ctx, &item).await.map_err(host_error)?;
+        let sha = hex(&Sha256::digest(page.text.as_bytes()));
+        let (text, truncated) = cap_evidence(&page.text, WEB_READ_TEXT_MAX);
+        let now = self.stamp();
+        let doc = json!({
+            "kind": "read", "app_id": app.app_id, "url": url, "id": item_id(url),
+            "title": page.title, "retrieved_at": now, "evidence_sha256": sha, "text": page.text,
+        });
+        let file = save(&app.folder, "read", url, &doc)?;
+        Ok(json!({
+            "url": url, "id": item_id(url), "title": page.title, "retrieved_at": now,
+            "evidence_sha256": sha, "text": text, "truncated": truncated, "file": file,
+        }))
+    }
+
+    async fn deep_crawl(&self, app: &AppContext, args: &Value) -> Result<Value, PeerError> {
+        let narrowed =
+            scope::narrow_crawl(&app.scope, args).map_err(|e| PeerError::new("denied", e))?;
+        let site = url_host(&narrowed.url)
+            .ok_or_else(|| PeerError::new("bad_request", "url must be an http(s) URL"))?;
+        let site = site.strip_prefix("www.").unwrap_or(&site).to_owned();
+        let same_site = |link: &str| {
+            url_host(link).is_some_and(|h| h.strip_prefix("www.").unwrap_or(&h) == site)
+        };
+        let under_prefix = |link: &str| match &narrowed.path_prefix {
+            None => true,
+            Some(prefix) => url_path(link).is_some_and(|p| p.starts_with(prefix.as_str())),
+        };
+        let ctx = self.context(app, DEEP_CRAWL, narrowed.max_pages);
+        let mut frontier = VecDeque::from([(narrowed.url.clone(), 0u32)]);
+        let mut seen = BTreeSet::from([narrowed.url.clone()]);
+        let mut pages = Vec::new();
+        let mut failures = Vec::new();
+        let mut attempts = 0;
+        while let Some((url, depth)) = frontier.pop_front() {
+            if attempts >= narrowed.max_pages {
+                break;
+            }
+            attempts += 1;
+            match self.backend.read_links(&ctx, &url).await {
+                Ok(linked) => {
+                    let (evidence, _) = cap_evidence(&linked.page.text, MAX_EVIDENCE_BYTES);
+                    let (excerpt, _) = cap_evidence(&linked.page.text, MAX_EXCERPT_BYTES);
+                    pages.push(json!({
+                        "n": pages.len() + 1, "url": linked.final_url, "id": item_id(&linked.final_url),
+                        "title": linked.page.title, "depth": depth, "excerpt": excerpt, "text": evidence,
+                        "evidence_sha256": hex(&Sha256::digest(linked.page.text.as_bytes())),
+                    }));
+                    if depth < narrowed.max_depth {
+                        for link in linked.links.into_iter().take(CRAWL_LINKS_PER_PAGE) {
+                            if frontier.len() >= CRAWL_FRONTIER_MAX {
+                                break;
+                            }
+                            if same_site(&link)
+                                && under_prefix(&link)
+                                && app.scope.check_domain(&link).is_ok()
+                                && seen.insert(link.clone())
+                            {
+                                frontier.push_back((link, depth + 1));
+                            }
+                        }
+                    }
+                }
+                Err(e) if pages.is_empty() && frontier.is_empty() => return Err(host_error(e)),
+                Err(e) => failures.push(json!({"url": url, "error": e.to_string()})),
+            }
+        }
+        let now = self.stamp();
+        let doc = json!({
+            "kind": "crawl", "app_id": app.app_id, "url": narrowed.url, "retrieved_at": now,
+            "max_depth": narrowed.max_depth, "max_pages": narrowed.max_pages,
+            "path_prefix": narrowed.path_prefix, "pages": pages, "failures": failures,
+        });
+        let file = save(&app.folder, "crawl", &narrowed.url, &doc)?;
+        let listed: Vec<Value> = pages
+            .iter()
+            .map(|p| json!({"n": p["n"], "url": p["url"], "title": p["title"], "depth": p["depth"], "excerpt": p["excerpt"]}))
+            .collect();
+        Ok(json!({
+            "url": narrowed.url, "retrieved_at": now, "pages": listed,
+            "failures": doc["failures"], "file": file,
+        }))
+    }
+
+    fn stamp(&self) -> String {
+        (self.clock)().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
+    }
+}
+
+/// Writes `doc` to `<folder>/research/<kind>-<slug>-<hash>.json` and returns
+/// the path relative to the folder.
+fn save(folder: &Path, kind: &str, subject: &str, doc: &Value) -> Result<String, PeerError> {
+    let dir = folder.join("research");
+    std::fs::create_dir_all(&dir)
+        .map_err(|e| PeerError::new("io", format!("toolbox folder: {e}")))?;
+    let body = serde_json::to_vec_pretty(doc).map_err(|e| PeerError::new("io", e.to_string()))?;
+    let hash = &hex(&Sha256::digest(&body))[..12];
+    let name = format!("{kind}-{}-{hash}.json", slug(subject));
+    let path: PathBuf = dir.join(&name);
+    let tmp = path.with_extension("json.tmp");
+    std::fs::write(&tmp, &body)
+        .and_then(|_| std::fs::rename(&tmp, &path))
+        .map_err(|e| PeerError::new("io", format!("write {name}: {e}")))?;
+    Ok(format!("research/{name}"))
+}
+
+/// The path of an `http(s)` URL (`/` when it has none).
+fn url_path(url: &str) -> Option<&str> {
+    let rest = url
+        .strip_prefix("https://")
+        .or_else(|| url.strip_prefix("http://"))?;
+    let rest = rest.split(['?', '#']).next()?;
+    Some(rest.find('/').map_or("/", |at| &rest[at..]))
+}
+
+fn slug(text: &str) -> String {
+    let mut out = String::new();
+    for c in text.chars() {
+        if c.is_ascii_alphanumeric() {
+            out.push(c.to_ascii_lowercase());
+        } else if !out.ends_with('-') {
+            out.push('-');
+        }
+        if out.len() >= 40 {
+            break;
+        }
+    }
+    let out = out.trim_matches('-');
+    if out.is_empty() {
+        "item".into()
+    } else {
+        out.to_owned()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn app(grants: &[&str], scope: Value) -> AppContext {
+        let mut app =
+            AppContext::new("os.news", "/nonexistent").with_scope(scope::parse(&scope).unwrap());
+        for g in grants {
+            app = app.grant(*g);
+        }
+        app
+    }
+
+    fn names(app: &AppContext) -> Vec<String> {
+        tool_decls(app, &Library::builtin().unwrap())
+            .iter()
+            .map(|d| d["name"].as_str().unwrap().to_owned())
+            .collect()
+    }
+
+    #[test]
+    fn registration_follows_the_grants() {
+        assert!(names(&app(&[], json!({}))).is_empty());
+        assert_eq!(
+            names(&app(&["research"], json!({}))),
+            [RUN, FORK, SEARCH, WEB_READ]
+        );
+        // `crawl` without crawl limits is no crawl.
+        assert_eq!(names(&app(&["crawl"], json!({}))), Vec::<String>::new());
+        assert_eq!(
+            names(&app(&["crawl"], json!({"max_depth": 2, "max_pages": 10}))),
+            [DEEP_CRAWL]
+        );
+        assert_eq!(
+            names(&app(
+                &["research", "crawl"],
+                json!({"max_depth": 2, "max_pages": 10})
+            )),
+            [RUN, FORK, SEARCH, WEB_READ, DEEP_CRAWL]
+        );
+        // The limits alone grant nothing.
+        assert!(names(&app(&[], json!({"max_depth": 2, "max_pages": 10}))).is_empty());
+    }
+
+    #[test]
+    fn declarations_are_octos_tools_json_entries() {
+        let decls = tool_decls(
+            &app(
+                &["research", "crawl"],
+                json!({"max_depth": 2, "max_pages": 10}),
+            ),
+            &Library::builtin().unwrap(),
+        );
+        let allowed: BTreeSet<&str> = [
+            "name",
+            "app",
+            "description",
+            "input_schema",
+            "risk",
+            "background",
+            "outward",
+            "confirm",
+            "shareable",
+        ]
+        .into();
+        for d in &decls {
+            let name = d["name"].as_str().unwrap();
+            // `<app>.<tool>`: 2–4 segments of [a-z][a-z0-9_]{0,31}.
+            let segments: Vec<&str> = name.split('.').collect();
+            assert!((2..=4).contains(&segments.len()), "{name}");
+            assert!(segments.iter().all(|s| s.len() <= 32
+                && s.starts_with(|c: char| c.is_ascii_lowercase())
+                && s.bytes()
+                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')));
+            assert!(
+                d.as_object()
+                    .unwrap()
+                    .keys()
+                    .all(|k| allowed.contains(k.as_str())),
+                "{d}"
+            );
+            assert!(d["description"].as_str().unwrap().len() <= 2048, "{name}");
+            assert_eq!(d["input_schema"]["type"], "object");
+            let risk = if name == FORK { "act" } else { "read" };
+            assert_eq!(d["risk"], risk, "{name}");
+            assert_eq!(d["outward"], false);
+            assert_eq!(d["background"], true);
+            assert_eq!(d["confirm"], "host");
+            assert_eq!(d["app"], OWNER, "marked with its owning app");
+            assert_eq!(d["shareable"], true);
+        }
+        // Everything granted is offered: the catalog, nothing held back.
+        assert_eq!(decls, catalog(&Library::builtin().unwrap()));
+        // The run tool lists the templates.
+        assert!(decls[0]["description"]
+            .as_str()
+            .unwrap()
+            .contains("news-digest"));
+    }
+
+    #[test]
+    fn saved_names_are_slugged_and_relative() {
+        assert_eq!(slug("https://Example.org/a b?c"), "https-example-org-a-b-c");
+        assert_eq!(slug("台风"), "item");
+        assert_eq!(url_path("https://example.org/a/b?c#d"), Some("/a/b"));
+        assert_eq!(url_path("https://example.org"), Some("/"));
+        assert_eq!(url_path("ftp://example.org/a"), None);
+    }
+}
diff --git a/crates/toolbox/src/research/mod.rs b/crates/toolbox/src/research/mod.rs
index 37803cfa..982214db 100644
--- a/crates/toolbox/src/research/mod.rs
+++ b/crates/toolbox/src/research/mod.rs
@@ -152,6 +152,32 @@ pub trait ResearchBackend {
         ctx: &'a CallContext,
         item: &'a FoundItem,
     ) -> HostFuture<'a, Result<PageText, HostError>>;
+
+    /// Reads one page of a crawl (`deep_crawl`, the `crawl` capability): its
+    /// main text, the URL it was finally read from, and the absolute
+    /// `http(s)` links on it. Backends that cannot list links refuse, which
+    /// is the default.
+    fn read_links<'a>(
+        &'a self,
+        _ctx: &'a CallContext,
+        _url: &'a str,
+    ) -> HostFuture<'a, Result<LinkedPage, HostError>> {
+        Box::pin(async {
+            Err(HostError::Denied(
+                "this research backend cannot crawl".into(),
+            ))
+        })
+    }
+}
+
+/// One page of a crawl.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LinkedPage {
+    /// Where the page was read from, after redirects.
+    pub final_url: String,
+    pub page: PageText,
+    /// Absolute `http(s)` links, in page order, without fragments.
+    pub links: Vec<String>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/crates/toolbox/src/research/octos.rs b/crates/toolbox/src/research/octos.rs
index c1a2e3fc..dc38b6dc 100644
--- a/crates/toolbox/src/research/octos.rs
+++ b/crates/toolbox/src/research/octos.rs
@@ -48,7 +48,9 @@
 //!   say `readable: false` and templates skip them.
 
 use super::chrome::{Chrome, ChromeConfig};
-use super::{same_language, FoundItem, PageText, ResearchBackend, SearchQuery, SearchResults};
+use super::{
+    same_language, FoundItem, LinkedPage, PageText, ResearchBackend, SearchQuery, SearchResults,
+};
 use crate::host::{url_host, CallContext, HostError, HostFuture};
 use octos_research::metasearch::{
     EngineReport, EngineStatus, MetaItem, Metasearch, ReqwestFetch, SearchRequest,
@@ -187,6 +189,9 @@ impl OctosResearch {
             timeout: config.timeout,
             respect_robots: config.respect_robots,
             renderer,
+            // `deep_crawl` lists a page's links from its HTML
+            // ([`ResearchBackend::read_links`]).
+            keep_html: true,
             ..ReaderConfig::default()
         });
         Self {
@@ -525,6 +530,82 @@ impl ResearchBackend for OctosResearch {
             })
         })
     }
+
+    fn read_links<'a>(
+        &'a self,
+        ctx: &'a CallContext,
+        url: &'a str,
+    ) -> HostFuture<'a, Result<LinkedPage, HostError>> {
+        Box::pin(async move {
+            let scope = &ctx.app.scope;
+            scope.check_domain(url).map_err(HostError::Denied)?;
+            let page = self.reader.read(url).await.map_err(read_error)?;
+            scope
+                .check_domain(&page.final_url)
+                .map_err(HostError::Denied)?;
+            let links = extract_links(&page.html, &page.final_url);
+            Ok(LinkedPage {
+                final_url: page.final_url,
+                page: PageText {
+                    text: page.text,
+                    title: page.meta.title.filter(|t| !t.trim().is_empty()),
+                },
+                links,
+            })
+        })
+    }
+}
+
+/// The absolute `http(s)` links of `<a href>`s in `html`, resolved against
+/// `base`, without fragments, deduplicated in page order. A plain scan, not
+/// a parser: it only has to find links, never to render.
+pub fn extract_links(html: &str, base: &str) -> Vec<String> {
+    let Ok(base) = url::Url::parse(base) else {
+        return Vec::new();
+    };
+    let lower = html.to_ascii_lowercase();
+    let mut links = Vec::new();
+    let mut seen = BTreeSet::new();
+    let mut from = 0;
+    while let Some(at) = lower[from..].find("href") {
+        let start = from + at + 4;
+        from = start;
+        let rest = &html[start..];
+        let trimmed = rest.trim_start();
+        let Some(after_eq) = trimmed.strip_prefix('=') else {
+            continue;
+        };
+        let after_eq = after_eq.trim_start();
+        let value = match after_eq.chars().next() {
+            Some(q @ ('"' | '\'')) => match after_eq[1..].find(q) {
+                Some(end) => &after_eq[1..1 + end],
+                None => continue,
+            },
+            Some(_) => {
+                let end = after_eq
+                    .find(|c: char| c.is_whitespace() || c == '>')
+                    .unwrap_or(after_eq.len());
+                &after_eq[..end]
+            }
+            None => continue,
+        };
+        let value = value.trim().replace("&amp;", "&");
+        if value.is_empty() || value.starts_with('#') {
+            continue;
+        }
+        let Ok(mut link) = base.join(&value) else {
+            continue;
+        };
+        if !matches!(link.scheme(), "http" | "https") {
+            continue;
+        }
+        link.set_fragment(None);
+        let link = link.to_string();
+        if seen.insert(link.clone()) {
+            links.push(link);
+        }
+    }
+    links
 }
 
 #[cfg(test)]
@@ -547,6 +628,22 @@ mod tests {
         }
     }
 
+    #[test]
+    fn links_are_absolute_http_without_fragments_or_repeats() {
+        let html = r##"<a href="/a">A</a> <A HREF='b?x=1&amp;y=2#top'>B</A>
+            <a href=https://other.example/c>C</a> <a href="#frag">F</a>
+            <a href="mailto:x@example.org">M</a> <a href="/a#again">A2</a>"##;
+        assert_eq!(
+            extract_links(html, "https://example.org/dir/page"),
+            [
+                "https://example.org/a",
+                "https://example.org/dir/b?x=1&y=2",
+                "https://other.example/c",
+            ]
+        );
+        assert!(extract_links(html, "not a url").is_empty());
+    }
+
     #[test]
     fn google_news_links_are_readable_only_with_a_browser() {
         let gn = "https://news.google.com/rss/articles/CBMiXYZ?oc=5";
diff --git a/crates/toolbox/src/scope.rs b/crates/toolbox/src/scope.rs
index 05cc8b72..fb2c0387 100644
--- a/crates/toolbox/src/scope.rs
+++ b/crates/toolbox/src/scope.rs
@@ -152,6 +152,41 @@ pub fn narrow_search(
     compat::narrow_search(scope, topic, language, region, max_age_hours, limit)
 }
 
+/// A `deep_crawl` narrowed to the grant (the `crawl` capability's limits).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NarrowedCrawl {
+    pub url: String,
+    /// Link hops from `url`, at least 1, at most the grant's `max_depth`.
+    pub max_depth: u32,
+    /// Pages read, at least 1, at most the grant's `max_pages`.
+    pub max_pages: u32,
+    /// Only URLs whose path starts with this, if set.
+    pub path_prefix: Option<String>,
+}
+
+/// Narrows one `deep_crawl` call (`{url, max_depth?, max_pages?,
+/// path_prefix?}`) to the grant, or refuses it: crawling not granted
+/// (`max_depth` or `max_pages` 0), no `url`, or a site outside the domain
+/// lists. Depth defaults to 1 and pages to 10, both clamped to the grant.
+/// With the feature this is `Scope::crawl_args`.
+pub fn narrow_crawl(scope: &Scope, args: &Value) -> Result<NarrowedCrawl, String> {
+    #[cfg(feature = "octos-engine")]
+    let narrowed = scope.crawl_args(args)?;
+    #[cfg(not(feature = "octos-engine"))]
+    let narrowed = compat::crawl_args(scope, args)?;
+    let number = |key: &str| narrowed.get(key).and_then(Value::as_u64).unwrap_or(1) as u32;
+    Ok(NarrowedCrawl {
+        url: narrowed["url"].as_str().unwrap_or_default().to_owned(),
+        max_depth: number("max_depth"),
+        max_pages: number("max_pages"),
+        path_prefix: narrowed
+            .get("path_prefix")
+            .and_then(Value::as_str)
+            .filter(|p| !p.is_empty())
+            .map(str::to_owned),
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -215,6 +250,30 @@ mod tests {
         assert!(allows_language(&unrestricted(), "en"));
     }
 
+    #[test]
+    fn crawls_need_the_crawl_limits_and_stay_within_them() {
+        let none = parse(&json!({})).unwrap();
+        let error = narrow_crawl(&none, &json!({"url": "https://example.org/"})).unwrap_err();
+        assert!(
+            error.contains("crawling is not in this app's grant"),
+            "{error}"
+        );
+        let scope =
+            parse(&json!({"max_depth": 2, "max_pages": 5, "domains_deny": ["bad.example.org"]}))
+                .unwrap();
+        let narrowed = narrow_crawl(
+            &scope,
+            &json!({"url": "https://example.org/", "max_depth": 9, "max_pages": 90, "path_prefix": "/a"}),
+        )
+        .unwrap();
+        assert_eq!((narrowed.max_depth, narrowed.max_pages), (2, 5));
+        assert_eq!(narrowed.path_prefix.as_deref(), Some("/a"));
+        let defaults = narrow_crawl(&scope, &json!({"url": "https://example.org/"})).unwrap();
+        assert_eq!((defaults.max_depth, defaults.max_pages), (1, 5));
+        assert!(narrow_crawl(&scope, &json!({"url": "https://bad.example.org/"})).is_err());
+        assert!(narrow_crawl(&scope, &json!({})).is_err());
+    }
+
     #[test]
     fn reads_are_checked_against_the_domains() {
         let scope = parse(&json!({
@@ -294,6 +353,18 @@ mod tests {
                     "{grant} {tag}"
                 );
             }
+            for args in [
+                json!({"url": "https://example.org/a"}),
+                json!({"url": "https://example.org/a", "max_depth": 9, "max_pages": 900, "path_prefix": "/news"}),
+                json!({"url": "https://bad.example.org/a", "max_depth": 1}),
+                json!({"max_depth": 1}),
+            ] {
+                assert_eq!(
+                    octos.crawl_args(&args),
+                    compat::crawl_args(&thin, &args),
+                    "{grant} {args}"
+                );
+            }
             for (language, region, hours, limit) in searches {
                 let a = narrow_search(&octos, "topic", language, region, hours, limit);
                 let b = compat::narrow_search(&thin, "topic", language, region, hours, limit);
diff --git a/crates/toolbox/src/scope/compat.rs b/crates/toolbox/src/scope/compat.rs
index 6ef3051f..e127083d 100644
--- a/crates/toolbox/src/scope/compat.rs
+++ b/crates/toolbox/src/scope/compat.rs
@@ -8,7 +8,7 @@
 use super::{NarrowedSearch, SEARCH_CATEGORY};
 use crate::host::url_host;
 use serde::{Deserialize, Serialize};
-use serde_json::Value;
+use serde_json::{json, Value};
 
 /// octos's metasearch categories.
 const CATEGORIES: &[&str] = &["general", "news", "science", "it", "social"];
@@ -222,3 +222,30 @@ pub fn narrow_search(
         notes,
     })
 }
+
+/// `Scope::crawl_args`: a `deep_crawl` call narrowed to the crawl limits.
+pub fn crawl_args(scope: &Scope, args: &Value) -> Result<Value, String> {
+    if scope.max_pages == 0 || scope.max_depth == 0 {
+        return Err("crawling is not in this app's grant".into());
+    }
+    let url = args
+        .get("url")
+        .and_then(Value::as_str)
+        .ok_or("url is required")?;
+    scope.check_domain(url)?;
+    let depth = args
+        .get("max_depth")
+        .and_then(Value::as_u64)
+        .unwrap_or(1)
+        .clamp(1, scope.max_depth as u64);
+    let pages = args
+        .get("max_pages")
+        .and_then(Value::as_u64)
+        .unwrap_or(10)
+        .clamp(1, scope.max_pages as u64);
+    let mut out = json!({"url": url, "max_depth": depth, "max_pages": pages});
+    if let Some(p) = args.get("path_prefix").and_then(Value::as_str) {
+        out["path_prefix"] = json!(p);
+    }
+    Ok(out)
+}
diff --git a/crates/toolbox/tests/peer.rs b/crates/toolbox/tests/peer.rs
new file mode 100644
index 00000000..ac25e867
--- /dev/null
+++ b/crates/toolbox/tests/peer.rs
@@ -0,0 +1,168 @@
+//! `toolbox.deep_crawl` through `PeerToolbox` over a scripted site: the
+//! crawl stays on the site, under the path prefix and inside the grant's
+//! domains and limits.
+
+mod common;
+
+use octosense_toolbox::fixture::{FakeModel, FakeModelConfig};
+use octosense_toolbox::host::{CallContext, HostError, HostFuture};
+use octosense_toolbox::peer::{PeerToolbox, DEEP_CRAWL};
+use octosense_toolbox::research::{
+    FoundItem, LinkedPage, PageText, ResearchBackend, SearchQuery, SearchResults,
+};
+use octosense_toolbox::{scope, AppContext, Library};
+use serde_json::{json, Value};
+use std::collections::BTreeMap;
+use std::sync::{Arc, Mutex};
+
+/// A site: each page's links.
+struct Site {
+    links: BTreeMap<&'static str, Vec<&'static str>>,
+    read: Mutex<Vec<String>>,
+}
+
+impl ResearchBackend for Site {
+    fn search<'a>(
+        &'a self,
+        _: &'a CallContext,
+        _: SearchQuery,
+    ) -> HostFuture<'a, Result<SearchResults, HostError>> {
+        Box::pin(async { Ok(SearchResults::default()) })
+    }
+    fn read<'a>(
+        &'a self,
+        _: &'a CallContext,
+        _: &'a FoundItem,
+    ) -> HostFuture<'a, Result<PageText, HostError>> {
+        Box::pin(async { Err(HostError::Failed("not used".into())) })
+    }
+    fn read_links<'a>(
+        &'a self,
+        ctx: &'a CallContext,
+        url: &'a str,
+    ) -> HostFuture<'a, Result<LinkedPage, HostError>> {
+        Box::pin(async move {
+            ctx.app.scope.check_domain(url).map_err(HostError::Denied)?;
+            self.read.lock().unwrap().push(url.to_owned());
+            let links = self
+                .links
+                .get(url)
+                .ok_or_else(|| HostError::Failed(format!("404 {url}")))?;
+            Ok(LinkedPage {
+                final_url: url.to_owned(),
+                page: PageText {
+                    text: format!("The page at {url}."),
+                    title: Some(url.to_owned()),
+                },
+                links: links.iter().map(|l| l.to_string()).collect(),
+            })
+        })
+    }
+}
+
+fn app(folder: &std::path::Path, scope: Value) -> AppContext {
+    AppContext::new("os.news", folder)
+        .grant("crawl")
+        .with_scope(scope::parse(&scope).unwrap())
+}
+
+#[tokio::test]
+async fn a_crawl_stays_on_the_site_and_within_its_limits() {
+    let site = Arc::new(Site {
+        links: BTreeMap::from([
+            (
+                "https://example.org/news/",
+                vec![
+                    "https://example.org/news/a",
+                    "https://example.org/about",
+                    "https://other.example/news/x",
+                    "https://bad.example.org/news/y",
+                    "https://www.example.org/news/b",
+                ],
+            ),
+            (
+                "https://example.org/news/a",
+                vec!["https://example.org/news/c"],
+            ),
+            ("https://www.example.org/news/b", vec![]),
+            ("https://example.org/news/c", vec![]),
+        ]),
+        read: Mutex::new(Vec::new()),
+    });
+    let model = Arc::new(FakeModel::new(BTreeMap::new(), FakeModelConfig::default()));
+    let toolbox = PeerToolbox::new(Library::builtin().unwrap(), site.clone(), model);
+    let dir = common::temp_dir("crawl");
+    let app = app(
+        &dir,
+        json!({"max_depth": 1, "max_pages": 10, "domains_deny": ["bad.example.org"]}),
+    );
+    let out = toolbox
+        .call(
+            &app,
+            DEEP_CRAWL,
+            json!({"url": "https://example.org/news/", "max_depth": 5, "path_prefix": "/news"}),
+        )
+        .await
+        .unwrap();
+    // Depth 1 (the grant's): the start and its on-site links under /news,
+    // never another site or a denied subdomain; not `c` (depth 2).
+    assert_eq!(
+        *site.read.lock().unwrap(),
+        [
+            "https://example.org/news/",
+            "https://example.org/news/a",
+            "https://www.example.org/news/b"
+        ]
+    );
+    assert_eq!(out["pages"].as_array().unwrap().len(), 3);
+    let file = out["file"].as_str().unwrap();
+    assert!(file.starts_with("research/crawl-"), "{file}");
+    let saved: Value =
+        serde_json::from_str(&std::fs::read_to_string(dir.join(file)).unwrap()).unwrap();
+    assert_eq!(saved["max_depth"], 1);
+    assert_eq!(
+        saved["pages"][0]["text"],
+        "The page at https://example.org/news/."
+    );
+
+    // The page limit holds.
+    site.read.lock().unwrap().clear();
+    let app = self::app(&dir, json!({"max_depth": 3, "max_pages": 2}));
+    toolbox
+        .call(
+            &app,
+            DEEP_CRAWL,
+            json!({"url": "https://example.org/news/", "max_pages": 50}),
+        )
+        .await
+        .unwrap();
+    assert_eq!(site.read.lock().unwrap().len(), 2);
+
+    // Without crawl limits, or outside the domains: refused before reading.
+    site.read.lock().unwrap().clear();
+    let none = AppContext::new("os.news", &dir).grant("crawl");
+    let refused = toolbox
+        .call(
+            &none,
+            DEEP_CRAWL,
+            json!({"url": "https://example.org/news/"}),
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(refused.kind, "not_granted");
+    let narrow = self::app(
+        &dir,
+        json!({"max_depth": 1, "max_pages": 2, "domains_allow": ["example.org"]}),
+    );
+    let refused = toolbox
+        .call(
+            &narrow,
+            DEEP_CRAWL,
+            json!({"url": "https://other.example/"}),
+        )
+        .await
+        .unwrap_err();
+    assert_eq!(refused.kind, "denied");
+    assert!(site.read.lock().unwrap().is_empty());
+    let _ = std::fs::remove_dir_all(&dir);
+}
diff --git a/desktop/Cargo.toml b/desktop/Cargo.toml
index ec800e6d..2c94a03f 100644
--- a/desktop/Cargo.toml
+++ b/desktop/Cargo.toml
@@ -66,3 +66,5 @@ app-aichat = ["octosense-shell/app-aichat"]
 # Developer mode from Settings and OCTOSENSE_DEV_MODE in a release build
 # (debug builds have it already; ADR 0004 §13).
 dev-mode = ["octosense-shell/dev-mode"]
+# The system toolbox offered to app agents (off by default; ADR 0002 §6).
+toolbox-peers = ["octosense-shell/toolbox-peers"]
diff --git a/phone/Cargo.toml b/phone/Cargo.toml
index fed7d08f..17b97d82 100644
--- a/phone/Cargo.toml
+++ b/phone/Cargo.toml
@@ -90,3 +90,5 @@ app-hub = ["dep:octosense-app-hub-app", "octosense-shell/app-hub"]
 # END native-apps: features
 app-aichat = ["dep:makepad-aichat", "octosense-shell/app-aichat"]
 dev-mode = ["octosense-shell/dev-mode"]
+# The system toolbox offered to app agents (off by default; ADR 0002 §6).
+toolbox-peers = ["octosense-shell/toolbox-peers"]