Agent OS roadmap: harden trust, multi-agent spine, IDE tools, session tree

[karutoil]

Summary

Deep dive of the CatCode codebase (Rust core, Go TUI, Next.js hub, TS SDK) produced a prioritized roadmap to strengthen the harness as a long-running, multi-agent coding product. Focus: fix safety/reliability debt first, then agent coordination, session/compaction model, IDE-grade tools, and provider/extensibility — while doubling down on Goal/CEO, microVM sandbox, self-learning, and dual UI.

This issue tracks the program of work. Sub-issues can split P0–P5 as needed.

Current strengths (protect)

• Goal / Control Center — first-class plan → deploy → verify phase machine; CEO loop on web
• Safety stack — workspace confinement, restricted paths, hybrid checkpoints, optional Microsandbox microVM, Destructive default approval
• Self-learning — memory scopes, episodes, failure atlas, change coupling, codebase index, collections
• Dual frontend — dense TUI (mouse, keybinds, plugin trust) + multi-project web hub (reattach, git, auth, export)
• Protocol v2 — run/session ids, sequence, fixtures (67 cmds / 99 events)

Gaps (internal)

Area	Today	Target
Multi-agent	In-process nested loops + intercom only	Async jobs, peer hub, park/revive, process supervision
Sessions	Flat JSONL; undo = last turn	Tree (id/parentId), leaf nav, branch, branch summaries
Compaction	Soft digest + LLM summarize	First-class compaction entries, shake/elide, optional vision archive
IDE tools	FS + bash + git + browser_*	LSP, better edit anchors, AST edit, eval REPL, unified read
Providers	OpenAI/Anthropic/Codex/GCA + presets	Broader catalog, local engines, key tool dialects, MCP client
Extensibility	Plugins + markdown skills	Secure install/trust, skill://, multi-root skills

Reliability / security debt (blocking “safer” claims)

From REVIEW.md — must close before leaning on sandbox/approval marketing:

Critical / high

• C1 Plugin install path traversal — untrusted plugin.name can remove_dir_all outside dest
• H1 Project plugin trust marker forgeable from repo
• H2 Global plugins fail under microsandbox → pre-hooks deny all tools
• H3 Streamed tool-call index unbounded → client OOM
• H5 write_file / bulk missing content silently truncates to empty
• H13 Cancelled subagents report success and promote partial worktrees
• H14 Sandbox stdout buffered unboundedly before truncate
• H15 Fetch SSRF edge cases (trailing-dot / wildcard DNS)
• H16 Browser file:// can read host files

Also

• Memory append/consolidate preserve schema v2 metadata; fix evidence overwrite / merge drop
• Split megamodules (main / provider / tools / plugins) along existing seams
• TUI/web parity: /control (CEO) on TUI; plugin-trust decisions UI on web

Roadmap

P0 — Trust & correctness (1–3 weeks)

1. Fix C1, H1–H3, H5, H13–H16 (+ related memory cancel/write bugs)
2. Cancelled workers never promote worktrees; write never truncates silently
3. Module splits so hub/LSP/session-tree have clean homes
4. CEO + plugin-trust UX parity across TUI and web

Done when: clean install + sandbox + plugin path cannot delete home; cancelled subagents cannot merge half-done trees.

P1 — Agent OS spine

1. Async task jobs with durable artifacts under session dir and auto-delivery into parent transcript
2. Hub tool v1 — peer messaging + job wait/cancel; revive idle subagent sessions from JSONL
3. Process supervision — named long-lived processes (dev servers): ready log/port, logs, stop; shared across CatCode instances in a project
4. Subagent lifecycle: park after finish (TTL), steer via hub, durable coordination beyond single core process death

P2 — Session tree + compaction

1. Session entries gain id / parentId; leaf navigation; /tree + /branch
2. Compaction as first-class entry (not only rewrite-in-place); preserve display transcript
3. Shake — elide huge tool results to artifact refs; evaluate cheap vision/archive compaction for vision models
4. Branch summaries when abandoning a path

