[joemckenney]

Summary

The phase-2 tool from the plan, motivated by the demo's offered follow-up ("break down the Chrome renderers"). Returns parent/child forest with two mutually exclusive modes.

Modes

• root_pid: tree rooted at one PID. Single-element forest with the PID at top and every descendant nested. For unpacking Chrome's main → renderer → GPU model, systemd supervisors, etc.
• cgroup_path: forest of in-cgroup PIDs organized by parent/child relationships among PIDs in the same cgroup. A PID whose parent is outside the cgroup becomes a forest root. For understanding the shape of a heavy cgroup identified via cgroup-mcp.

Mutually exclusive: exactly one must be set; rejects both / neither.

Wire shape

Each TreeNode flattens ProcessEntry (so identifier fields are at the top level alongside children):

{ pid, comm, cmdline, state, ppid, rss_bytes, cgroup_path, children: [TreeNode, ...] }

Children sorted by rss_bytes desc with nulls last. Same redact_args / skipped semantics as the other tools.

Robustness

• Visited-set tracking defends against /proc inconsistency (e.g., a ppid cycle)
• root_pid for a nonexistent PID errors
• cgroup_path validated like everywhere else (no absolute, no ..)

Test plan

• 37 unit + 37 integration tests pass (9 new for process_tree covering both modes, forest roots, descendant nesting, nonexistent PID, empty cgroup, redaction, mutually-exclusive validation, cgroup path validation)
• fmt + clippy -D warnings + release build clean
• tool_list_snapshot reviewed; only diff is the new tool
• After merge: ask Claude something like "break down the Chrome process tree" and confirm renderers nest under the main process

🤖 Generated with Claude Code