[ymote]

Docs-only fixes for the drift the ADR 0004 gap review found, plus one code comment. Every claim was checked against main at baa90bd and octos acffad3b (the pin) before a doc was changed.

Fixes

Doc	Fix	Evidence
ADR 0004 header, Context, Gap 3, plan 3/5	octos#2567 and #106 marked merged	gh pr view: octos#2567 merged, #106 merged 2026-09-28
ADR 0004 Context	Keeps "verified at e6223ef" as history; adds that the pin is now acffad3b (octos#2616)	Cargo.toml:101
ADR 0004 Context (#2567 bullet)	generic_tools is an exact list; an empty list keeps nothing; omitted keeps the whole roster, ask_user_question and shell included. "Additive" means with generic_tools omitted	octos tests should_offer_exactly_the_generic_tools_the_host_sets, should_keep_the_peers_kernel_tools_when_it_registers_an_empty_set, should_offer_ask_user_question_on_a_peer_input_turn_when_the_host_lists_it (ui_protocol_peer_host_tools_tests.rs)
ADR 0004 Gap 2, §12 system agent paragraph	Dated note: octos's shell is denied since #117; the rest of the default set remains	system_tools.rs tool_policy(), enforce
ADR 0004 Gap 6	Withdrawn (premise false); the missing piece is the shell forwarding peer questions	same octos tests; no user_question handling in crates/app-peers
ADR 0004 §5	octos.context.open → octos.session.open	peer_link/wire.rs PEER_METHODS; Makepad peer.rs open_session
ADR 0004 §12	"octos refuses its own shell to app peers" corrected: with generic_tools omitted (as the broker registers), peers keep shell; the only barrier is the _main tool_policy, which fails open when enforce refuses	octos test should_offer_exactly_the_registered_tools_and_refuse_an_unlisted_one; broker.rs register_tools; tests/broker.rs:554; launch.rs:223
ADR 0004 plan step 3	The ask for ask_user_question on host-driven turns closed as already met (G14)	as above
architecture.md §2, §8 step 1	The system chat exists (#132: Setup → Assistant → Assistant chat, F8)	crates/shell/src/system_chat/
architecture.md process hosting, agents, §3 table, diagrams	The peer link's shell side exists (#130); no process app is granted an agent	crates/shell/src/peer_link/, frames routed in lib.rs; native-apps.json (Terminal octos: [])
architecture.md §7	macOS sandbox on main; Linux built but unvalidated (#138); Windows planned (#137)	crates/shell/src/sandbox/mod.rs table, clients.rs sandbox_policy
architecture.md disagreement 2	Fixed: a dead process app's tile stays, closed with a Restart	ClientSlot::stops_in_place, test an_unexpected_death_keeps_the_tile_closed_with_restart
architecture.md §6 storage	Self-contradiction resolved to the code: peers created since 665209e5 get the account folder as cwd; hash unification is #139	broker.rs open_params/cwds, host_tools::agent_workspace
architecture.md tool list, generic tools row	Omitted generic_tools = whole roster; shell stays unless tool_policy removes it	as above
architecture.md disagreements	2 and 4 fixed; new 11 (peer questions not forwarded) and 12 (only macOS sandbox)	as above
ai-services.md	Rechecked revision noted (baa90bd/acffad3b); octos#2567 merged; relay (#145) feeds the router; peer link built; system chat; exact list waits for octos#2605	as above
ADR 0002 line ~212 and amendment §1/§12; new "Amendment, 2026-09-29"	Dated notes for #117 and the two decisions	system_tools.rs
ADR 0003 "What the profile runs"	Dated amendment: since #117 the _main profile denies group:runtime	system_tools.rs enforce
crates/kernel/src/system_tools.rs module doc	The command-execution switch exists (#132); app peers are not yet narrowed by generic_tools (the broker omits it)	system_chat/grants.rs; broker.rs

Decisions (2026-09-29)

Recorded in ADR 0004 as dated decisions (the user's, relayed):

• G11: host.ask is dropped. App agents and the system agent ask with octos's own ask_user_question, which octos keeps on host-driven turns. The shell routes each question to the right conversation: the app's own conversation, or the system chat for system-agent turns (including peer/input turns). Updated in the Context, Gap 6, §6, plan step 6, the follow-ups, ADR 0002's amendment and architecture.md. No host.ask is registered on main (grep finds none); any remaining shell code for it is being removed separately.
• G12: terminal.run is process-only. The Terminal's AI types commands only when the Terminal runs as its own sandboxed process (macOS, Windows, Linux with Vulkan and Wayland). The in-process Terminal (Linux without Vulkan, phones) is read-only (Makepad apps/terminal/src/module.rs, read_only_manifest). §10, §12 and the Consequences say so, including that the system agent's terminal.run grant takes effect only where a process Terminal exists.

Review claims not taken

• "§5 PeerToolCall omits tool_call_id/args_digest": false for the peer link. The shell's ToolCallDown (peer_link/wire.rs) and Makepad's PeerToolCall (libs/ai/services/src/peer.rs) carry exactly the fields the ADR lists. tool_call_id and args_digest are on the kernel's peer/tool/call (crates/app-peers/src/host_tools.rs, HostToolCall), which the shell uses for dedupe and does not pass to the app. §5 unchanged.

Not changed

• docs/architecture.zh-CN.md and docs/ai-services.zh-CN.md are not updated; they now lag the English pages.
• The repo has no docs CI (no link checker in .github/workflows). A local check of every relative link and anchor in the five changed docs found none broken. cargo fmt -p octosense-kernel --check differs on main already (not in CI); this change touches only comments.

🤖 Generated with Claude Code