feat(FN-3547): add runtime action classification and gating system for agen

Merged seven commits that introduce a runtime action gate for task execution (FN-3547) — adding action classification, git-based heuristics for branch/remote gating, and per-step session enforcement — with tests covering the gate logic, heartbeat integration, and PI agent creation. Also landed FN-37

Fusion-Task-Id: FN-3547

docs/agents.md

@@ -59,6 +59,36 @@ V1 runtime action categories:
 - `network-api`
 - `task-agent-management`
 
+### Runtime gate v1 mapping (per tool invocation, permanent agents only)
+
+The engine classifies each tool call with this precedence order (first match wins):
+
+1. `git-write`
+2. `file-write-delete`
+3. `task-agent-management`
+4. `network-api`
+5. `shell-command`
+6. exempt/read-only (`allow`)
+
+Current v1 mapping:
+
+- `file-write-delete`: `write`, `edit`
+- `task-agent-management`: `fn_task_create`, `fn_task_add_dep`, `fn_delegate_task`, `fn_update_agent_config`, `fn_update_identity`, `fn_spawn_agent`
+- `network-api`: `fn_research_run` (explicit tool-owned network/API surface only)
+- `shell-command`: non-git `bash`, and read-only git shell commands
+- `git-write`: mutating `bash` git commands
+
+`bash` git-write heuristic in v1:
+
+- Mutating git operations include: `git add`, `commit`, `merge`, `rebase`, `cherry-pick`, `am`, `apply`, `stash`, `tag`, `push`, `reset`, `rm`, `mv`, `clean`, `worktree add/remove`, `checkout -b`, `switch -c`, `pull --rebase`, `restore --staged`, and branch/remote mutation forms.
+- Read-only git operations include: `git status`, `diff`, `log`, `show`, `rev-parse`, `branch --show-current`, `branch` listing, and `remote -v`.
+
+Intentionally exempt in v1 (remain normal execution plumbing):
+
+- `fn_task_update`, `fn_task_log`, `fn_task_done`, `fn_task_document_write`, mailbox reads, memory reads, and other routine read-only inspection tools.
+
+For `require-approval` dispositions, execution is intercepted before side effects; the engine creates/reuses a pending approval request keyed by a deterministic dedupe key (`agentId + taskId + toolName + category + resourceType + resourceId + operation`).
+
 Default and legacy fallback behavior:
 
 - New **non-ephemeral/permanent** agents persist a normalized `permissionPolicy` using preset `unrestricted` when not explicitly provided.

docs/architecture.md

@@ -480,6 +480,13 @@ See [Memory Plugin Contract](./memory-plugin-contract.md) for the full plan.
 - `AgentRuntime` (`agent-runtime.ts`) — runtime adapter interface contract
 - `RuntimeResolution` (`runtime-resolution.ts`) — runtime selection and fallback logic
 - `AgentSessionHelpers` (`agent-session-helpers.ts`) — runtime-aware session creation helpers
+- `AgentActionGate` (`agent-action-gate.ts`) — permanent-agent runtime action classification + policy disposition decisions
+
+Runtime action-gate flow (v1):
+- Tool execution wrappers in `pi.ts` compose `wrapToolsWithBoundary()` and `wrapToolsWithActionGate()`.
+- Non-ephemeral agents receive `AgentActionGateContext` from executor/heartbeat session creation.
+- `block` and `require-approval` dispositions intercept before tool side effects.
+- `require-approval` persists durable requests via `ApprovalRequestStore`, reusing pending requests by dedupe key in `targetAction.context.approvalDedupeKey`.
 
 ### Concurrency, recovery, and resiliency
 - `AgentSemaphore` (`concurrency.ts`) — slot acquisition