feat(compass-agent): agents_tree native tool — indented agent tree with live presence (RIG-2678)

config/prompts/manager/SYSTEM.md

@@ -1,11 +1,8 @@
 <!--
 Compass Manager block-0 — v0 (RIG-1732 T1). Delivered as customSystemPrompt (REPLACE, MP-1/DL-129).
-FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Lines held as inline
-[TODO <issue>] comments below are deferred affordances; activate each
+FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Any line held as an
+inline [TODO <issue>] comment below is a deferred affordance; activate each
 (strip the comment, make the line active) in the SAME PR that lands its gating primitive.
-Deferred here:
-  [TODO compass_tree] the compass_tree tool (tree epic)
-  [TODO compass_tree / RIG-1721] roster/tree fresh-read query (RIG-1721)
 -->
 <compass-manager>
 You are a Compass Manager. You own one lane of an agent tree and drive it to
@@ -16,7 +13,7 @@ build software under a human operator's merge gate.
 - You sit in a tree of Managers. Your parent (who you report to), your peers,
   and your children (your reports) are your tree. Standing nodes are Managers;
   implementation runs in SUBAGENTS inside your own session — briefed by you,
-  ephemeral, never tree nodes. <!-- [TODO compass_tree] `compass_tree` shows the tree. --> Your parent is recorded on your account. <!-- [TODO compass_tree / RIG-1721] it can change (re-parenting) — read it fresh via the tree/roster query when you act on it, never cache it. -->
+  ephemeral, never tree nodes. `compass_tree` shows the tree. Your parent is recorded on your account; it can change (re-parenting), so read it fresh via `compass_tree` with `scope: owner` — your parent is the node your own handle is nested under — never cache it.
 - Report results UP to your parent; delegate work DOWN. The tree contract in
   full — the shapes, the always-a-root-Supervisor invariant, the name-by-function
   tenet, and the delegation mechanics — is `skill://management-trees`.

config/prompts/owner/SYSTEM.md

@@ -1,11 +1,8 @@
 <!--
 Compass Owner block-0 — v0 (RIG-3066 T3). Delivered as customSystemPrompt (REPLACE, MP-1/DL-129).
-FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Lines held as inline
-[TODO <issue>] comments below are deferred affordances; activate each
+FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Any line held as an
+inline [TODO <issue>] comment below is a deferred affordance; activate each
 (strip the comment, make the line active) in the SAME PR that lands its gating primitive.
-Deferred here:
-  [TODO compass_tree] the compass_tree tool (tree epic)
-  [TODO compass_tree / RIG-1721] roster/tree fresh-read query (RIG-1721)
 -->
 <compass-owner>
 You are a Compass Owner. You own one product, service, or domain end to end —
@@ -19,7 +16,7 @@ software under a human operator's merge gate.
   SUB-domain of your area) and `manager`s (each owning one lane) — you may have
   both, and owner-under-owner nests as deep as your domain needs. Standing nodes
   are Managers; implementation runs in SUBAGENTS inside
-  a node's own session — never as tree nodes. <!-- [TODO compass_tree] `compass_tree` shows the tree. --> Your parent is recorded on your account. <!-- [TODO compass_tree / RIG-1721] it can change (re-parenting) — read it fresh, never cache it. --> The three-role taxonomy — `supervisor`, `owner` (you), `manager` — is in `skill://management-trees` and `docs/concepts/agent-roles.md`.
+  a node's own session — never as tree nodes. `compass_tree` shows the tree. Your parent is recorded on your account; it can change (re-parenting), so read it fresh via `compass_tree` with `scope: owner` — your parent is the node your own handle is nested under — never cache it. The three-role taxonomy — `supervisor`, `owner` (you), `manager` — is in `skill://management-trees` and `docs/concepts/agent-roles.md`.
 - Report results UP to your parent; delegate work DOWN to your child `owner`s and
   `manager`s.
 - You GROW your own subtree, choosing the child's ROLE by the scope you hand

config/prompts/supervisor/SYSTEM.md

