feat(FN-4599): complete Step 1 — export approval gate tool metadata

Fusion-Task-Id: FN-4599
Fusion-Task-Lineage: 39bdbfd4-d90a-4232-a447-23ef107732e4

packages/core/src/__tests__/agent-permission-policy.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
+  AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES,
+  AGENT_PERMISSION_POLICY_EXEMPT_TOOL_EXAMPLES,
   DEFAULT_AGENT_PERMISSION_POLICY_PRESET_ID,
   getBuiltInAgentPermissionPolicyPresets,
   isAgentPermissionPolicyPresetId,
@@ -7,6 +9,10 @@ import {
   resolveEffectiveAgentPermissionPolicy,
 } from "../agent-permission-policy.js";
 import { AGENT_PERMISSION_POLICY_ACTION_CATEGORIES } from "../types.js";
+import {
+  ACTION_GATE_TASK_AGENT_MANAGEMENT_TOOLS,
+  COORDINATION_EXEMPT_TOOLS,
+} from "../../../engine/src/gating-classifications.js";
 
 describe("agent-permission-policy", () => {
   it("returns the canonical built-in preset catalog", () => {
@@ -68,4 +74,29 @@ describe("agent-permission-policy", () => {
     expect(isAgentPermissionPolicyPresetId("locked-down")).toBe(true);
     expect(isAgentPermissionPolicyPresetId("custom")).toBe(true);
   });
+
+  it("provides non-empty tool examples for every action category", () => {
+    for (const category of AGENT_PERMISSION_POLICY_ACTION_CATEGORIES) {
+      expect(AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES[category].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("includes key discoverability examples", () => {
+    expect(AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES.network_api).toContain("fn_research_run (web/research)");
+    expect(AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES.task_agent_mutation).toContain("fn_task_create");
+    expect(AGENT_PERMISSION_POLICY_EXEMPT_TOOL_EXAMPLES).toContain("fn_send_message");
+  });
+
+  it("keeps task-agent mutation examples aligned with action-gate tool classifications", () => {
+    for (const toolName of AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES.task_agent_mutation) {
+      expect(toolName.startsWith("fn_")).toBe(true);
+      expect(ACTION_GATE_TASK_AGENT_MANAGEMENT_TOOLS.has(toolName)).toBe(true);
+    }
+  });
+
+  it("keeps exempt examples aligned with coordination-exempt classifications", () => {
+    for (const toolName of AGENT_PERMISSION_POLICY_EXEMPT_TOOL_EXAMPLES) {
+      expect(COORDINATION_EXEMPT_TOOLS).toContain(toolName);
+    }
+  });
 });

packages/core/src/agent-permission-policy.ts

@@ -1,5 +1,6 @@
 import type {
   AgentPermissionPolicy,
+  AgentPermissionPolicyActionCategory,
   AgentPermissionPolicyDisposition,
   AgentPermissionPolicyPresetId,
   AgentPermissionPolicyRules,
@@ -8,6 +9,41 @@ import { AGENT_PERMISSION_POLICY_ACTION_CATEGORIES, AGENT_PERMISSION_POLICY_PRES
 
 export const DEFAULT_AGENT_PERMISSION_POLICY_PRESET_ID: AgentPermissionPolicyPresetId = "unrestricted";
 
+export const AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES: Record<
+  AgentPermissionPolicyActionCategory,
+  readonly string[]
+> = {
+  git_write: ["git commit", "git push", "git merge", "git branch -d", "git worktree add", "write", "edit"],
+  file_write_delete: ["write", "edit", "fn_task_attach"],
+  command_execution: ["bash (non-git)", "read", "find", "grep", "ls"],
+  network_api: ["fn_research_run (web/research)"],
+  task_agent_mutation: [
+    "fn_task_create",
+    "fn_delegate_task",
+    "fn_task_import_github",
+    "fn_task_import_github_issue",
+    "fn_spawn_agent",
+    "fn_update_agent_config",
+    "fn_update_identity",
+  ],
+};
+
+export const AGENT_PERMISSION_POLICY_EXEMPT_TOOL_EXAMPLES: readonly string[] = [
+  "fn_send_message",
+  "fn_post_room_message",
+  "fn_read_messages",
+  "fn_task_log",
+  "fn_task_done",
+  "fn_heartbeat_done",
+  "fn_task_document_write",
+  "fn_task_document_read",
+  "fn_memory_search",
+  "fn_memory_get",
+  "fn_memory_append",
+  "fn_read_evaluations",
+  "fn_reflect_on_performance",
+];
+
 export interface BuiltInAgentPermissionPolicyPreset {
   id: AgentPermissionPolicyPresetId;
   name: string;

packages/core/src/index.ts

@@ -61,6 +61,8 @@ export {
 } from "./agent-permissions.js";
 export {
   DEFAULT_AGENT_PERMISSION_POLICY_PRESET_ID,
+  AGENT_PERMISSION_POLICY_CATEGORY_TOOL_EXAMPLES,
+  AGENT_PERMISSION_POLICY_EXEMPT_TOOL_EXAMPLES,
   getBuiltInAgentPermissionPolicyPresets,
   resolveAgentPermissionPolicyPreset,
   normalizeAgentPermissionPolicyFromPreset,