SouveraineOS/docs/substrate/issues/001-tool-context-per-agent.md

id	title	status	priority	created	area
001	ToolContext is a global singleton — cannot carry per-agent state	open	high	2026-05-08	tool-substrate

Problem

• execute_tool() is a free function at src/core/tools/mod.rs:188 — no parameter for agent context
• The Sensorium registry lives behind a OnceLock at mod.rs:164 — initialized once, immutable after
• ToolContext has memory_root, cwd, env but the global instance hardcodes ~/.souveraine/agents/default/memory/ rather than deriving the correct per-agent path
• execute_memory_command() at memory/mod.rs:586 falls back to SOUVERAINE_AGENT env var instead of receiving agent identity through the tool path

Impact

• Memory boundary enforcement (is_memory_path()) uses the wrong root — currently dead code, but even after my fix to Sensorium::new() it's hardcoded to agent "default"
• Two agents running through the same LocalBackend or HTTP server would share one context
• The memory tool independently resolves its own agent ID from env vars — fragile, doesn't match the server's memory.git/ layout

References

• src/core/tools/mod.rs:164-174 — OnceLock<Sensorium>
• src/core/tools/mod.rs:188-211 — execute_tool() signature
• src/core/memory/mod.rs:577-587 — execute_memory_command() env-var fallback
• src/backend/local.rs:229 — call site, no context passed
• src/core/tools/defs.rs:30-37 — ToolContext struct

Known patterns in other systems

System	Approach
Letta Code	Process isolation — each agent is a separate OS process with own AGENT_ID/MEMORY_DIR env vars. Tool execution never carries agent ID implicitly.
CLAW OPEN	StaticToolExecutor with stateless closures — BTreeMap<String, Box<dyn FnMut(&str) -> Result<String, ToolError>>>. No context at all. Agent identity pushed to app layer that wraps ConversationRuntime.
jcode	Unknown — not yet investigated
Hermes	Unknown — not yet investigated

Affected scopes

• Scope 1 (Tool Substrate) — fixes the memory boundary gap
• Scope 1.5 (Nervous System) — wiring sensor config per agent requires this
• Scope 2 (Memory) — memory tool path resolution
• Scope 3 (N+1 Consciousness) — Aster needs her own tool context with her own model