feat: add SharedState for sub-agent communication

[yuanhao]

Summary

• Adds SharedState — a shared key-value store (Arc<RwLock<HashMap<String, String>>>) that sub-agents can read/write via an injected shared_state tool
• Opt-in via .with_shared_state(state) on SubAgentTool — existing behavior unchanged
• Core agent loop untouched (no changes to types.rs, agent_loop.rs, agent.rs)
• Closes SubAgentTool: support shared REPL state across calls (RLM primitive) #34

New files

• src/shared_state.rs — SharedState type with 10MB default cap, get/set/remove/keys/summary
• src/tools/shared_state_tool.rs — SharedStateTool implementing AgentTool (get/set/list/remove)
• tests/shared_state_test.rs — 5 integration tests with MockProvider

Modified files

• src/sub_agent.rs — shared_state field + builder, injects tool + state summary into prompt
• src/tools/mod.rs — register module
• src/lib.rs — register module + re-export

Usage

let state = SharedState::new();
state.set("ci_log", large_log_text).await.unwrap();

let analyzer = SubAgentTool::new("analyzer", provider.clone())
    .with_shared_state(state.clone());  // opt-in

// Sub-agent calls shared_state(action="get", key="ci_log") to read
// Parent reads back: state.get("summary").await

Test plan

• cargo fmt -- --check
• cargo clippy --all-targets (with -Dwarnings)
• cargo test — 187 tests pass, 0 failures
• Unit tests for SharedState (get/set/remove/keys/capacity)
• Unit tests for SharedStateTool (all actions + error cases)
• Integration: parent stores → sub-agent reads
• Integration: sub-agent writes → parent reads back
• Integration: two parallel sub-agents share state
• Backward compat: SubAgentTool without shared_state works as before

🤖 Generated with Claude Code

[yuanhao]

Code review

Found 5 issues:

1. CLAUDE.md describes SharedState with outdated type (CLAUDE.md says "SharedState is a shared key-value store (Arc<RwLock<HashMap<String, String>>>)") but the implementation now uses Arc<dyn SharedStateBackend> with pluggable backends. The architecture description is factually wrong.

yoagent/CLAUDE.md

Lines 84 to 86 in 3312908

	`SharedState` is a shared key-value store (`Arc<RwLock<HashMap<String, String>>>`) for sub-agent communication. It lets a parent store large artifacts once and have multiple sub-agents read/write by reference — no re-pasting into prompts.

2. FileBackend key collision and broken keys() round-trip — key_to_path() sanitizes non-alphanumeric chars to _, so distinct keys like "summary:src/main.rs" and "summary_src_main.rs" map to the same file, causing silent overwrites. Additionally, keys() returns sanitized filenames, so key.strip_prefix("summary:") in rlm.rs will never match when using FileBackend.

yoagent/src/shared_state.rs

Lines 220 to 233 in 3312908

	/// Replaces path separators and other unsafe chars with underscores.
	fn key_to_path(&self, key: &str) -> PathBuf {
	let safe: String = key
	.chars()
	.map(|c| {
	if c.is_alphanumeric() || c == '-' || c == '_' || c == '.' {
	c
	} else {
	'_'
	}
	})
	.collect();
	self.dir.join(safe)
	}

3. docs/reference/configuration.md drops compaction_strategy from struct listing — The diff replaces compaction_strategy with turn_delay, but both fields exist in the real AgentLoopConfig struct. The docs now omit a public field entirely.

yoagent/docs/reference/configuration.md

Lines 28 to 31 in 3312908

	pub on_error: Option<OnErrorFn>,
	pub input_filters: Vec<Arc<dyn InputFilter>>,
	pub turn_delay: Option<Duration>,
	}

4. src/sub_agent.rs module doc still says "no nesting" — Line 10 states "sub-agents are not given other SubAgentTools" but examples/rlm.rs nests SubAgentTools, and docs/concepts/sub-agents.md was updated to say "Nesting supported". The source code comment contradicts both.

yoagent/src/sub_agent.rs

Lines 9 to 11 in 3312908

	//! - **Context isolation**: each invocation starts a fresh conversation
	//! - **Depth limiting**: sub-agents are not given other SubAgentTools (static, no runtime counter)
	//! - **Cancellation propagation**: the parent's cancel token is forwarded

5. FileBackend I/O errors silently swallowed — SharedState::get() uses .ok().flatten(), remove() uses unwrap_or(false), keys() uses unwrap_or_default(). Any filesystem error (permission denied, disk full) is indistinguishable from "key not found" to the caller and to sub-agents.

yoagent/src/shared_state.rs

Lines 341 to 368 in 3312908

	/// Get a value by key. Returns `None` if the key doesn't exist.
	pub async fn get(&self, key: &str) -> Option<String> {
	self.backend.get(key).await.ok().flatten()
	}
	/// Store a value. Returns `Err(CapacityError)` if the backend rejects it.
	pub async fn set(&self, key: &str, value: String) -> Result<(), SharedStateError> {
	self.backend.set(key, value).await
	}
	/// Remove a key. Returns `true` if the key existed.
	pub async fn remove(&self, key: &str) -> bool {
	self.backend.remove(key).await.unwrap_or(false)
	}
	/// List all keys (sorted).
	pub async fn keys(&self) -> Vec<String> {
	self.backend.keys().await.unwrap_or_default()
	}
	/// Human-readable summary of stored variables (key names + byte sizes).
	/// Suitable for injecting into a system prompt.
	pub async fn summary(&self) -> String {
	self.backend
	.summary()
	.await
	.unwrap_or_else(|_| "(error reading state)".to_string())
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}