Hubspot Hook Response Contracts

Stderr is reserved for diagnostic noise only — stack traces, debug logs, verbose API responses. Claude Code reads stdout exclusively for the decision envelope.

Stdout vs Stderr Channel Rules

Workflow

1. Determine the decision outcome — after all validation and governance checks complete, resolve to block, warn, or allow.
2. Construct the envelope — populate all required fields. reason must be actionable (e.g., "Bulk delete of 312 contacts exceeds 100-record safety threshold. Use hsdedup with --dry-run first.").
3. Write envelope to stdout only — use process.stdout.write(JSON.stringify(envelope) + '\n') or echo "$envelope" >&1. Never mix diagnostic text with the envelope on stdout.
4. Write diagnostics to stderr — any verbose API responses, timing data, or debug flags go to >&2.
5. Set exit code — exit 0 for allow and warn; exit 1 for block (belt-and-suspenders with the JSON decision field).
6. Verify with degraded-mode test — confirm that if the hook script crashes mid-execution, the absence of a valid envelope causes Claude Code to default to allow (fail-open) and log the anomaly.

Routing Boundaries

Use this skill for response envelope design and stdout/stderr channel discipline only. Defer to hubspot-hook-input-contracts for input parsing and to hubspot-agent-governance-runtime for governance policy.

References

• Decision Schema
• Stderr vs Stdout
• Rejection Guidance