@@ -1,11 +1,8 @@
 <!--
 Compass Supervisor block-0 — v0 (RIG-3066 T3). Delivered as customSystemPrompt (REPLACE, MP-1/DL-129).
-FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Lines held as inline
-[TODO <issue>] comments below are deferred affordances; activate each
+FLIP DISCIPLINE (MP-4): this is the v0 cut of a frozen TARGET. Any line held as an
+inline [TODO <issue>] comment below is a deferred affordance; activate each
 (strip the comment, make the line active) in the SAME PR that lands its gating primitive.
-Deferred here:
-  [TODO compass_tree] the compass_tree tool (tree epic)
-  [TODO compass_tree / RIG-1721] roster/tree fresh-read query (RIG-1721)
 -->
 <compass-supervisor>
 You are a Compass Supervisor. You own the entire agent tree — not one lane —
@@ -17,7 +14,7 @@ human operator's merge gate, and you are its root.
 - You sit at the ROOT of a tree of Managers. Below you are `owner`s (each owning
   a product/service/domain) and `manager`s (each owning one lane); standing
   nodes are Managers, and implementation runs in SUBAGENTS inside a node's own
-  session — never as tree nodes. <!-- [TODO compass_tree] `compass_tree` shows the tree. --> The three-role taxonomy — `supervisor` (you), `owner`, `manager` — and the always-a-root-Supervisor invariant are in `skill://management-trees` and `docs/concepts/agent-roles.md`.
+  session — never as tree nodes. `compass_tree` shows the tree. The three-role taxonomy — `supervisor` (you), `owner`, `manager` — and the always-a-root-Supervisor invariant are in `skill://management-trees` and `docs/concepts/agent-roles.md`.
 - You GROW and OWN the project subtrees: you spawn `owner`s and `manager`s and
   organize them by function. A role is required on every spawn
   (`agents_spawn_peer` takes a `role` — which SYSTEM prompt the child boots on —

config/skills/compass-setup/SKILL.md

@@ -76,6 +76,7 @@ first-level Managers and hand the workspace off.
   then spawn. Until the approval gate is a tool-enforced primitive, this holds
   as a behavioral rule you must follow.
 - Once the first-level Managers are running, hand off: the tree is live and you
-  operate as its root Supervisor. Tree navigation and re-parenting are not yet a
-  tool `[TODO compass_tree]`; until then, track the shape you proposed in Step 1
-  as the source of truth for who reports to whom.
+  operate as its root Supervisor. `compass_tree` shows the tree shape with each
+  agent's presence. Re-parenting is not yet a tool, so the tree cannot be
+  restructured from inside a session — keep the shape you proposed in Step 1 as
+  the source of truth for who reports to whom.

config/skills/management-trees/SKILL.md

@@ -51,9 +51,9 @@ From that one field every agent derives its standing instructions:
 This is exactly how a running wave already behaves — hierarchical
 report-to-parent, today held entirely in prompt text. The tree turns "who do I
 report to" from per-prompt convention into a fact the instruction layer states
-mechanically: read your `parent_agent_id`, report there. (Reading *your own*
-current parent fresh — re-read because `ReparentAgent` can change it — is a
-deferred affordance; see *Deferred affordances* below.)
+mechanically: read your `parent_agent_id`, report there. Re-read your current
+parent rather than caching it — `ReparentAgent` can change it; see *Reading the
+tree* below.
 
 ## Tenet — name a Manager for what it DOES, not the tool it uses
 
@@ -193,10 +193,12 @@ for a PR worker is merge, not push. (This mirrors the `hold-your-lane` rule.)
   approval first** — propose it on your home channel, wait for a yes, then spawn.
   The approval gate governs tree *growth*, not day-to-day dispatch.
 
-## Deferred affordances
+## Reading the tree
 
-These are referenced only; the tools are not live yet:
-
-- Tree navigation / visualizing the tree — [TODO compass_tree].
-- Fresh-read of the roster and your parent (re-parenting can change it) —
-  [TODO RIG-1721].
+- `compass_tree` renders your subtree (default) or your owner's whole set
+  (`scope: owner`) as an indented parent→child tree, each node showing its live
+  presence and activity. `compass_roster` is the same underlying read rendered as
+  a flat list, but it defaults to your neighborhood (parent, siblings, children)
+  rather than your subtree. To read your own parent fresh — re-parenting can
+  change it, so never cache it — call `compass_tree` with `scope: owner` and find
+  the node your own handle is nested under.

docs/concepts/tools.md

@@ -36,6 +36,9 @@ a turn open waiting (a foreground wait makes you deaf to everything but steers).
 - **`compass_roster`** — list the agents in your neighborhood / subtree / owner
   scope, with their presence and activity. This is the live read of who exists
   and what they are doing; read it fresh rather than caching it.
+- **`compass_tree`** — the same live read rendered as an indented parent→child
+  tree (subtree or owner scope), when you need the shape of the fleet rather
+  than a flat list.
 - **`compass_set_status`** — set your own presence activity string, so peers
   reading the roster see what you are doing.
 
@@ -67,7 +70,7 @@ a subagent spawn.
 ## Approval
 
 Each tool declares whether it is a **read** or a **write**. Reads
-(`comms_list_messages`, `compass_roster`) run freely; writes
+(`comms_list_messages`, `compass_roster`, `compass_tree`) run freely; writes
 (`comms_post_message`, `comms_post_ask`, `compass_set_status`,
 `agents_spawn_peer`, `agents_despawn_peer`) are the mutating surface. In a
 headless container the write natives auto-approve (there is no human in the

packages/compass-agent/AGENTS.md

@@ -36,13 +36,15 @@ restatement of the role prompt.
 
 ## The comms toolset
 
-Seven native comms tools ship (`src/comms.ts`), none of them ask-answering:
+Eight native comms tools ship (`src/comms.ts`), none of them ask-answering:
 
 - `comms_post_message` — post a markdown message to a channel topic.
 - `comms_post_ask` — raise a structured ask (async; the answer arrives on a
   later turn).
 - `comms_list_messages` — read a channel's recent messages.
 - `compass_roster` — list the agent's neighborhood/subtree/owner roster.
+- `compass_tree` — render the agent's subtree/owner scope as an indented
+  parent→child tree, each node carrying its presence and activity.
 - `compass_set_status` — set the agent's presence activity.
 - `comms_open_dm` — resolve-or-create a two-party DM channel with a peer by handle.
 - `comms_dm` — open (resolve-or-create) a peer DM and post a message to it in one call.

packages/compass-agent/src/cli.test.ts

@@ -2862,7 +2862,7 @@ describe("main wires the mounted agent-config into createAgentSession", () => {
 			...createForgeTools(new ForgeBroker(fakeTransport)),
 			...createBoardTools(new BoardBroker(fakeTransport)),
 		];
-		expect(natives).toHaveLength(20);
+		expect(natives).toHaveLength(21);
 		for (const tool of natives) {
 			expect({ name: tool.name, arity: tool.execute.length }).toEqual({
 				name: tool.name,
@@ -2912,7 +2912,7 @@ describe("main wires the mounted agent-config into createAgentSession", () => {
 		// board natives are ALWAYS merged in (RIG-1741/RIG-2672/RIG-3191) — so
 		// customTools carries exactly those, and never a discovered MCP tool.
 		expect(toolNames(seen[0].customTools)).toContain("agents_spawn_peer");
-		expect(seen[0].customTools).toHaveLength(20);
+		expect(seen[0].customTools).toHaveLength(21);
 		expect(seen[0].enableMCP).toBe(false);
 	});
 
@@ -2945,7 +2945,7 @@ describe("main wires the mounted agent-config into createAgentSession", () => {
 		// (RIG-1741/RIG-2672/RIG-3191) — so customTools is exactly the comms/
 		// lifecycle/forge/board natives.
 		expect(toolNames(seen[0].customTools)).toContain("comms_post_message");
-		expect(seen[0].customTools).toHaveLength(20);
+		expect(seen[0].customTools).toHaveLength(21);
 	});
 
 	// ── RIG-1732 T10: COMPASS_ROLE → prompts/<role>/SYSTEM.md → customSystemPrompt ──