[ymote]

ADR 0002 §6 / ADR 0004 §12: the system toolbox offered to app agents as host-routed tools, on top of octos#2567's shell side from #145. This supersedes #108, which was written before octos#2567 was final and conflicts with main. This PR re-ports #108's toolbox parts onto main instead of rebasing it. Everything is behind the toolbox-peers feature, which is off by default (shell, desktop, phone and octosense-ai-host).

What changed vs #108

• Shell side of octos#2567: host tools, relay, peer/input, terminal.run on #system (ADR 0004) #145's registration and relay are used; toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108's are dropped.
  • toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108's crates/app-peers/src/peer_tools.rs, its broker.rs registration and routing, the peer-tools feature and hosted::launch_with_tools are not ported.
  • Main's broker registers the toolbox tools after every peer/prepare and reconnect, with generic_tools omitted. They come from ToolHost::declarations.
  • Main's relay (crates/shell/src/host_tools/) authorizes each call and routes it.
• The toolbox is one more owning app in the relay (toolbox), not a second tool host.
  • Its tools are declared once in the relay's catalog, each app: "toolbox" and shareable.
  • Each app is granted exactly its toolbox tools.
  • ToolboxExecutor is installed as the toolbox owner's executor, the same seam an in-process module uses. It runs each call with the toolbox engine.
• No hard-coded exclusions. toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108's "never offer octos deep_research" is gone. In practice that rule was the empty generic_tools list, which stripped every kernel tool from the peer. toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108's workflow.list/workflow.evaluate were simply never declared, and still aren't.
  • An app is offered exactly what it declares AND the person granted: ToolboxGrant::new(app, declared, granted, scope).
    • The research grant gives workflow.run (read), workflow.fork (act), toolbox.search (read) and toolbox.web_read (read).
    • The crawl grant, with max_depth/max_pages > 0, gives toolbox.deep_crawl (read).
  • octos's own generic tools stay the kernel's.
• ADR 0004 §8/§4: approval router, standing rules, shell sheets, first-use consent #120 first-use consent gates the toolbox.
  • Before the person allows an app's agent, ShellToolHost::declarations leaves out the toolbox's tools (Catalog::offered).
  • The relay also refuses the app's calls before consent (consent_pending), as it does for every host tool on main.
• Native modules' grants. The module host grants a native module the toolbox capabilities it declares (grant_module, before offer_with). Those capabilities are compiled in and reviewed with the shell.
  • toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108 applied its os.*-only rule to modules too. That rule is kept only for script-app manifests (ToolboxGrant::for_manifest), because the shells' App Hub pin (e8601b80) still does not include App Hub mobile: native-feeling frame pacing on the phone #26.
• Developer mode. It does not blanket-grant the toolbox's tools, which need the grant's scope (Catalog::may_call). It still grants other shareable tools as before.
• Ported from toolbox-peers: offer the system toolbox to app agents (ADR 0002 §6, behind a feature) #108 with small changes:
  • crates/toolbox peer module, read_links/LinkedPage, scope::narrow_crawl and its octos parity test.
  • ModelHostClient and the 256 KiB host input limit in the model service.
  • toolbox_folder/toolbox_root.
  • The per-app worker thread.
  • The mock model's CALL_TOOL rule.
  • Change: peer::catalog() is new; tool_decls is the catalog narrowed to the grant.
  • Change: deep_crawl's description no longer embeds one app's limits, since the catalog entry is shared.

