Trace a request with the hook debug log

Start with the local hook debug log when an approval or event does not appear. It shows whether the agent fired an Agent Approve hook, what the hook prepared, whether the API answered, and which result returned to the agent.

The log stays on your computer at ~/.agentapprove/hook-debug.log. It is off by default.

Enable the log

Open ~/.agentapprove/env in a text editor and set:

AGENTAPPROVE_DEBUG_LOG=true

Start a new agent session, then ask the agent to perform one harmless action that you can identify by time. Some plugin-based agents need to be restarted before they reload local configuration.

Watch new entries in a terminal:

tail -f ~/.agentapprove/hook-debug.log

Press Control-C when the test is complete. You can also open the file in a text editor or use:

less ~/.agentapprove/hook-debug.log

The file is created with owner-only permissions. It rotates after it grows past 5 MB and keeps the most recent portion.

Treat the log as private

Debug logging records raw hook input on your computer. It can contain commands, paths, prompts, tool arguments, output, and other private work. It also records the outgoing request structure and response diagnostics.

Do not attach the complete log to a public issue. Copy only the short, redacted section around one test. Remove tokens, authorization values, pairing material, private paths, command content, prompts, and customer data.

Trace the request one step at a time

1. Did the agent fire a hook?

Look for a new entry with the time of your test and the hook name.

If nothing is added:

• Run npx agentapprove status and confirm the agent is installed.
• Check the agent's hook or plugin settings. Confirm the Agent Approve entry is enabled and approve it if the agent requires confirmation.
• Start a new session or quit and reopen the native agent app.
• Rerun npx agentapprove install if the configuration is missing.

If the agent reports an invalid hook configuration after an agent update, send the agent version and redacted error to Support. The agent may have changed its configuration format.

2. Did the hook prepare and send the event?

The log marks raw input and the request sent to Agent Approve. With end-to-end encryption on, the outgoing JSON should contain encrypted e2e fields instead of plaintext command or tool content. The raw input section can still show plaintext because it records what the local agent passed to its local hook.

If the hook reports missing configuration, a token problem, or unavailable encryption keys, run npx agentapprove status. Use npx agentapprove refresh for an access-token problem or npx agentapprove pair when pairing or encryption keys also need repair.

3. Did the Agent Approve API answer?

The response diagnostics distinguish a successful response from an authorization rejection, rate limit, service error, timeout, empty body, or invalid response.

If the request cannot reach Agent Approve, check status.agentapprove.com. The computer then applies its configured offline fallback.

A response that says the subscription expired means the hooks are installed, but the account is no longer entitled. Open the iOS app, confirm the subscription on the Connection screen, and renew if needed. An authorization error after account closure means the remaining computer installation should be removed or paired to an active account.

4. What did policy decide?

A successful API response can approve, deny, or ask for a human decision. Not every action should appear as a manual approval:

• A Deny List match is denied automatically.
• An Allow List match is approved automatically.
• A policy with Allow by Default or Deny by Default handles unmatched actions automatically.
• A policy with Ask sends unmatched actions to your devices.

Check the active policy and lists before treating a missing prompt as a delivery failure.

5. Did the request reach the iPhone?

If the log shows that the request was sent and the hook is waiting for a manual decision, but nothing appears on the phone:

1. Open Agent Approve and check the cloud icon. Confirm you are signed in and connected.
2. Confirm the Connection screen shows an active trial or subscription.
3. Leave the app open and repeat the harmless test. A live connection can show the request while the app is active.
4. Enable iOS notifications so the request can alert you while the app is in the background.

If requests appear only while the app is open, continue with Push notification did not arrive.

Turn the log off

After the test, set this entry back to false:

AGENTAPPROVE_DEBUG_LOG=false

Keeping debug logging off reduces local collection of raw agent input. You can remove old local logs when you no longer need them.

If the trace still does not identify the failure, follow Collect a safe support report and contact Support.