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 or Codex) 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 --hooks

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 --hooks 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 policy requires an inbox item

Some policies don't require human review. For launch, use an explicit plan gate so a human inbox item is created before implementation.

Check the committed .viewport/policy.yaml:

vpd check .

Or inspect the run in the web app. The composed policy should show a plan-review gate with reviewer tags.

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 policy doesn't have a plan-review gate. Check .viewport/policy.yaml. See Reference: .viewport YAML.
The route points at an old policy ref. Push the policy and resync before triggering again.
The gate reviewer tag has no members. Assign a team member the tag or change the policy to use a tag that exists.