Agent pauses, no inbox item

The agent stopped waiting for input. But /inbox is empty. The hook bridge didn't fire.

Symptom

Your agent (Claude Code, Codex, Aider, Gemini) hit a permission prompt or generated a plan, but the web app's /inbox has nothing. The agent is stuck at its native prompt. Typing in the terminal would unblock it, but the whole point was to decide remotely.

Root cause: the hook bridge isn't catching the event

Each agent fires session events through its hook system. The Viewport daemon listens on a local Unix socket. If the hook isn't installed or is misconfigured, events don't reach the daemon, and nothing gets shipped to the platform.

Fix

1. Confirm the hook is installed

vpd install

You should see something like:

[+] claude-code found at /usr/local/bin/claude
[+] Installing Claude Code hook... installed at ~/.claude/hooks/viewport.json

If you see [-] not found, the agent binary isn't on PATH where the daemon expects it. Make sure which claude (or whichever agent) returns a path.

2. Confirm the hook is firing

cd ~/some-repo
claude --message "what's in this repo"

In a separate terminal:

vpd logs --follow --since 1m

You should see session-started immediately. If you don't, the hook isn't reaching the daemon.

Common causes:

Hook file is there but not enabled. For Claude Code, check ~/.claude/config.json and confirm the hook entry exists and is enabled.
Daemon socket is at a non-default location. If you set VIEWPORT_HOME or VPD_HOME, the hook needs to know. Re-run vpd install after setting these.
SELinux / AppArmor blocking. Uncommon, but on hardened Linux the hook's socket write may be denied. Check dmesg for AVCs.

3. Confirm the directory is recognized

The daemon only announces sessions in registered directories.

vpd list

If the working directory isn't listed:

vpd add ~/your-repo

Then re-run the agent.

4. Confirm the workflow requires an inbox item

Some workflows don't require human review. If the workflow node says "auto-approve always," no inbox item is created. The agent just continues.

Check the workflow definition:

vpd config resolve | grep -A 20 your-workflow

Or inspect in the web app: /workflows/{workflow-id} shows the node definitions.

5. Self-hosted relay specific

If you self-host the relay and the daemon sees the event but it doesn't reach the platform:

vpd logs --follow | grep -i relay

If frames are queueing locally, your relay is down or unreachable. See Daemon won't connect and Relay handshake errors.

What if the agent itself isn't pausing

Sometimes the agent runs to completion and never pauses. Which feels wrong if you expected a plan review.

Causes:

The workflow doesn't have a plan-review node. Check the workflow YAML. See Reference: Workflow YAML.
The agent's plan-mode isn't enabled. For Claude Code, the workflow needs agent.plan_mode: true. For Codex, similar.
Auto-approve fired. If your policy says "auto-approve plans under 5 file changes," small plans pass without prompting. Check the audit log for the auto-approval entry.