feat(contact): choose future email delivery

[robzolkos]

Summary

HEY contacts can now be sent to the Imbox, The Feed, Paper Trail, or Screened Out from the CLI. This gives scripts and coding agents the same delivery control as the web app without relying on box display names or an unreliable read-back.

The command validates its contact ID and closed destination vocabulary before account selection can make an HTTP request. Box destinations resolve HEY's canonical box kinds; Screened Out first confirms that the contact is an external email sender. The result is a stable {id, destination} mutation response, and the CLI guide, API coverage, command surface, and bundled HEY skill describe the same contract.

Selecting The Feed may remove an existing bundle, matching HEY's server behavior. Assigning a box does not implicitly approve a denied sender.

Validation

• make check
• make build
• Smoke module compilation
• Focused strict contact smoke tests against the local HEY development server
• Full strict smoke reached the new contact-delivery coverage successfully, then timed out later in the unrelated long-thread Markdown test
• Full multi-lens code review, including an independent cross-model adversarial pass, with no remaining findings

Fixes #336.

---

Summary by cubic

Adds hey contact deliver <contact-id> --to imbox|feed|papertrail|screened-out so the CLI can set where a contact's future email arrives, giving scripts and agents the same delivery control as the web app. Fixes #336.

• Validates the contact ID and closed destination vocabulary before account selection can make an HTTP request.
• Resolves Imbox, The Feed, and Paper Trail to HEY's canonical box kinds; Screened Out refuses contacts that are not external email senders before denying them.
• Selecting The Feed removes an existing bundle to match HEY's server behavior; assigning a box does not approve a contact that is already Screened Out.
• Returns a stable {id, destination} result; the command is write-only because HEY does not expose the current setting as structured data.
• Aligns help, CLI docs, API coverage, the command surface, and the bundled HEY skill on the same contract, and adds endpoint and smoke coverage.

^{Written for commit b7448f9. Summary will update on new commits.}

[cursor]

Approved. Cursor Security Agent passed with no findings that need human review; Cursor Bugbot was not present on this PR. No reviewers were assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[Copilot]

Copilot review overview

🟡 Changes recommended

Ordinary command help omits several required delivery semantics currently present only in agent metadata.

Review effort: Balanced
Findings: 1

Open (1)

• Include agent_notes caveats in contact deliver help · New

What changed in this PR

Adds contact-first delivery routing for HEY contacts.

Changes:

• Adds hey contact deliver with four validated destinations.
• Adds unit and smoke coverage.
• Updates CLI, API, command-surface, and agent documentation.

[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

File	Description
.surface	Records the new command and flag.
API-COVERAGE.md	Maps delivery API operations.
docs/​cli.md	Documents routing behavior.
docs/​plans/​2026-09-27-0116-feat-contact-delivery-routing-plan.md	Defines the implementation plan.
internal/​cmd/​contacts.go	Registers the subcommand.
internal/​cmd/​contacts_deliver.go	Implements contact delivery routing.
internal/​cmd/​contacts_deliver_test.go	Tests validation and API behavior.
internal/​cmd/​help_test.go	Updates contact help expectations.
skills/​embed_test.go	Verifies embedded guidance.
skills/​hey/​SKILL.md	Documents the command for agents.
tests/​smoke/​contacts_test.go	Adds real-server smoke coverage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approved

The implementation, validation, tests, command surface, and documentation consistently satisfy the stated delivery-routing contract.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Include agent_notes caveats in contact deliver help