Pairs with Goal/CEO — long missions need non-destructive history.

P3 — IDE tools (model effectiveness)

Deferred groups via existing load_tools to keep core schema lean:

Tool	Why
LSP	rename / refs / diagnostics without fragile CLI
Snapshot-tagged / hashline-style edit	fewer failed applies than pure search/replace
AST edit	structural multi-file rewrites
eval (py/js first)	retained REPL vs one-shot shell
Unified read	URLs, archives, skill://, memory://, agent artifacts
Browser	shared Chromium/CDP; block file://; optional relay later
DAP debug	after LSP

P4 — Providers & extensibility

1. Expand catalog (local engines keyless, more OAuth presets) — quality over raw count
2. Own 2–3 tool wire dialects for local/open models we care about
3. MCP client (consume servers) before inventing another plugin format
4. Skills: skill:// resolution + multi-root discovery
5. Marketplace browse optional — after trust/install security

P5 — Double down on CatCode moats

1. Goal/CEO as default long-horizon path — tree sessions + hub jobs + correct worktree promote; mission UX in TUI
2. Safer-by-default agent OS — keep Destructive default; map read/write/exec tiers; microVM for exec tools
3. Self-learning that compounds — fix memory bugs → mission → episodes → verified memories → skill proposals with user accept
4. Web hub multi-operator — multi-device cores already exist; add shareable session + process panel
5. Evidence-backed goals — research_evidence + failure_atlas + coverage_ledger into CEO verify

Explicit non-goals (for now)

• Defaulting to auto-approve everything
• Cloning every third-party provider before LSP / hub / session tree
• Computer-use before browser scheme lockdown + sandbox story
• Growing plugin surface without install/trust fixes

90-day target

Dimension	Today	Target
Safety	Feature-strong, bug-undercut	Hardened install/sandbox; safer defaults hold under review
Multi-agent	In-process only	Jobs + hub messaging + parked agents
Long sessions	Flat + digest/summarize	Tree + better compaction
Model tools	Bash-heavy	LSP + structured edit + REPL
Long-horizon	Goal/CEO lead	Goal/CEO + tree + hub = clear product lead
Providers/ext	Narrower	Good-enough + MCP; dialects for our users

References

• REVIEW.md — core bug audit
• docs/architecture/ — protocol and system shape
• core/src/goal.rs, subagent.rs, agent/compaction.rs, memory.rs, sandbox/, tooling/schema.rs
• docs/guides/goal-mode.md, control-center.md, subagents.md, sandbox.md

Acceptance (program-level)

• P0 items closed or tracked with owners
• P1 hub/jobs design doc + vertical slice (spawn → artifact → parent delivery)
• P2 session tree design (entry model + /tree UX) approved
• At least one P3 tool (prefer LSP or eval) shipped behind load_tools
• No regression in Goal/CEO, checkpoints, or Destructive approval defaults

[pullfrog]

