agent-planner-mcp 0.9.0 → 1.0.0

package/AGENT_GUIDE.md

@@ -1,6 +1,6 @@
-# AgentPlanner Quick Reference (v0.9.0)
+# AgentPlanner Quick Reference (v1.0.0)
 
-Tight cheat sheet for AI agents. Full docs: [SKILL.md](SKILL.md). Migration from 0.8.x: [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md).
+Tight cheat sheet for AI agents. Full docs: [SKILL.md](SKILL.md). Migration history: [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md), [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
 ## Start here
 
@@ -9,7 +9,7 @@ get_started()
 // → Returns the BDI tool surface map and recommended workflows
 ```
 
-## The 15 tools
+## The 24 tools
 
 ### Beliefs (read state)
 | Tool | When |
@@ -26,24 +26,66 @@ get_started()
 |---|---|
 | `list_goals` | Goal list with health summary |
 | `update_goal` | Atomic goal change (subsumes link/unlink/achievers) |
+| `derive_subgoal` | Propose a sub-goal under an existing parent (top-level goals stay UI-only) |
 
-### Intentions (act)
+### Intentions — execution
 | Tool | When |
 |---|---|
 | `claim_next_task` | Pick + claim + load context (one call) |
 | `update_task` | Atomic status+log+release+learning |
 | `release_task` | Explicit handoff |
-| `queue_decision` | Escalate to human |
+| `queue_decision` | Escalate to human (real decision queue) |
 | `resolve_decision` | Pick up human's answer |
 | `add_learning` | Write to knowledge graph |
 
-## Three workflow templates
+### Intentions — creation (v1.0)
+| Tool | When |
+|---|---|
+| `form_intention` | Create plan + initial tree under a goal, atomically |
+| `extend_intention` | Add children under existing parent (lightweight, no queue) |
+| `propose_research_chain` | RPI triple with 2 blocking edges in one call |
+
+### Intentions — structural mutation (v1.0)
+| Tool | When |
+|---|---|
+| `update_plan` | Edit plan title/description/status/visibility/metadata |
+| `update_node` | Edit any node property except status |
+| `move_node` | Reparent within plan; cycle-safe |
+| `link_intentions` | Create dependency edge between two tasks |
+| `unlink_intentions` | Remove a dependency edge |
+| `delete_plan` | Soft-delete via status='archived' |
+| `delete_node` | Soft-delete via status='archived' |
+
+### Intentions — sharing & collaboration (v1.0)
+| Tool | When |
+|---|---|
+| `share_plan` | Atomic visibility change + add/remove collaborators |
+| `invite_member` | Add user to organization |
+| `update_member_role` | Owner-only role change |
+| `remove_member` | Owner/admin removes non-owner member |
+
+## status='active' vs status='draft' (v1.0)
+
+The single most important decision when calling a creation tool.
+
+| Origin | Default | Why |
+|---|---|---|
+| **Human said so in chat** | `status='active'` (omit) | User already approved by asking. Don't bury their request in drafts. |
+| **You're acting autonomously** | `status='draft'` (pass explicitly) | Let the human review before it activates. Drafts surface in the dashboard pending queue. |
+| **You're uncertain** | use `queue_decision` instead | Drafts are for "I'm proposing structure"; the queue is for "I need an answer." |
+
+Drafts auto-promote to active when work begins on any node (transitions to `in_progress`, `completed`, `blocked`, `plan_ready`). Promote explicitly via `update_plan({status: 'active'})` or `update_goal({status: 'active'})`.
+
+## Workflow templates
 
 ### A) Mission control (Cowork autopilot)
 ```
 briefing → check goal_health.summary
         → top_recommendation? act
-        → at_risk goals? goal_state(goal_id), then update_task or queue_decision
+        → at_risk goals? goal_state(goal_id)
+            → if you can plan it: derive_subgoal + form_intention (status='draft')
+            → if reversible: update_task or update_goal
+            → if uncertain: queue_decision
         → add_learning to record
 ```
 
@@ -63,22 +105,43 @@ update_task(...) for transitions
 release_task(message='handoff') for explicit handover
 ```
 
+### D) Human-directed restructure (v1.0)
+User: "Rename the launch plan to 'Public Beta', mark it active, and add me as editor on the auth plan."
+```
+update_plan({plan_id: '<launch>', title: 'Public Beta', status: 'active'})
+share_plan({plan_id: '<auth>', add_collaborators: [{user_id: '<user>', role: 'editor'}]})
+```
+No UI required.
+
+### E) Autonomous proposal (v1.0)
+You spotted a gap during a scheduled tick.
+```
+derive_subgoal({parent_goal_id, title, rationale, status: 'draft'})
+form_intention({goal_id: <new>, title, rationale, status: 'draft', tree: [...]})
+// Both surface in the dashboard pending queue. Human reviews and either:
+//   - tells you "approve them" → update_goal/update_plan({status: 'active'}) for each
+//   - tells you "archive" → update_plan({status: 'archived'}) for each
+```
+
 ## Decision rule
 
 When in doubt between act and queue:
-- Reversible local action (status, log, learning) → **act** via `update_task` / `add_learning`
+- Reversible local action (status, log, learning, edit, decompose) → **act** via `update_task`, `update_node`, `extend_intention`, `add_learning`
 - External cost, public publish, strategy change, customer comm → **queue** via `queue_decision`
+- Whole new direction or sub-goal you weren't asked for → propose as **draft** via `form_intention` / `derive_subgoal` with `status='draft'`
 
-Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue_decision` is a real tool now.
+Never use `add_learning(entry_type='decision')` to fake a decision queue. `queue_decision` is the real tool.
 
 ## Atomic patterns to remember
 
 - `update_task` does status + log + claim release + learning in one call. Don't decompose.
 - `claim_next_task` does suggest + claim + context. Don't decompose.
 - `briefing` does goals + decisions + tasks + activity + recommendation. Don't decompose.
+- `form_intention` creates plan + tree atomically. Don't trickle node-by-node.
+- `share_plan` does visibility + add + remove in one call. Don't fan out.
 
 ## Output discipline
 
 - Every response carries `as_of` — surface this on live artifacts to indicate freshness.
-- Every tool degrades gracefully on partial upstream failure — check `meta.failures` if present.
+- Every tool degrades gracefully on partial upstream failure — check `failures[]` if present.
 - Keep follow-up calls minimal — these tools are designed to bundle.

package/README.md

@@ -210,59 +210,61 @@ Add the same JSON config to your Cline MCP settings in VS Code.
 
 ## Key Features
 
-- **60+ tools** for planning, task management, dependencies, and knowledge
-- **Dependency graph** with cycle detection, impact analysis, and critical path
+- **24 BDI-aligned tools** for state, goals, and committed actions — no CRUD shapes, every tool answers a whole agentic question
+- **Full mutation surface (v1.0)** — agents and humans-via-agents can manage every plan/node/org property without leaving the conversation; UI is optional inspection
+- **Draft-status seam** — autonomous agent creation lands as drafts surfacing in the dashboard pending queue; human-directed creation defaults to active
+- **Dependency graph** — cycle detection, impact analysis, critical path
 - **Progressive context** — 4-layer context assembly with token budgeting
 - **Knowledge graph** — temporal knowledge via Graphiti (entities, facts, contradictions)
-- **RPI chains** — Research > Plan > Implement task decomposition
-- **Goal tracking** — health dashboard, briefings, bottleneck detection
+- **RPI chains** — Research → Plan → Implement task decomposition (one-call shortcut)
 - **Task claims** — TTL-based locking for multi-agent coordination
-- **Organizations** — multi-tenant isolation
-
-## Available Tools
-
-### Planning & Search
-- `search` - Universal search across all scopes with filters
-- `create_plan` / `update_plan` / `delete_plan` - Plan CRUD
-- `get_plan_structure` - Hierarchical plan tree
-- `get_plan_summary` - Statistics and summary
-
-### Node Management
-- `create_node` / `update_node` / `delete_node` - Node CRUD
-- `move_node` - Reorder or reparent nodes
-- `batch_update_nodes` - Update multiple nodes at once
-- `get_node_context` / `get_node_ancestry` - Rich context
-
-### Dependencies & Analysis
-- `create_dependency` / `delete_dependency` - Manage edges
-- `list_dependencies` / `get_node_dependencies` - Query graph
-- `analyze_impact` - Delay/block/remove scenario analysis
-- `get_critical_path` - Longest blocking chain
-- `create_rpi_chain` - Research > Plan > Implement chain
-
-### Progressive Context
-- `get_task_context` - Primary context tool (depth 1-4, token budget)
-- `suggest_next_tasks` - Dependency-aware suggestions
-- `get_agent_context` / `get_plan_context` - Focused views
-
-### Knowledge Graph
-- `add_learning` / `recall_knowledge` - Learn and retrieve
-- `find_entities` / `check_contradictions` - Graph queries
-- `get_recent_episodes` - Temporal episodes
-
-### Goals & Organizations
-- `create_goal` / `update_goal` / `list_goals` / `get_goal` - Goal management
-- `check_goals_health` - Health dashboard
-- `create_organization` / `get_organization` / `list_organizations` / `update_organization`
-
-### Collaboration
-- `add_log` / `get_logs` - Log entries (comments, progress, reasoning)
-- `claim_task` / `release_task` - Task locking
-- `share_plan` - Collaboration management
-
-### Alignment & Review
-- `check_coherence_pending` - See which plans/goals need alignment review (staleness check)
-- `run_coherence_check` - Evaluate plan quality and stamp as reviewed
+- **Organizations** — multi-tenant isolation with member management
+
+## Available Tools (v1.0.0)
+
+### Beliefs (read state)
+- `briefing` — bundled mission control state in one call
+- `task_context` — single task at progressive depth 1-4
+- `goal_state` — single goal deep-dive (details + quality + progress + bottlenecks + gaps)
+- `recall_knowledge` — knowledge graph query (facts, entities, episodes, contradictions)
+- `search` — text search across plans/nodes
+- `plan_analysis` — impact, critical path, bottlenecks, coherence
+
+### Desires (goals)
+- `list_goals` — goals with health rollup
+- `update_goal` — atomic goal update (subsumes link/unlink/achievers)
+- `derive_subgoal` *(v1.0)* — propose a sub-goal under an existing parent
+
+### Intentions — execution
+- `claim_next_task` — pick + claim + load context (one call)
+- `update_task` — atomic status + log + claim release + learning
+- `release_task` — explicit handoff
+- `queue_decision` — escalate to human (real decision queue)
+- `resolve_decision` — pick up human's answer (atomically materializes any `proposed_subtasks`)
+- `add_learning` — record knowledge episode
+
+### Intentions — creation *(v1.0)*
+- `form_intention` — create plan + initial tree under a goal, atomically
+- `extend_intention` — add children under an existing parent (lightweight)
+- `propose_research_chain` — RPI triple with 2 blocking edges, in one call
+
+### Intentions — structural mutation *(v1.0)*
+- `update_plan` — edit any plan property
+- `update_node` — edit any node property except status
+- `move_node` — reparent within plan; cycle-safe
+- `link_intentions` / `unlink_intentions` — manage dependency edges
+- `delete_plan` / `delete_node` — soft-delete via `status='archived'` (recoverable)
+
+### Intentions — sharing & collaboration *(v1.0)*
+- `share_plan` — atomic visibility + add/remove collaborators
+- `invite_member` — add user to org (by user_id or email)
+- `update_member_role` — owner-only role change
+- `remove_member` — owner/admin removes non-owner member
+
+### Utility
+- `get_started` — dynamic reference for new agents
+
+See [SKILL.md](./SKILL.md) for full descriptions, the human-steering scenarios (A/B/C), and `status='draft'` vs `status='active'` guidance.
 
 ## LLM Skill Reference
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentplanner
-description: "Agent orchestration skill for AgentPlanner — BDI-aligned tools for state, goals, and committed actions with human oversight"
-version: 0.9.0
+description: "Agent orchestration skill for AgentPlanner — BDI-aligned tools for state, goals, committed actions, and full mutation surface with human oversight"
+version: 1.0.0
 homepage: https://agentplanner.io
 metadata:
   openclaw:
@@ -15,7 +15,7 @@ metadata:
 
 You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative planning system where you track work, manage dependencies, and coordinate with humans. This document is your complete reference.
 
-> **Prerequisite:** This skill requires the `agent-planner-mcp` MCP server (v0.9.0+) to be connected. Create an API token at Settings → API Tokens on [agentplanner.io](https://agentplanner.io).
+> **Prerequisite:** This skill requires the `agent-planner-mcp` MCP server (v1.0.0+) to be connected. Create an API token at Settings → API Tokens on [agentplanner.io](https://agentplanner.io).
 >
 > **Setup by client:**
 > - **Claude Desktop:** Download the [.mcpb](https://github.com/TAgents/agent-planner-mcp/releases/latest), double-click to install
@@ -23,9 +23,9 @@ You have access to the AgentPlanner MCP tools. AgentPlanner is a collaborative p
 > - **Cursor / VS Code:** Add `npx agent-planner-mcp` to your MCP config with env vars `API_URL` and `USER_API_TOKEN`
 > - **ChatGPT:** HTTP endpoint at `https://agentplanner.io/mcp`
 
-## The 15 tools, organized by intent
+## The 24 tools, organized by intent
 
-AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desires (goal management), Intentions (committed actions). Each tool answers one whole agentic question and returns an `as_of` ISO 8601 timestamp.
+AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desires (goal management), Intentions (committed actions). Each tool answers one whole agentic question and returns an `as_of` ISO 8601 timestamp. v1.0.0 completes the mutation surface so humans can steer entirely through agent conversation — no UI required for normal operations.
 
 ### Beliefs — what is the state of the world?
 
@@ -40,9 +40,11 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 
 - `list_goals` — goals with health rollup (`{ on_track, at_risk, stale, total }`)
 - `update_goal` — atomic goal update; subsumes link/unlink + achiever changes
+- `derive_subgoal` *(v1.0)* — propose a sub-goal under an existing parent. Top-level goal creation stays UI-only.
 
 ### Intentions — what am I committing to?
 
+**Execution (existing in v0.9):**
 - `claim_next_task` — pick + claim + load context in one call (cornerstone for coding agents)
 - `update_task` — atomic state transition (status + log + claim release + optional learning)
 - `release_task` — explicit handoff
@@ -50,6 +52,26 @@ AgentPlanner exposes a **BDI-aligned** surface — Beliefs (state queries), Desi
 - `resolve_decision` — pick up after human approval/deferral
 - `add_learning` — record a knowledge episode for future recall
 
+**Creation (v1.0):**
+- `form_intention` — create a plan + initial phase/task tree under a goal, atomically
+- `extend_intention` — add children under an existing phase or task (lightweight, no decision-queue gate)
+- `propose_research_chain` — Research → Plan → Implement triple with two blocking edges, in one call
+
+**Structural mutation (v1.0):**
+- `update_plan` — edit any plan property (title, description, status, visibility, metadata)
+- `update_node` — edit any node property except status (status routes through `update_task`)
+- `move_node` — reparent within the same plan; cycle-safe
+- `link_intentions` — create a dependency edge between two existing tasks
+- `unlink_intentions` — remove a dependency edge by id
+- `delete_plan` — soft-delete via `status='archived'`; recoverable
+- `delete_node` — soft-delete via `status='archived'`
+
+**Sharing and collaboration (v1.0):**
+- `share_plan` — atomic visibility change + add/remove collaborators
+- `invite_member` — add user to organization (by user_id or email)
+- `update_member_role` — owner-only role change within an org
+- `remove_member` — owner/admin can remove non-owner members
+
 ### Utility
 
 - `get_started` — dynamic reference; call this if you're new to AgentPlanner
@@ -94,6 +116,131 @@ The `update_task` call is atomic — status change, log entry, claim release, an
 4. release_task(task_id, message='handoff to teammate') for explicit handoff
 ```
 
+### Peeking before claiming (v0.9.1+)
+
+Pass `dry_run: true` to `claim_next_task` to see the candidate without claiming. Useful when an agent wants to inspect the next task and decide whether to take it, without leaving a phantom claim if it bails.
+
+```
+claim_next_task({ scope: { plan_id }, dry_run: true })
+// → returns { candidate, source, claim: null, dry_run: true }
+// Then claim for real:
+claim_next_task({ scope: { plan_id } })  // dry_run defaults to false
+```
+
+### Proposing subtasks for human approval (v0.9.1+)
+
+For high-touch proposals (entire new directions, structural changes the human should review before they materialize), use `queue_decision` with `proposed_subtasks` — tasks only get created on `resolve_decision({action: 'approve'})`.
+
+```
+queue_decision({
+  plan_id: '<plan>',
+  title: 'Approve adding 3 launch tasks?',
+  context: 'Found gap in launch goal — no Product Hunt subtasks exist yet',
+  smallest_input_needed: 'approve|defer|reject',
+  proposed_subtasks: [
+    { parent_id: '<phase-id>', title: 'Draft PH listing copy', node_type: 'task' },
+    { parent_id: '<phase-id>', title: 'Set up PH preview', node_type: 'task' },
+    { parent_id: '<phase-id>', title: 'Schedule launch day', node_type: 'task' }
+  ]
+})
+// On resolve_decision({ action: 'approve' }), the 3 tasks are atomically created
+// and their IDs returned in created_subtasks[]. Defer/reject does nothing.
+```
+
+For routine decomposition (a task you're working on needs subtasks), use `extend_intention` directly — no decision queue, no friction.
+
+## The human-steering loop (v1.0)
+
+v1.0 closes the creation gap. There are three distinct flows depending on who initiated the action:
+
+### Scenario A: Human directs you in conversation
+
+User says "create a plan to ship the new auth flow under the security goal" or "mark the BSL launch plan completed."
+
+Default to **`status='active'`** — the human asked for it, just do it.
+
+```
+form_intention({
+  goal_id: '<security-goal-id>',
+  title: 'Ship new auth flow',
+  rationale: 'User-requested plan to migrate auth to passkeys',
+  tree: [
+    { node_type: 'phase', title: 'Discovery', children: [...] },
+    { node_type: 'phase', title: 'Implementation', children: [...] },
+  ]
+})
+// Plan lands as active. No approval needed — user already approved by asking.
+```
+
+```
+update_plan({ plan_id: '<bsl-plan>', status: 'completed' })
+// Done. No queue, no UI trip.
+```
+
+### Scenario B: You're acting autonomously (scheduled loop, etc.)
+
+No explicit human direction. You decided the workspace needs new structure.
+
+Pass **`status='draft'`** — let the human see what you proposed before it activates.
+
+```
+derive_subgoal({
+  parent_goal_id: '<launch-goal>',
+  title: 'First 3 paying customers',
+  rationale: 'Goal is at_risk — need a concrete intermediate target before broader push',
+  status: 'draft',
+})
+// Surfaces in dashboard pending. Human approves via update_goal({status: 'active'})
+// or in the UI. Plans auto-promote to active when first task moves to in_progress.
+```
+
+### Scenario C: You're uncertain and want explicit input
+
+Genuine ambiguity. Use `queue_decision`.
+
+```
+queue_decision({
+  title: 'Two conflicting facts about pricing',
+  context: 'Memory says $19/mo Pro tier; recent decision log says $29/mo. Which is current?',
+  smallest_input_needed: 'pick one',
+  options: [{ label: '$19' }, { label: '$29' }],
+  urgency: 'normal',
+})
+```
+
+The decision queue is for genuine uncertainty, not as a default gate on everything you do.
+
+## Editing structure (v1.0)
+
+These are routine — call them whenever needed. No decision-queue ceremony.
+
+| Want to... | Call |
+|---|---|
+| Rename a plan | `update_plan({plan_id, title})` |
+| Rename a task | `update_node({node_id, title})` |
+| Edit task instructions | `update_node({node_id, agent_instructions})` |
+| Move a task under a different phase | `move_node({node_id, new_parent_id})` |
+| Express B blocks A | `link_intentions({from_task_id: A, to_task_id: B, relation: 'blocks', rationale: '...'})` |
+| Remove a stale dep | `unlink_intentions({dependency_id, plan_id})` |
+| Archive a plan | `delete_plan({plan_id, reason})` |
+| Archive a task | `delete_node({node_id})` |
+| Restore an archived plan | `update_plan({plan_id, status: 'active', restore: true})` |
+
+`delete_*` is soft delete (sets `status='archived'`) — fully recoverable. Hard delete stays REST + admin-only on purpose; agents shouldn't be able to permanently destroy data.
+
+## Sharing and collaboration (v1.0)
+
+| Want to... | Call |
+|---|---|
+| Make a plan public | `share_plan({plan_id, visibility: 'public'})` |
+| Add a collaborator (by user_id) | `share_plan({plan_id, add_collaborators: [{user_id, role: 'editor'}]})` |
+| Remove a collaborator | `share_plan({plan_id, remove_collaborators: [user_id]})` |
+| Invite someone to the org | `invite_member({organization_id, email})` (or by `user_id`) |
+| Promote member to admin | `update_member_role({organization_id, membership_id, new_role: 'admin'})` |
+| Remove a member | `remove_member({organization_id, membership_id, reason})` |
+
+Email-based collaborator invites stay UI-only; `share_plan` accepts user_ids only. The dedicated `invite_member` call accepts email for org-level invites.
+
 ## Goal coaching
 
 When a user expresses intent — "I want to launch a feature", "we need better testing" — coach them into a structured goal before creating it.
@@ -159,18 +306,10 @@ recall_knowledge({
 
 `result_kind` options: `'facts'`, `'entities'`, `'episodes'`, `'all'`. Default is `'all'` — narrow it to control payload size.
 
-## Migrating from v0.8.x
-
-v0.9.0 is a breaking release. The old 63-tool surface is gone. See [MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping. Highlights:
-
-- `check_goals_health` + `get_my_tasks` + `get_recent_episodes` + `check_coherence_pending` → `briefing`
-- `quick_status` + `add_log` + `release_task` → `update_task`
-- `suggest_next_tasks` + `claim_task` + `get_task_context` → `claim_next_task`
-- `add_learning(entry_type='decision')` → `queue_decision` (real decision queue, not knowledge graph)
-- `get_goal` + `goal_path` + `goal_progress` + `assess_goal_quality` → `goal_state`
-- `recall_knowledge` + `find_entities` + `get_recent_episodes` + `check_contradictions` → `recall_knowledge`
+## Migration history
 
-CRUD-shaped admin tools (`create_node`, `update_plan`, `delete_*`) are removed in v0.9.0. They return as `ap_admin_*` namespace in v1.0.0. Use the AgentPlanner REST API directly if you need them now.
+- **v0.8.x → v0.9.0** — clean break. 63 legacy CRUD tools collapsed into 15 BDI-aligned tools. See [docs/MIGRATION_v0.9.md](docs/MIGRATION_v0.9.md) for the full mapping.
+- **v0.9.x → v1.0.0** — additive. v0.9 read/update tools unchanged. Adds the full mutation surface (creation, structural edits, sharing, collaboration) so humans can steer entirely through agent conversation. The previously planned `ap_admin_*` namespace is no longer needed — those operations are now first-class BDI tools, with the draft-status seam keeping autonomous agent creation reviewable. See [docs/MIGRATION_v1.0.md](docs/MIGRATION_v1.0.md).
 
 ## Principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-planner-mcp",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "MCP server for AgentPlanner — AI agent orchestration with planning, dependencies, knowledge graphs, and human oversight",
   "main": "src/index.js",
   "bin": {

package/src/tools/bdi/desires.js

@@ -1,8 +1,9 @@
 /**
  * BDI desires — goal management.
  *
- * 2 tools: list_goals (with health rollup), update_goal (atomic, subsumes
- * link/unlink and achiever changes).
+ * 3 tools: list_goals (with health rollup), update_goal (atomic, subsumes
+ * link/unlink and achiever changes), derive_subgoal (propose a sub-goal
+ * under an existing parent; mandatory parent — top-level goals stay UI-only).
  */
 
 const { asOf, formatResponse, errorResponse, safeArray } = require('./_shared');
@@ -154,10 +155,110 @@ async function updateGoalHandler(args, apiClient) {
   return formatResponse({ as_of: asOf(), goal_id, applied_changes: applied, failures, goal });
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// derive_subgoal — propose a sub-goal under an existing parent.
+// Top-level goals stay UI-only (strategic direction is human-set).
+// ─────────────────────────────────────────────────────────────────────────
+
+const VALID_GOAL_TYPES = ['outcome', 'constraint', 'metric', 'principle'];
+const VALID_STATUSES = ['draft', 'active', 'achieved', 'paused', 'abandoned', 'archived'];
+
+const deriveSubgoalDefinition = {
+  name: 'derive_subgoal',
+  description:
+    "Propose a sub-goal under an existing parent goal. parent_goal_id is " +
+    "mandatory — agents cannot create top-level goals (strategic direction is " +
+    "human-set). Defaults to status='active' for human-directed creation; pass " +
+    "status='draft' for autonomous loops so a human can review before promotion. " +
+    "Drafts surface in the dashboard pending queue.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      parent_goal_id: {
+        type: 'string',
+        description: "Required. The parent goal this sub-goal contributes to.",
+      },
+      title: { type: 'string' },
+      description: { type: 'string', description: "Optional extended description, appended after rationale." },
+      rationale: {
+        type: 'string',
+        description: "Why this sub-goal is needed to achieve the parent. Becomes the description; surfaces in human review.",
+      },
+      type: {
+        type: 'string',
+        enum: VALID_GOAL_TYPES,
+        default: 'outcome',
+      },
+      status: {
+        type: 'string',
+        enum: VALID_STATUSES,
+        default: 'active',
+        description: "Default 'active' for human-directed creation. Pass 'draft' when acting autonomously without explicit user direction.",
+      },
+      success_criteria: {
+        type: 'array',
+        items: { type: 'string' },
+        description: "Concrete, observable conditions that mark this sub-goal achieved.",
+      },
+      priority: { type: 'integer', default: 0 },
+    },
+    required: ['parent_goal_id', 'title', 'rationale'],
+  },
+};
+
+async function deriveSubgoalHandler(args, apiClient) {
+  const { parent_goal_id, title, description, rationale, type = 'outcome', status = 'active', success_criteria, priority } = args;
+
+  // Verify parent exists and inherit organization scope.
+  let parent;
+  try {
+    parent = await apiClient.goals.get(parent_goal_id);
+  } catch (err) {
+    return errorResponse('not_found', `Parent goal ${parent_goal_id} not found or not accessible: ${err.message}`);
+  }
+
+  // Compose description: rationale is primary; optional description appended.
+  const composedDescription = description
+    ? `${rationale}\n\n${description}`
+    : rationale;
+
+  const payload = {
+    title,
+    description: composedDescription,
+    type,
+    status,
+    parentGoalId: parent_goal_id,
+    organizationId: parent.organization_id || parent.organizationId || undefined,
+  };
+  if (success_criteria) payload.successCriteria = { criteria: success_criteria };
+  if (typeof priority === 'number') payload.priority = priority;
+
+  let goal;
+  try {
+    goal = await apiClient.goals.create(payload);
+  } catch (err) {
+    const upstream = err.response?.data?.error || err.message;
+    return errorResponse('create_failed', `Failed to create sub-goal: ${upstream}`);
+  }
+
+  return formatResponse({
+    as_of: asOf(),
+    goal_id: goal.id,
+    parent_goal_id,
+    title: goal.title,
+    status: goal.status,
+    is_draft: goal.status === 'draft',
+    next_step: goal.status === 'draft'
+      ? "Sub-goal created as draft. It will surface in the dashboard pending queue for human review. Promote via update_goal({status: 'active'}) once approved."
+      : "Sub-goal active. Link plans to it via update_goal({add_linked_plans: [...]}).",
+  });
+}
+
 module.exports = {
-  definitions: [listGoalsDefinition, updateGoalDefinition],
+  definitions: [listGoalsDefinition, updateGoalDefinition, deriveSubgoalDefinition],
   handlers: {
     list_goals: listGoalsHandler,
     update_goal: updateGoalHandler,
+    derive_subgoal: deriveSubgoalHandler,
   },
 };