From 978a544f19610549e99a11be3603da4d88d7e6af Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Sun, 21 Dec 2025 17:12:45 +0000 Subject: [PATCH] plan: design agent parent/child hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Design complete for agent parent/child hierarchy feature: - parentAgentId field to track agent relationships - MCP create_agent tool auto-sets parent from calling agent - Homepage filters to show only root agents - Agent menu shows sub-agents with navigation Added implementation tasks: - Server types (agent-manager, agent-sdk-types, agent-projections) - MCP server integration - Client types (session-store, agent-directory, messages) - Homepage filtering - Agent menu sub-agents section - End-to-end test task - Re-audit plan task 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- plan.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/plan.md b/plan.md index 3963038a7..b40969168 100644 --- a/plan.md +++ b/plan.md @@ -240,7 +240,7 @@ Remove `requestGitDiff` from useEffect dependencies in `git-diff.tsx`. Use a ref - Verify the loading spinner goes away - **Done (2025-12-21 18:20)**: PASSED. Tested via Playwright MCP - navigated to agent screen, clicked "View Changes", and git diff loaded successfully showing changes to `plan.md`. Only one `git_diff_request` was sent (no infinite loop). The `setGitDiffs` was called once and content rendered correctly. Fix verified working. -- [ ] **Plan**: Design and implement agent parent/child hierarchy. +- [x] **Plan**: Design and implement agent parent/child hierarchy. - Add `parentId` field to agents. - Agents created via MCP should auto-set parentId to the calling agent. @@ -250,6 +250,101 @@ Remove `requestGitDiff` from useEffect dependencies in `git-diff.tsx`. Use a ref - Ensure back button works properly when navigating agent hierarchy. - Add implementation tasks based on findings. - Add another **Plan** task at an appropriate position to re-audit after some progress. + - **Done (2025-12-21 19:30)**: Design complete. See findings below. + +### Agent Parent/Child Hierarchy Design + +**Overview**: Enable agents to spawn child agents, with UI support for viewing and navigating the hierarchy. + +**Architecture Summary**: + +Files requiring modification: +1. **Server Types** (`agent-manager.ts:77`): Add `parentAgentId?: string` to `ManagedAgentBase` +2. **SDK Types** (`agent-sdk-types.ts:148`): Add to `AgentSessionConfig` interface +3. **App Types** (`session-store.ts:85`, `agent-directory.ts:4`): Add to `Agent` and `AgentDirectoryEntry` +4. **MCP Server** (`mcp-server.ts:183`): Add `parentAgentId` to `create_agent` tool input schema +5. **Session Handler** (`session.ts:1248`): Pass `parentAgentId` in `handleCreateAgentRequest()` +6. **Message Schema** (`messages.ts:351`): Add to `CreateAgentRequestMessageSchema` +7. **Agent Projections** (`agent-projections.ts`): Include `parentAgentId` in serialized payload +8. **Homepage** (`agent-list.tsx`): Filter to show only root agents (no `parentAgentId`) +9. **Agent Menu** (`[agentId].tsx:536`): Add "Sub-Agents" section showing child agents +10. **Create Agent** (`[agentId].tsx:415`): Pass current agent ID as `parentAgentId` when spawning + +**Data Flow**: +1. MCP `create_agent` tool receives `parentAgentId` from calling agent context +2. Server stores `parentAgentId` on `ManagedAgent` +3. Agent projections include `parentAgentId` in client payload +4. Client stores `parentAgentId` in session store +5. Homepage filters: `agents.filter(a => !a.parentAgentId)` +6. Agent menu queries: `agents.filter(a => a.parentAgentId === currentAgentId)` + +**UI/UX Design**: +- Homepage shows only root agents (agents with no parent) +- Agent info menu adds "Sub-Agents" section with clickable child agents +- Tapping a child agent navigates to that agent's screen +- Back button works naturally via router history +- Child agents show parent info in their menu (optional enhancement) + +**MCP Context**: +- The MCP server runs in the context of a specific agent +- `create_agent` tool knows the calling agent's ID +- Automatically set `parentAgentId` to calling agent ID + +--- + +- [ ] **Implement**: Add parentAgentId field to server types. + + - Add `parentAgentId?: string` to `ManagedAgentBase` in `agent-manager.ts:77` + - Add `parentAgentId?: string` to `AgentSessionConfig` in `agent-sdk-types.ts:148` + - Update `toAgentPayload()` in `agent-projections.ts` to include `parentAgentId` + - Run typecheck after changes. + +- [ ] **Implement**: Add parentAgentId to MCP create_agent tool. + + - Add `parentAgentId` to tool input schema in `mcp-server.ts:183` + - Pass `parentAgentId` to `agentManager.createAgent()` call in `mcp-server.ts:263` + - The MCP server has access to the calling agent context - use that ID + - Run typecheck after changes. + +- [ ] **Implement**: Add parentAgentId to client types and session store. + + - Add `parentAgentId?: string` to `Agent` interface in `session-store.ts:85` + - Add `parentAgentId?: string` to `AgentDirectoryEntry` in `agent-directory.ts:4` + - Update message schema if needed in `messages.ts:351` + - Run typecheck after changes. + +- [ ] **Implement**: Filter homepage to show only root agents. + + - In `use-aggregated-agents.ts`, filter agents: `agents.filter(a => !a.parentAgentId)` + - Or filter in `agent-list.tsx` before rendering + - Root agents are those with `parentAgentId === undefined` or `null` + - Run typecheck after changes. + +- [ ] **Implement**: Add sub-agents section to agent info menu. + + - In `[agentId].tsx:536`, add a "Sub-Agents" section to the menu + - Query the session store for agents where `parentAgentId === currentAgentId` + - Display child agents as clickable menu items + - Tapping a child agent navigates to that agent's screen + - Show "No sub-agents" if none exist + - Run typecheck after changes. + +- [ ] **Test**: Verify parent/child hierarchy end-to-end. + + - Create a root agent via the UI + - Use MCP to spawn a child agent from within the root agent + - Verify homepage only shows the root agent (not the child) + - Verify root agent's menu shows the child in "Sub-Agents" section + - Click child agent in menu, verify navigation works + - Verify back button returns to parent agent screen + - If issues found: add fix tasks + re-test task. + +- [ ] **Plan**: Re-audit agent hierarchy after initial implementation. + + - Review test results + - Check for edge cases (orphaned agents, deep nesting) + - Consider showing parent info on child agent screens + - Add polish tasks if needed - [ ] **Plan**: Tool call details in bottom sheet on mobile.