Plan: Agent OS roadmap (#8)

Program plan for hardening trust, then multi-agent spine, session tree, IDE tools, and providers — without diluting Goal/CEO, microVM sandbox, self-learning, or dual UI.

REVIEW.md is not in-tree; findings below are mapped to live code. docs/architecture/hardening-plan.md already records runtime/coordinator work (v2 protocol, EventSink, leases). This plan focuses on remaining security debt and product spine.

---

Principles

1. Safety before surface area — no marketplace growth, computer-use, or broader plugin APIs until P0 install/sandbox/browser/fetch are closed.
2. Protect moats — Goal/CEO phase machine, Destructive default approval, workspace confinement, hybrid checkpoints stay default behavior.
3. Extend existing seams — load_tools groups, RuntimeCoordinator resources, IntercomBus, session v2 JSONL, deferred tools — do not invent parallel systems.
4. Small PRs, regression tests first — each P0 item ships with a unit/integration test that fails before the fix.
5. Sub-issues — split by priority band (below) so owners can land independently.

---

Code reality check (today)

Item	Locus	Status
C1 plugin path traversal	plugins.rs install / validate_plugin_name	Partially mitigated (name string checks); needs post-join containment under install root
H1 trust marker forge	plugin_trust.rs + user plugin-trust.json	Mostly fixed (store-only; test-only marker). Residual: path-keyed trust, optional content-hash pin
H2 global plugins + microsandbox	sandbox/microsandbox_backend.rs mounts + plugins.rs pre_* HookFailMode::Deny	Live — global dir often not mounted → pre-hooks deny all tools
H3 stream tool index	provider.rs ~1499 while tool_calls.len() <= idx	Live — unbounded growth
H5 silent empty write	tools.rs unwrap_or("") on content	Live — schema required, runtime not
H13 cancel → promote	subagent.rs Outcome::ok("[subagent aborted]") + promote on outcome.ok	Live (multiple cancel sites ~1604, 1806, 2057)
H14 unbounded stdout	sandbox/backend.rs collect-then-truncate_tail	Live — 8 MiB post-buffer
H15 fetch SSRF	fetch_tool.rs	Partial harden; trailing-dot + resolve residual
H16 browser file://	browser/wry_backend.rs navigate	Live — no scheme allowlist
Memory v2 wipe	memory.rs append/save + memory_hygiene.rs consolidate	Live — drops evidence / v2 fields
Megamodules	baseline: main 5800 / provider 5600 / tools 4400; plugins ~6.7k outside baseline	Ongoing splits under agent/, tooling/, providers/
UI parity	Web: /control yes, trust modal no · TUI: trust yes, /control no	Asymmetric

---

Milestone 0 — Program hygiene (1–2 days)

1. File sub-issues from this plan (P0a–P0d, P1 design, P2 design, P3 first tool).
2. Re-home or regenerate REVIEW.md from the live map (or link this plan) so security claims stay auditable.
3. Add a short “Agent OS roadmap” section under docs/architecture/ pointing at milestones and non-goals (optional; issue can remain SoT).
4. Confirm CI gates stay green: cd core && cargo fmt --check && cargo clippy --all-targets && cargo test --locked, protocol schema check, architecture baseline.

Done when: tracked issues exist; owners can pick P0 slices without re-auditing.

---

Milestone 1 — P0 Trust & correctness (1–3 weeks)

Order by blast radius (promote/write/OOM first, then sandbox/network, then install, then UX/memory/modules).

P0a — Correctness that corrupts work (days 1–4)

ID	Change	Tests
H13	On cancel: return non-ok outcome (or explicit cancelled); never promote_worktree unless ok && !cancel.is_cancelled(). Fix all abort paths in subagent.rs (single + parallel).	Cancel mid-run with worktree: assert no promote; journal/UI cancelled
H5	Require content key present for write_file / each bulk_write file; allow explicit "" only if key exists	Omit content → tool error, file unchanged
H3	Cap streamed tool-call index (e.g. 32–64) and total args bytes; fail stream on overflow in provider.rs / providers/streaming.rs	Malicious high index does not allocate multi-GB

P0b — Sandbox / network / browser (days 3–10)

ID	Change	Tests
H2	Always mount real global plugins root (~/.catalyst-code/plugins) RO; set sandbox plugin_dir to absolute global path; keep pre_* fail-closed only when script was reachable	Global pre-hook under microsandbox still allows tools when mount present
H16	Scheme allowlist on browser navigate/create: http/https/(optional about:blank); reject file:, data:, custom	file:///etc/passwd denied
H15	Strip trailing . on hosts; resolve A/AAAA and re-check private ranges per hop (or document residual + pin first hop)	Trailing-dot + private-resolve cases in fetch_tool suite
H14	Stream-cap stdout/stderr (ring/tail) before full collect; consider lower hook caps	Large guest stdout stays under memory bound

P0c — Install / trust residual (days 7–12)

ID	Change	Tests
C1	After dest_root.join(name), absolute/canonicalize and assert strict prefix under install roots before any remove_dir_all/copy; confine remove the same way	name with .., absolute, symlink escape → error, no delete outside dest
H1	Document as closed for forgeable markers; optional follow-up: pin trust to plugin.json (+ script) content hash	Existing project-gating tests remain; optional hash test

P0d — Memory + UI parity + module homes (parallel, days 5–15)

Work	Detail
Memory v2	Route append/consolidate through full write_memory_file (or extend save); serialize evidence_episodes; merge evidence on consolidate
TUI /control	Mirror web: slash + modal/panel sending start_goal with ceo_mode: true, auto_deploy: true (docs/guides/control-center.md)
Web plugin trust	Modal on plugin_trust_prompt; send decisions (TUI already has plugin_trust.go)
Module splits	Incremental extractions only where P1–P3 need homes: hub/jobs near intercom/subagent; session tree near session.rs; LSP/eval under tooling/ + deferred group. Keep architecture-baseline megamodule ceilings

P0 done when: clean install + sandbox + plugin path cannot delete home; cancelled subagents cannot merge half-done trees; write never silently empties; stream index bounded; browser cannot file:// host; global hooks work under microVM; CEO + trust UX on both frontends (or tracked with owners).

Suggested sub-issues: #8-P0a H13/H5/H3 · #8-P0b H2/H14/H15/H16 · #8-P0c C1/H1 · #8-P0d memory + UI + splits.

---

Milestone 2 — P1 Agent OS spine (design week + vertical slice)

Design doc (before large code)

Cover:

1. Async task jobs — durable artifacts under session dir; status machine (queued/running/done/failed/cancelled); auto-inject result into parent transcript; identity via session_id/run_id/parent_run_id.
2. Hub tool v1 — evolve IntercomBus + intercom / contact_supervisor tools: peer message, job wait/cancel, revive idle subagent from JSONL (park + TTL).
3. Process supervision — named long-lived processes (dev servers): ready via log/port, logs, stop; project-scoped sharing across CatCode instances (build on presence / workspace_activity + ResourceRegistry, not ad-hoc bash).
4. Lifecycle — park after finish; steer via hub; survive single core process death where durable state allows.

Vertical slice (must ship)

spawn job → write artifact under session → parent delivery event/message end-to-end with cancel that does not promote worktrees (depends on H13).

Build on: subagent.rs, intercom.rs, runtime/ ResourceKind, session::append_activity_state, worktree promote gates.

Out of scope for v1: multi-machine mesh, full marketplace, replacing in-process nested loops entirely.

Done when: design approved + vertical slice green in protocol harness / unit tests.

---

Milestone 3 — P2 Session tree + compaction

Design

1. Session entries gain stable id / parentId (session schema v3 or additive fields with loader migration).
2. Leaf navigation; /tree + /branch (TUI + web).
3. Compaction as first-class entry (not only rewrite-in-place); preserve display transcript.
4. Shake — elide huge tool results to artifact refs (extend soft digest + ToolOutputCache in agent/compaction.rs).
5. Branch summaries when abandoning a path.

Constraints: keep Goal/CEO long missions non-destructive; undo/checkpoints remain coherent; SDK today fabricates PI parentId — real tree replaces synthetic fork.

Done when: design approved; minimal tree load/nav prototype optional in same milestone or follow-on.

---

Milestone 4 — P3 IDE tools (one tool first)

Prefer LSP or eval behind existing load_tools:

Step	Work
Schema	New deferred group in tooling/schema.rs + DEFERRED_TOOLS_GUIDE / handle_load_tools
Runtime	LSP client lifecycle as ResourceKind (or eval REPL state under session)
Policy	Readonly diagnostics/refs parallel-safe; renames/edits sequential + approval
Follow-ons	Snapshot/hashline edit, AST edit, unified read (skill://, memory://, artifacts), browser shared CDP + scheme lockdown (after H16), DAP after LSP

Done when: at least one P3 tool ships behind load_tools with tests; core schema stays lean.

---

Milestone 5 — P4 Providers & extensibility (after P0 trust)

1. Catalog quality over count (local keyless engines, curated OAuth presets via core/providers/ + staging).
2. Own 2–3 tool wire dialects for local/open models we care about (adapter layer in providers/).
3. MCP client (consume servers) as bridge beside plugins — docs today say plugins replace MCP; introduce client without inventing a second plugin format.
4. Skills: skill:// resolution + multi-root discovery (today: .catalyst-code/skills).
5. Marketplace browse only after C1/H1/H2 install/trust story.

---

Milestone 6 — P5 Double down on moats (continuous)

Moat	Work
Goal/CEO	Tree sessions + hub jobs + correct promote; mission UX on TUI (/control)
Safer defaults	Keep Destructive default; map read/write/exec tiers; microVM for exec; marketing only after P0
Self-learning	Memory bugs → mission → episodes → verified memories → skill proposals with accept
Web hub multi-op	Shareable session + process panel on multi-device cores
Evidence-backed goals	Wire research_evidence + failure_atlas + coverage_ledger into CEO verify

---

Explicit non-goals (unchanged)

• Default auto-approve everything
• Cloning every third-party provider before LSP / hub / session tree
• Computer-use before browser scheme lockdown + sandbox story
• Growing plugin surface without install/trust fixes

---

90-day sequencing (suggested)

Window	Focus
Weeks 1–3	P0 complete (or residual tracked with owners)
Weeks 3–5	P1 design + jobs vertical slice
Weeks 5–7	P2 session tree design (+ shake if capacity)
Weeks 6–9	P3 first deferred tool (LSP or eval)
Weeks 8–12	P4 MCP client spike + skill://; P5 continuous polish

---

Acceptance (program-level) — how we close #8

• P0 items closed or tracked with owners (H1 can close as “mitigated” with note)
• P1 hub/jobs design doc + vertical slice (spawn → artifact → parent delivery)
• P2 session tree design (entry model + /tree UX) approved
• ≥1 P3 tool (prefer LSP or eval) shipped behind load_tools
• No regression in Goal/CEO, checkpoints, or Destructive approval defaults

First implementation PR (when Build is kicked)

Recommended first code PR after plan sign-off: H13 + H5 + H3 (P0a) — smallest correctness wins, unblocks safe multi-agent work, clear tests in subagent.rs / tools.rs / provider.rs.

Key references

• Issue body roadmap P0–P5
• docs/architecture/hardening-plan.md, docs/architecture/index.md, docs/architecture/protocol.md
• docs/guides/{goal-mode,control-center,subagents,sandbox,sessions}.md
• core/src/{subagent,plugins,plugin_trust,tools,provider,fetch_tool,memory,session,intercom,worktree}.rs
• core/src/{agent/compaction,sandbox,browser,tooling/schema}.rs
• architecture-baseline.json

---

Ready for human review / sub-issue split. No code changes in this run.

Task list (3/4 completed)

• Analyze issue Agent OS roadmap: harden trust, multi-agent spine, IDE tools, session tree #8 and gather codebase context
• Map P0 bugs and architecture seams to real code
• Produce structured actionable plan with milestones
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/ck-grok-4.5 ｜ 𝕏}

[pullfrog]

Implemented P0a (H13/H5/H3) from the Agent OS roadmap and opened a PR.

PR: #9

• H13: cancel/abort returns non-ok; worktree promote gated on ok && !cancelled
• H5: write_file / bulk_write require content key (explicit "" allowed)
• H3: stream tool-call index < 64 and args ≤ 8 MiB; no retry on cap overflow

Targeted unit tests passed (--no-default-features; full microsandbox link needs libcap-ng-dev in CI).

Task list (5/5 completed)

• Create branch and locate H13/H5/H3 code
• Fix H13: cancel must not promote worktree
• Fix H5: require content key for write_file/bulk_write
• Fix H3: cap streamed tool-call index
• Add/run tests, self-review, push PR

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using openai-compatible/ck-grok-4.5 ｜ 𝕏}