Overlaps G3 (home-96's feat/adr0004-g3-app-tools)

These are small seams in crates/shell/src/host_tools/, kept separable so G3 can adopt or replace them:

• Catalog::set_grants(caller, owner, tools) replaces a caller's grants of one owner's tools. Main's grant(caller, tool) is only additive.
• Catalog::offered(app, dev_all, consented) is declarations without the toolbox owner's tools until consent.
• relay::TOOLBOX and host_tools::toolbox::{init, set_grant, grant_module, grant_manifest}. grant_manifest has no caller yet: App Hub install or tools.json loading (G3) is where a script app's grant comes from.
• This PR computes no generic_tools; that is G3's job.

Tests

Scripted kernel, via main's broker (crates/ai-host/tests/toolbox_peers.rs, 8 tests). A ToolHost stands in for the relay. The tests cover:

• a peer is registered exactly its declared+granted toolbox tools: every grant combination, declared-not-granted, granted-not-declared, the intersection, and module grants; each tool marked app: "toolbox";
• no toolbox tool is offered or run before consent, and it is offered at the next registration after consent;
• the os.*-only manifest rule and scope refusals;
• workflow.run/fork/search/web_read executed by the toolbox, with results under .host;
• a forged deep_crawl, refused by the relay and by the executor itself;
• cancel: a cancelled call is stopped and never answered;
• template model calls through ModelHost and the app's budget.

Shell relay (crates/shell/src/host_tools/tests.rs, +2 tests, with and without the feature):

• offered exactly the granted toolbox tools, only after consent, grants replaced, no developer-mode blanket;
• no toolbox call runs before consent or without a grant; routed to the toolbox executor once consented; cancel reaches it.

Toolbox: #108's unit tests, the crawl test (tests/peer.rs) and the catalog test ("everything granted is offered, nothing held back").

Real kernel, octos acffad3b (the pin), built locally with cargo build --release -p octos-cli --bin octos --no-default-features --features api:

• crates/ai-host/tests/toolbox_real_kernel.rs (new) passes.
  • Before consent, a real turn is offered no toolbox tool and none runs.
  • After consent, the real peer's offered tools include exactly toolbox_search, toolbox_web_read, workflow_fork, workflow_run among the toolbox's.
  • Real turns call toolbox_search and workflow_run; the result lands in .host.
  • toolbox_deep_crawl is not offered without crawl.
  • The peer keeps its kernel tools, because registration is additive.
• crates/app-peers/tests/real_kernel.rs: 8/8 pass.

Commands run locally:

• cargo test --locked for:
  • toolbox (plain, live, octos-engine);
  • ai-host (plain, octos-core,llm, toolbox-peers);
  • app-peers (plain, octos-core,ws);
  • llm-service and mail-service.
• From phone/:
  • cargo test --locked --features mobile-apps -p octosense-shell: 509 pass;
  • --features mobile-apps,toolbox-peers ... host_tools: 11 pass;
  • cargo check --locked -p octosense-home --features mobile-apps (and +toolbox-peers).
• Clippy -D warnings:
  • ai-host (toolbox-peers, octos-core,llm);
  • app-peers (octos-core,ws);
  • toolbox (plain, live,octos-engine);
  • no new shell warnings.
• cargo fmt -p octosense-toolbox --check and python3 tools/native_apps.py --check.

CI:

• apps.yml now tests and lints ai-host with toolbox-peers.
• phone.yml runs the shell's host_tools tests with toolbox-peers.
• The real-kernel toolbox test is not in kernel-security. That Ubuntu job does not build Makepad, which ai-host links. The test skips without OCTOS_APP_PEERS_TEST_KERNEL.

Not done / unverified

• octos deep_research "when declared and granted" is not testable here.
  • It is a kernel generic tool (a pipeline or skill), and the octos#2567 peer roster at this pin does not include it: the api build and the test profile offer no deep_research or deep_search.
  • Which generic tools a peer gets is its generic_tools list, which is G3's. generic_tools can only narrow the profile's roster, never widen it.
  • This PR only removes OctoSense's own exclusion.
• No shell run with the feature on: no hidden-window run and no device. The live octos engine was not exercised through a peer; only fixtures were.
• Script apps' toolbox grants are not wired. They need App Hub mobile: native-feeling frame pacing on the phone #26 on the shells' pin and G3's install-time declare/grant.

No pin moved, and no Rinx code was touched.

🤖 Generated with Claude Code