Background

Tool output overflow (large outputs >50 KB) is currently stored as UUID files on disk. This was a pragmatic initial solution but has several drawbacks compared to SQLite, which is already used for conversation history and memory.

Exposed in PR #1771 (#1740): the overflow path is an absolute filesystem path, leaking the username into LLM context (SEC-JIT-03) and making the database non-portable.

Problems with current approach

• Absolute paths leak /Users/<username>/.zeph/overflow/ into LLM context
• No cleanup — files are not deleted when a conversation ends or the DB is wiped
• Not portable — copying the .db file alone is insufficient for backup/migration
• No atomicity — overflow file and conversation record written in separate operations
• No size limits — files can accumulate indefinitely

Proposal

Store overflow content as a BLOB in a new tool_overflow SQLite table, linked to the conversation message by message_id:

CREATE TABLE tool_overflow (
    id          TEXT PRIMARY KEY,  -- UUID, referenced in message body
    message_id  TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
    content     BLOB NOT NULL,
    created_at  INTEGER NOT NULL
);

The reference injected into body becomes an opaque ID rather than a path:

[tool output pruned; full content at overflow:{uuid}]

The agent retrieves it via a dedicated tool (or the existing memory_search path).

Tasks

1. Add tool_overflow table with migration step (--migrate-config)
2. Update save_overflow() in tool_execution/mod.rs to write to SQLite instead of disk
3. Update extract_overflow_ref() and reference format (opaque ID, not path)
4. Add a retrieval path — either extend an existing tool or add read_overflow native tool
5. Add TTL/eviction policy (e.g., delete on conversation end, or age-based)
6. Update debug_dump.rs rendering

References

• Initial overflow implementation: crates/zeph-core/src/agent/tool_execution/mod.rs
• JIT reference injection: research(memory): just-in-time tool result retrieval — store large outputs, inject references (Manus/Anthropic pattern) #1740, PR feat(core): JIT tool reference injection after pruning (#1740) #1771
• SEC-JIT-03: absolute path leaks username into LLM context