feat(FN-4488): complete Step 7 — docs and changeset

Fusion-Task-Id: FN-4488
Fusion-Task-Lineage: 3fc1ac43-490f-43f2-a27e-4fdceb64d9c4

.changeset/fn-4488-agent-permission-policies.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Add editable agent permission policies with project defaults and per-agent overrides, including per-category action-gate dispositions across git writes, file writes/deletes, command execution, network/API, and task/agent mutation.

docs/agents.md

@@ -1402,3 +1402,24 @@ POST /api/agents/:id/ratings
 - [Workflow Steps](./workflow-steps.md)
 - [Settings Reference](./settings-reference.md)
 - [Architecture](./architecture.md)
+
+## Permission Policies
+
+Permanent-agent sensitive actions are gated across five categories:
+- `git_write`
+- `file_write_delete`
+- `command_execution`
+- `network_api`
+- `task_agent_mutation`
+
+Each category can be set to one disposition:
+- `allow`
+- `require-approval`
+- `block`
+
+Precedence:
+1. Per-agent permission policy override (Agent Detail → Settings → Permissions)
+2. Project default permission policy (`defaultAgentPermissionPolicy` in Project Settings → Agent Permissions)
+3. Built-in fallback preset (`unrestricted` / allow-all)
+
+Per-agent rows can inherit project defaults category-by-category.

docs/settings-reference.md

@@ -1144,3 +1144,25 @@ Fusion supports scoped automations and routines:
 **Settings that interact with scheduling:**
 - `autoBackupEnabled` / `autoBackupSchedule` — Backup automation respects scope like any other scheduled task.
 - `insightExtractionEnabled` / `insightExtractionSchedule` — Insight extraction can be configured as global or project-scoped.
+
+### `defaultAgentPermissionPolicy`
+
+Project-scoped default permission policy for permanent-agent action gates.
+
+```json
+{
+  "defaultAgentPermissionPolicy": {
+    "rules": {
+      "git_write": "require-approval",
+      "command_execution": "require-approval",
+      "network_api": "block"
+    }
+  }
+}
+```
+
+- `rules` is a partial map of category → disposition.
+- Categories: `git_write`, `file_write_delete`, `command_execution`, `network_api`, `task_agent_mutation`.
+- Dispositions: `allow`, `require-approval`, `block`.
+- Missing categories default to `allow` via the built-in `unrestricted` seed.
+- Per-agent overrides take precedence over this project default.