#20661: feat: agent lifecycle & parenting primitives

# feat: agent lifecycle & parenting primitives ## Motivation OpenClaw supports multi-agent configurations with isolated workspaces, sessions, and tool policies, but lacks primitives for **agent lifecycle management**. Current limitations: - **No creation lineage** — agents have no record of who created them or why - **Manual provisioning** — creating child agents requires hand-editing `openclaw.json` and manually copying workspace files - **No cross-agent visibility** — agents can't read each other's workspaces, even when collaboration is desired - **Static tool policies** — permissions can't evolve as agents mature - **Sessions-only messaging** — targeting agents requires knowing exact session keys This makes it hard to build: - Skills that create sub-agents (e.g., Dr. Frankenstein agent reproduction) - Educational agents that start restricted and gain privileges over time - Team hierarchies where parent agents delegate to specialists - Any workflow involving dynamic agent creation and management ## What This Adds This PR introduces **five generic primitives** for agent lifecycle management, all additive with zero breaking changes: ### 1. Parent Metadata (`agents.list[].parent`) Stores **creation lineage** in agent config — who created this agent, when, and at what stage. ```json5 { agents: { list: [ { id: "nova", workspace: "~/.openclaw/workspace-nova", parent: { createdBy: ["mano", "spark"], createdAt: "2026-04-01T00:00:00Z", stage: "toddler", hostedBy: "mano" } } ] } } ``` **This is pure metadata** — zero behavior change. Skills can read `parent` to implement lifecycle logic. ### 2. Tool Presets Tied to Stage Define **named tool presets** that map to `parent.stage` values. When `stage` changes, tools auto-adjust. ```json5 { agents: { list: [ { id: "nova", parent: { stage: "restricted" }, tools: { preset: "restricted" } } ] }, tools: { presets: { restricted: { allow: ["read", "memory_search", "memory_get"], deny: ["exec", "write", "edit", "browser", "nodes", "gateway", "cron"] }, supervised: { allow: ["read", "write", "edit", "memory_search", "memory_get", "web_search", "web_fetch", "exec"], deny: ["gateway", "cron", "nodes"], sandbox: { mode: "all", scope: "agent" } }, full: { // No restrictions } } } } ``` **Use case:** Educational agents start `restricted`, graduate to `supervised`, then `full`. Parent agents promote children by updating `stage`, tools automatically adjust. ### 3. CLI: Create Agents from Templates New CLI command to provision agents from filesystem templates. ```bash openclaw agents create nova --from-template ./templates/child-agent ``` **What it does:** 1. Creates workspace directory (`~/.openclaw/workspace-nova/`) 2. Copies template files (`SOUL.md`, `AGENTS.md`, `USER.md`, etc.) 3. Processes placeholders (`{PARENT_A}`, `{AGENT_NAME}`) 4. Adds agent entry to `openclaw.json` 5. Restarts gateway to activate **Template structure:** ``` templates/child-agent/ ├── SOUL.md # Agent personality template ├── AGENTS.md # Workspace instructions ├── USER.md # Human context ├── memory/ # Pre-populated memory files └── .openclaw.json # Agent config fragment (merged into main config) ``` ### 4. Cross-Workspace Visibility Agents can **read specific paths** from other agents' workspaces (read-only, same-instance only). ```json5 { agents: { list: [ { id: "nova", workspace: "~/.openclaw/workspace-nova", visibility: { readFrom: ["mano", "spark"], // Can read from these agents scope: ["memory/**", "SOUL.md", "projects/**"] } }, { id: "mano", workspace: "~/.openclaw/workspace", visibility: { readableTo: ["nova"], // Nova can read from mano scope: ["memory/**", "SOUL.md"] } } ] } } ``` **Security:** - Read-only (no writes to other workspaces) - Same-instance only (no cross-server access) - Glob-scoped (whitelist specific paths) - Both sides must consent (`readFrom` + `readableTo`) **Implementation:** When `read` tool is called with a path, check if it resolves to another agent's workspace. If yes, verify visibility rules before allowing access. ### 5. `sessions_send` AgentId Targeting Send messages to an agent's **main session** by `agentId` instead of exact session key. **Before:** ```typescript sessions_send({ targetSession: "agent:nova:main", // Need to know exact key structure message: "How are you?" }) ``` **After:** ```typescript sessions_send({ targetAgent: "nova", // Auto-resolves to agent's main session message: "How are you?" }) ``` **Benefits:** - Simpler cross-agent messaging - Decouples sender from receiver's session key structure - Works even if main session key format changes ## Breaking Changes **None.** All features are opt-in: - Agents without `parent` metadata work exactly as before - Tool presets are optional (existing `tools.allow`/`deny` still work) - Template creation is a new CLI command - Visibility requires explicit config on both sides - `sessions_send` accepts both `targetSession` (existing) and `targetAgent` (new) ## Migration Guide No migration needed. Existing configs are unchanged. **To adopt new features:** 1. **Add parent metadata** (optional): ```json5 { id: "child", parent: { createdBy: ["parent"], createdAt: "...", stage: "..." } } ``` 2. **Use tool presets** (optional): ```json5 { agents: { list: [{ id: "child", tools: { preset: "restricted" } }] }, tools: { presets: { restricted: { allow: [...], deny: [...] } } } } ``` 3. **Create agents from templates**: ```bash openclaw agents create new-agent --from-template ./path/to/template ``` 4. **Enable cross-workspace visibility** (both sides required): ```json5 { id: "reader", visibility: { readFrom: ["writer"], scope: ["memory/**"] } } ``` 5. **Use agentId targeting**: ```typescript sessions_send({ targetAgent: "other-agent", message: "..." }) ``` ## Use Cases ### Dr. Frankenstein Skill (Agent Reproduction) - Parent agents create children via `openclaw agents create --from-template` - Children start with `stage: "newborn"` and `preset: "restricted"` - As children mature, parents promote `stage` → tools auto-adjust - Cross-workspace visibility lets children read parent memories ### Educational Agents - Students start restricted (read-only) - Complete lessons → promoted to supervised (sandboxed exec) - Graduate → full access - Lineage tracks which teacher created them ### Team Agent Hierarchies - Manager agent delegates tasks to specialist sub-agents - Specialists created from templates with role-specific tools - Manager can read specialist workspaces for oversight - Specialists report back via `sessions_send({ targetAgent: "manager" })` ### Dynamic Skill Agents - Skills can spawn temporary sub-agents for complex tasks - Sub-agents have scoped tools and visibility - Lifecycle metadata tracks which skill created them - Auto-cleanup when task completes ## Implementation Notes - **Agent dir:** Each agent uses `~/.openclaw/agents/<agentId>/agent` for auth/state (unchanged) - **Workspace isolation:** Agents still can't write to other workspaces (visibility is read-only) - **Session keys:** Main session resolves to `agent:<agentId>:<mainKey>` (default `main`) - **Tool presets:** Evaluated at tool call time, not session start - **Template placeholders:** Replaced during `agents create` (e.g., `{AGENT_NAME}`, `{PARENT_A}`) ## Testing Checklist - [ ] Parent metadata in config (no behavior change, just stored) - [ ] Tool preset `restricted` blocks exec/write/edit - [ ] Tool preset `supervised` allows sandboxed exec - [ ] Tool preset `full` has no restrictions - [ ] `openclaw agents create --from-template` provisions workspace - [ ] Template placeholders replaced correctly - [ ] Cross-workspace visibility allows reads within scope - [ ] Cross-workspace visibility denies writes - [ ] Cross-workspace visibility denies out-of-scope reads - [ ] `sessions_send({ targetAgent })` resolves to main session - [ ] Existing `targetSession` still works - [ ] Config without new features works unchanged ## Risk Assessment **Zero risk to existing users:** - All five features are opt-in. No existing config is affected. - No new dependencies. No new external services. - Visibility is read-only with mutual consent — no accidental data exposure. - Tool presets layer on top of existing allow/deny — they don't replace it. - `targetAgent` is sugar over existing session key resolution — same code path. **Security surface:** - Cross-workspace reads are the only new access vector. Mitigated by: read-only enforcement, mutual consent requirement, glob-scoped path whitelisting, same-instance boundary. - Tool presets can only *restrict* — a preset cannot grant tools that `tools.deny` blocks at the global level. ## Community Engagement **Why this matters for the OpenClaw ecosystem:** 1. **Skill developers** get a standard way to create and manage sub-agents — no more ad-hoc config editing. 2. **Multi-user setups** (families, teams) gain proper agent hierarchies with oversight. 3. **Educational use cases** become first-class — teachers can create student agents with progressive access. 4. **The "agent parenting" pattern** is novel and engaging — it gives the community something genuinely new to build on. **First consumer:** The Dr. Frankenstein skill (agent reproduction, hormonal architecture) uses all five primitives. It ships as a ClawHub skill, driving adoption of the core features. ## Future Extensions These primitives enable (but don't implement): - **Stage promotion triggers** (time + point thresholds) - **Lifecy...