@mastra/mcp-docs-server 1.1.49-alpha.1 → 1.2.0-alpha.0

package/.docs/docs/harness/tool-approvals.md

@@ -0,0 +1,141 @@
+# Tool approvals and permissions
+
+The Harness provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
+
+## Permission policies
+
+Three policies control tool behavior:
+
+- `allow`: The tool runs without prompting
+- `ask`: The tool pauses and emits a `tool_approval_required` event; the user must approve or decline
+- `deny`: The tool is blocked from execution
+
+### Setting policies
+
+Set policies per-category or per-tool. Per-tool policies take precedence over category policies:
+
+```typescript
+// Category-level: all execute tools require approval
+harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })
+
+// Tool-level: this specific tool is always blocked
+harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+```
+
+### Tool categories
+
+The `toolCategoryResolver` maps tool names to categories. Pass it to the Harness constructor:
+
+```typescript
+const harness = new Harness({
+  id: 'my-agent',
+  toolCategoryResolver: toolName => {
+    if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
+    if (toolName.includes('execute')) return 'execute'
+    return 'read'
+  },
+})
+```
+
+Built-in categories are `read`, `edit`, `execute`, `mcp`, and `other`.
+
+## Responding to approval requests
+
+When a tool's policy is `ask`, the Harness emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
+
+```typescript
+harness.subscribe(event => {
+  if (event.type === 'tool_approval_required') {
+    // Show approval UI...
+    harness.session.respondToToolApproval({ decision: 'approve' })
+  }
+})
+```
+
+The `decision` field accepts `'approve'`, `'decline'`, or `'always_allow_category'`. When `always_allow_category` is used, the tool's category is granted for the rest of the session. Future tools in the same category are auto-approved.
+
+```typescript
+harness.session.respondToToolApproval({ decision: 'always_allow_category' })
+```
+
+## Session grants
+
+The Harness owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/harness/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
+
+```typescript
+// Grant all edit tools for this session
+harness.session.grantCategory('edit')
+
+// Grant a specific tool
+harness.session.grantTool('mastra_workspace_execute_command')
+
+// Check current grants
+const grants = harness.session.getGrants()
+// { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
+```
+
+## Tool suspensions
+
+Interactive built-in tools (`ask_user`, `submit_plan`) use the native tool-suspension primitive instead of the approval flow. They emit a `tool_suspended` event with `toolCallId`, `toolName`, and `suspendPayload`. Resume with `respondToToolSuspension()`:
+
+```typescript
+harness.subscribe(event => {
+  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
+    const { question } = event.suspendPayload as { question: string }
+    // Show question to user, then resume:
+    harness.respondToToolSuspension({
+      toolCallId: event.toolCallId,
+      resumeData: 'User response here',
+    })
+  }
+})
+```
+
+### Plan approval
+
+The `submit_plan` tool suspends via the same mechanism. Resume with an `action` field:
+
+```typescript
+// Approve the plan
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'approved' },
+})
+
+// Reject with feedback
+harness.respondToToolSuspension({
+  toolCallId: event.toolCallId,
+  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
+})
+```
+
+## Built-in tools
+
+The Harness provides these built-in tools to agents in every mode:
+
+| Tool            | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `ask_user`      | Ask the user a question (free text, single-select, or multi-select) |
+| `submit_plan`   | Submit a plan for user review and approval                          |
+| `task_write`    | Create or replace a structured task list                            |
+| `task_update`   | Update one tracked task by ID                                       |
+| `task_complete` | Mark one tracked task completed                                     |
+| `task_check`    | Check task list completion status                                   |
+| `subagent`      | Spawn a focused subagent (requires `subagents` config)              |
+
+Disable specific built-in tools with `disableBuiltinTools`:
+
+```typescript
+const harness = new Harness({
+  id: 'no-plans',
+  disableBuiltinTools: ['submit_plan'],
+})
+```
+
+## Related
+
+- [Harness overview](https://mastra.ai/docs/harness/overview)
+- [Session](https://mastra.ai/docs/harness/session)
+- [Subagents](https://mastra.ai/docs/harness/subagents)
+- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [API reference](https://mastra.ai/reference/harness/harness-class)