Coding hooks MDM payloads (macOS)

This page is the copy and paste contract for machine-wide coding-agent hooks deployed by MDM or configuration management. The Pathfinder agent installer writes the same managed provider files by default for rollout convenience. To stop it, set managed_autoinstall = false under [hooks] in /etc/pathfinder/agent.toml on the Mac, and deliver the files below instead. See macOS enrollment plist.

Managed hook payloads intentionally do not bake in PATHFINDER_DATA_DIR. Each user session resolves its own Pathfinder agent data directory when the hook fires, and every verdict comes from the local Pathfinder agent service.

The managed hook command path in these payloads is /Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent. Deploy the Pathfinder agent package first, or deploy these payloads in the same MDM sequence after that binary exists.

Recommended ownership on macOS: root-owned directories with 0755 permissions and root-owned configuration files with 0644 permissions, so coding agents that users launch can read them.

Managed File Paths

Provider	Ship this file	Raw payload command
Claude Code	`/Library/Application Support/ClaudeCode/managed-settings.json`	`pathfinder-agent hook install --provider claude --print`
Codex	`/Library/Application Support/Codex/requirements.toml`	`pathfinder-agent hook install --provider codex --print`
Cursor	`/Library/Application Support/Cursor/hooks.json`	`pathfinder-agent hook install --provider cursor --print`
GitHub Copilot	`/etc/github-copilot/policy.d/pathfinder.json`	`pathfinder-agent hook install --provider copilot --print`

Claude Code

Ship to: /Library/Application Support/ClaudeCode/managed-settings.json

Generate this payload directly with:

pathfinder-agent hook install --provider claude --print

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "pre-tool-use"
            ]
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "post-tool-use"
            ]
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "post-tool-use-failure"
            ]
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "user-prompt-submit"
            ]
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "session-start"
            ]
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "session-end"
            ]
          }
        ]
      }
    ],
    "SubagentStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "subagent-start"
            ]
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "subagent-stop"
            ]
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "pre-compact"
            ]
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "notification"
            ]
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "stop-failure"
            ]
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "post-compact"
            ]
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "stop"
            ]
          }
        ]
      }
    ],
    "PermissionDenied": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "permission-denied"
            ]
          }
        ]
      }
    ],
    "UserPromptExpansion": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent",
            "args": [
              "hook",
              "--agent-type",
              "claude-code",
              "event",
              "user-prompt-expansion"
            ]
          }
        ]
      }
    ]
  }
}

Codex

Ship to: /Library/Application Support/Codex/requirements.toml

Generate this payload directly with:

pathfinder-agent hook install --provider codex --print

[hooks]

[[hooks.PreToolUse]]
matcher = ".*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event PreToolUse"

[[hooks.PostToolUse]]
matcher = ".*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event PostToolUse"

[[hooks.UserPromptSubmit]]
matcher = ".*"

[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event UserPromptSubmit"

[[hooks.SessionStart]]
matcher = ".*"

[[hooks.SessionStart.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event SessionStart"

[[hooks.SessionEnd]]
matcher = ".*"

[[hooks.SessionEnd.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event SessionEnd"

[[hooks.SubagentStart]]
matcher = ".*"

[[hooks.SubagentStart.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event SubagentStart"

[[hooks.SubagentStop]]
matcher = ".*"

[[hooks.SubagentStop.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event SubagentStop"

[[hooks.PreCompact]]
matcher = ".*"

[[hooks.PreCompact.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event PreCompact"

[[hooks.PostCompact]]
matcher = ".*"

[[hooks.PostCompact.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event PostCompact"

[[hooks.Stop]]
matcher = ".*"

[[hooks.Stop.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event Stop"

[[hooks.PermissionRequest]]
matcher = ".*"

[[hooks.PermissionRequest.hooks]]
type = "command"
command = "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type codex event PermissionRequest"

[features]
hooks = true

Cursor

Ship to: /Library/Application Support/Cursor/hooks.json

Generate this payload directly with:

pathfinder-agent hook install --provider cursor --print

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event sessionStart",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "sessionEnd": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event sessionEnd",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "preToolUse": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event preToolUse",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "postToolUse": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event postToolUse",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "postToolUseFailure": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event postToolUseFailure",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "subagentStart": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event subagentStart",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "subagentStop": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event subagentStop",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "beforeSubmitPrompt": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event beforeSubmitPrompt",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "preCompact": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event preCompact",
        "matcher": "*",
        "timeout": 30
      }
    ],
    "stop": [
      {
        "command": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type cursor event stop",
        "matcher": "*",
        "timeout": 30
      }
    ]
  }
}

GitHub Copilot

Ship to: /etc/github-copilot/policy.d/pathfinder.json

Generate this payload directly with:

pathfinder-agent hook install --provider copilot --print

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event preToolUse",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event preToolUse",
        "timeoutSec": 30
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event postToolUse",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event postToolUse",
        "timeoutSec": 30
      }
    ],
    "postToolUseFailure": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event postToolUseFailure",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event postToolUseFailure",
        "timeoutSec": 30
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event userPromptSubmitted",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event userPromptSubmitted",
        "timeoutSec": 30
      }
    ],
    "userPromptTransformed": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event userPromptTransformed",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event userPromptTransformed",
        "timeoutSec": 30
      }
    ],
    "sessionStart": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event sessionStart",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event sessionStart",
        "timeoutSec": 30
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event sessionEnd",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event sessionEnd",
        "timeoutSec": 30
      }
    ],
    "agentStop": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event agentStop",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event agentStop",
        "timeoutSec": 30
      }
    ],
    "subagentStart": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event subagentStart",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event subagentStart",
        "timeoutSec": 30
      }
    ],
    "subagentStop": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event subagentStop",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event subagentStop",
        "timeoutSec": 30
      }
    ],
    "permissionRequest": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event permissionRequest",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event permissionRequest",
        "timeoutSec": 30
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event errorOccurred",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event errorOccurred",
        "timeoutSec": 30
      }
    ],
    "preCompact": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event preCompact",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event preCompact",
        "timeoutSec": 30
      }
    ],
    "notification": [
      {
        "type": "command",
        "bash": "'/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event notification",
        "powershell": "& '/Applications/PathfinderEnforcement.app/Contents/Resources/pathfinder-agent' hook --agent-type copilot event notification",
        "timeoutSec": 30
      }
    ]
  }
}