Missing activity events
Use this guide when installation appears successful but Activity does not show the runtime events you expected.
Use this guide when installation appears successful but Activity does not show the runtime events you expected.
Start with the symptom. Do not debug identity, groups, or policies until live runtime delivery is confirmed.
Fast split
| What you see | Meaning | First action |
|---|---|---|
| Managed macOS PKG installed, no workstation | The package installed but profile delivery, token staging, or enrollment did not finish | Run the package status helper; require enrollment_state=enrolled and a valid credential before debugging Activity |
| No workstation and no system event on a standalone install | AgentKeeper never received check-in | Check origin, credential, and outbound HTTPS |
| Workstation appears, no Activity rows | Registration worked; the live hook may not have fired, reached evaluation, or received persistence acknowledgment | Restart the agent, run a real preflight action, and compare the Windows runtime, evaluate, and Activity markers |
| Self-test rows only | Local hook can reach AgentKeeper, but the agent has not loaded the hook | Fully quit and relaunch the agent, then start a new session |
| BLOCK appears, PASS missing | Enforcement is working, full audit logging may be off | Enable Log All Tool Calls for the policy that applies to the host |
| Events appear under another source | The wrong integration is being viewed | Filter by claude_code, claude_chat, cowork, cursor, codex, gemini, windsurf, mcp_gateway, or openai_compliance_api |
| Events appear in the wrong org | User is authenticated into a different organization | Check invite, SSO domain, and role |
Triage order
- Confirm the dashboard origin matches the install origin.
- Filter Activity by the expected source and host.
- Confirm the agent was fully restarted after install.
- Run the relevant status helper and confirm self-test delivery.
- Run a real tool action and confirm live delivery markers update.
- Run a known blocked action and confirm BLOCK appears.
- Only then check person mapping, groups, policy packs, and directory sync.
Claude Code
Symptoms
| Symptom | Likely cause | Fix |
|---|---|---|
/hooks does not show AgentKeeper on macOS MDM | The universal runtime is not enrolled, reconciliation was blocked, or Claude Code has not restarted | Run the package status helper and require enrollment_state=enrolled, hook_matrix.config_json=true, and a valid credential. Then run the package remediation helper and fully restart Claude Code. |
HTTP 407 appears for AgentKeeper evaluate or audit hooks | A stale AgentKeeper native type: "http" hook is still in ~/.claude/settings.json and Claude Code is sending it through a local authenticated proxy before it reaches AgentKeeper | Rerun the current macOS MDM Claude Code remediation, remove only AgentKeeper type: "http" hook entries if immediate manual repair is needed, fully restart Claude Code, and confirm only AgentKeeper command hooks remain |
SessionStart marker missing | Claude Code has not started a new session since install | Quit and restart Claude Code, then start a session |
| Inventory empty but Activity has events | Runtime hooks are working, but SessionStart inventory has not run or cannot find config | Run agentkeeper-mcp-gateway scan-inventory --dry-run < /dev/null and restart Claude Code |
| Windows status self-test fails | Runtime hook forwarder, state dir ACL, config, or outbound HTTPS is broken | Read C:\ProgramData\AgentKeeper\State\last-evaluate.json and rerun Intune remediation |
| macOS status looks healthy but no live events | Claude Code was already running when hooks changed | Fully restart Claude Code |
Windows markers
When a Windows hook fails, the status script writes proof markers under:
C:\ProgramData\AgentKeeper\State
Useful files:
Get-Content "C:\ProgramData\AgentKeeper\State\last-runtime-hook.json" | ConvertFrom-Json
Get-Content "C:\ProgramData\AgentKeeper\State\last-evaluate.json" | ConvertFrom-Json
Get-Content "C:\ProgramData\AgentKeeper\State\last-activity.json" | ConvertFrom-Json
Get-Content "C:\ProgramData\AgentKeeper\State\last-checkin.json" | ConvertFrom-Json
last-runtime-hook.json proves the local command hook started. last-evaluate.json records the latest real preflight request result and its policy-fetch health. last-activity.json changes only when AgentKeeper returns a structurally valid event ID with an explicit persisted acknowledgment, so it is the local proof that an Activity row exists. A self-test, duplicate, disabled PASS logging, malformed ID, or later request failure does not overwrite it. last-checkin.json proves the SessionStart wrapper registered the workstation.
Claude Desktop Cowork
Cowork has the most common false-positive install state: self-test succeeds, but live Cowork has not loaded the plugin.
Required sequence
- Install the Cowork hook.
- Run the status self-test for the operating system.
- Fully quit Claude Desktop.
- Relaunch Claude Desktop.
- Start a new Cowork chat.
- Run a real tool action.
- Run status again without the self-test flag.
Healthy live status shows updated live markers, not only self-test markers.
Common Cowork causes
| Symptom | Likely cause | Fix |
|---|---|---|
| Status says no workspaces | Cowork has not been opened on that machine | Open Claude Desktop, start Cowork once, then rerun the installer |
| Manifest hooks missing | Old plugin cache or stale installer | Rerun the installer, then fully quit and relaunch Claude Desktop |
| Self-test succeeds, live activity missing | Claude Desktop did not load the local plugin for the active session | Upload the AgentKeeper Cowork plugin ZIP or install it from Claude organization plugin settings, then restart |
Windows plugin shows /bin/sh or pre-tool-hook.sh | The macOS/Linux Cowork artifact or stale plugin cache is loaded on Windows | Install or upload agentkeeper-cowork-guardrail-windows.zip; Windows hooks must run powershell.exe and hook.ps1 |
| Live hook marker updates but no Activity row | Request failed after the hook started | Inspect ~/.agentkeeper/cowork-evaluate-last-run.json |
| Tool call uses Bedrock | Bedrock changes model routing, not the local Cowork hook mechanism | Validate plugin loading and live markers. Connectivity is not the issue if self-test reaches AgentKeeper |
On Windows, use cowork-windows-status.ps1. The Cowork hook marker files live under the signed-in developer profile at:
%USERPROFILE%\.agentkeeper
The live marker must come from a real Cowork action. A marker with self_test=True, self_test_source, or a session_id such as cowork-windows-self-test-... proves only that the helper script can reach AgentKeeper.
If Microsoft Store opens during install, the wrong installer path was used. Windows can open Store prompts when it is asked to resolve python, python3, bash, or WSL from a macOS/Linux command. Re-run the Windows PowerShell installer instead.
Claude Desktop Chat
Claude Chat uses MCP Gateway through Claude Desktop configuration. A Gateway install can be healthy while Claude Desktop has not loaded the routed MCP config yet.
Required sequence
- Install AgentKeeper MCP Gateway.
- Run
agentkeeper-mcp-gateway configure-ide --ide=claude-desktop. - Fully quit Claude Desktop.
- Relaunch Claude Desktop.
- Ask Chat to use a configured MCP tool.
- Run
agentkeeper-mcp-gateway list --health.
configure-ide writes agentkeeper-mcp-gateway server into Claude Desktop MCP config. The restarted client launches Gateway during real MCP tool use.
On Windows, run the installer elevated or through Intune/SYSTEM, then run the configure command from the signed-in developer profile:
& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' configure-ide --ide=claude-desktop
Common Chat causes
| Symptom | Likely cause | Fix |
|---|---|---|
| Gateway check-in appears, but Chat has no tool events | Claude Desktop has not restarted or no routed MCP tool call has run | Quit Claude Desktop fully, relaunch Claude Desktop, trigger a Chat MCP tool, then run list --health |
| Windows install succeeds, but Claude Desktop config is unchanged | Configure ran as SYSTEM or an elevated admin instead of the signed-in Claude user | Run the configure command from the developer's normal PowerShell profile |
| Chat shows no MCP tools | claude_desktop_config.json was not rewritten or contains invalid JSON | Run configure-ide --ide=claude-desktop --dry-run, then reapply and restart Claude Desktop |
Activity shows only mcp_gateway | Older Gateway build did not stamp the Chat source | Upgrade Gateway and confirm Activity after a fresh Chat tool call |
PASS versus BLOCK
BLOCK events prove enforcement. PASS events are shown when the relevant runtime policy logs all tool calls.
If a customer says "blocking works but I do not see normal activity," check:
- Base Policy or policy pack has Log All Tool Calls enabled.
- The workstation is in the expected policy audience.
- The event source filter is not hiding PASS rows.
- The action happened after the policy was saved.
Hook-based runtime policy changes apply on the next supported agent evaluation.
Escalation packet
Collect these fields before escalation:
- User email.
- Organization.
- Hostname.
- Operating system.
- Agent source.
- Dashboard URL being viewed.
- Install origin used.
- Status helper output.
- Latest local marker files, with secrets redacted.
- Whether self-test, live event, PASS, and BLOCK each passed.
- Screenshot or copy of the newest Activity rows for the host.