#902 swamp audit record --from-hook exits non-zero as Claude Code PostToolUse hook despite internal try/catch design

Description

When swamp audit record --from-hook is configured as a Claude Code PostToolUse/PostToolUseFailure hook, Claude Code intermittently reports a hook error:

PostToolUse:Bash hook error
Failed with non-blocking status code: No stderr output

The error fires on real PostToolUse hook invocations but the swamp doctor smoke test passes, and every manual simulation of the command (across multiple payload shapes) exits 0.

Environment

• swamp version: 20260701.000413.0-sha.eaa21300
• tool: claude (Claude Code)
• OS: macOS Darwin 25.5.0

Steps to Reproduce

1. Run swamp init --tool claude to wire the PostToolUse hook in .claude/settings.local.json
2. Use Claude Code and run any Bash tool call
3. Observe the hook error in Claude Code's terminal output

Observed Behavior

Claude Code reports:

PostToolUse:Bash hook error
Failed with non-blocking status code: No stderr output

swamp doctor audit returns overallStatus: "pass" including the recording-smoke-test check. Running swamp audit record --from-hook manually with all tested payload shapes (valid Claude payload, missing tool_input, lowercase tool_name, invalid JSON, empty stdin) always exits 0.

Key Findings from Source Inspection

1. Command source guarantees exit 0 (src/cli/commands/audit.ts:115–163)

The entire action body is wrapped in:

try {
  // ... all logic ...
} catch {
  // Must never throw - this is a hook command.
}

There is no code path in the action that exits non-zero. The smoke test code even comments: "Never relies on subprocess exit code — audit record --from-hook never throws by design." Yet Claude Code reports a non-zero exit.

2. Hook is duplicated across two settings files

swamp init writes the hook to .claude/settings.local.json. In this repo the hook also exists in .claude/settings.json (the git-tracked project settings). Claude Code loads both files and fires all matching hooks — so swamp audit record --from-hook fires twice per Bash call, racing on the same stdin pipe. The agent-config-loadable doctor check only validates settings.local.json and would not detect this duplication.

3. swamp help audit --json reports subcommands: []

The JSON schema for the audit command lists no subcommands, even though swamp audit record --from-hook is functional. This may be a documentation gap rather than a functional bug, but it's worth noting.

Hypothesis

The most likely cause is either:

• A Cliffy framework-level error that escapes the try/catch (e.g. option parsing issue triggered only by Claude Code's invocation environment)
• A hook timeout: Claude Code kills the hook process after a deadline, causing a non-zero exit that the try/catch cannot prevent
• A race condition from the duplicate hook entries causing two concurrent reads from the same stdin pipe

Workaround

Remove the duplicate hook from .claude/settings.json so it only exists in .claude/settings.local.json (where swamp init writes it). This halves the hook invocations per Bash call.