Add per-agent toggle to disable HITL approval notification emails

[jiashuoz]

Problem

When an agent has hitl_enabled: true, every pending_approval send fires an approval-notification email to the account owner via internal/hitlnotify/notifier.go. There is no way to opt out short of disabling HITL entirely.

This is painful in a few real cases:

• E2E / load testing. During a prod test session, ~70 pending sends produced ~70 notification emails to the owner's inbox. The "queue then reject" pattern is not safe for testing because the notification already left by the time /messages/{id}/reject is called.
• Dashboard-only reviewers. Some operators watch the dashboard live (or have a Slack integration polling pending messages) and don't want their inbox to fill up.
• Programmatic approval flows. Agents whose approvals are driven by API/CLI/webhook callers don't need the magic-link email — the link goes unused.

Proposed solution

Add a per-agent boolean hitl_notify_email (default true to preserve existing behavior). When false, the HITL gate skips the call to Notifier.NotifyPendingApproval for that agent. All other HITL paths (dashboard view, CLI approve/reject, /messages/{id}/approve|reject, TTL expiration worker) remain unchanged.

Per-agent matches the existing HITL granularity (hitl_enabled, hitl_expiration_action, hitl_ttl_seconds) and is the simplest mental model for users.

Implementation sketch

• Migration: ALTER TABLE agents ADD COLUMN IF NOT EXISTS hitl_notify_email BOOL NOT NULL DEFAULT TRUE; (idempotent, non-destructive — safe per the migration guidelines in CLAUDE.md)
• Add the field to RegisterAgentRequest, UpdateAgentRequest, and Agent response with swag annotations
• Branch in the HITL gate (where Notifier.NotifyPendingApproval is currently called) to skip when the agent's flag is false
• make generate to regen TS + Python SDK types
• CLI: surface as --no-notify on the relevant commands (or part of agents update)
• Web: add a checkbox to the agent's HITL settings panel

Tradeoff to document

If a user disables notifications and stops watching the dashboard, pending messages will silently expire and act per hitl_expiration_action (approve or reject). The API description for hitl_notify_email should call this out.

Alternative considered

A per-request header override (X-E2A-Skip-Notification: 1 on /send) is more flexible but adds API surface for a niche case. Per-agent boolean covers all the use cases above with less complexity.

Out of scope

• Per-recipient notification rules (deferred)
• Notification channels other than email (Slack, webhook) — separate feature

[jiashuoz]

🔍 Issue audit (automated triage, 2026-06-26)

• Stale? Partially. The issue was written against the old HITL model: it references `hitl_enabled: true` (column dropped in `043_drop_hitl_columns.sql`) and status `pending_approval` (renamed to `pending_review` in `044_unify_holds.sql`). The core problem is still live — `NotifyPendingApprovalAsync` fires unconditionally at `internal/agent/api.go:1035` — but the implementation sketch needs updating to the current terminology (`outbound_policy_action=review` triggers holds, not `hitl_enabled`).

• Severity — medium. Real operational pain (load-test / programmatic approval flows produce inbox flood), but no data loss and no blocking of any core API contract.

• Correctness bug? No — pure feature/UX-control gap.

• Root cause — n/a — feature. The notification path at `internal/agent/api.go:1035` is guarded only by `a.notifier != nil`; there is no per-agent suppress flag anywhere in the model. `AgentIdentity` (`internal/identity/store.go:77–137`) carries `HITLTTLSeconds` and `HITLExpirationAction` but no `HITLNotifyEmail` or equivalent. No migration has added one.

• Best fix — Add `hitl_notify_email BOOL NOT NULL DEFAULT TRUE` to `agent_identities` (a new idempotent migration, e.g. `049_hitl_notify_email.sql`), add the field to `AgentIdentity` and the protection/update API surface, then branch the `NotifyPendingApprovalAsync` call in `api.go:1035` to skip when `!agent.HITLNotifyEmail`. The field sits naturally next to `hitl_ttl_seconds`/`hitl_expiration_action` in the review-queue mechanism group. Relationship to Notification preferences (Settings → Notifications shows 'Coming soon') #133: Notification preferences (Settings → Notifications shows 'Coming soon') #133 proposes account-level notification prefs (`hitl_pending_threshold`, `webhook_failure`, etc.) which would eventually let a user suppress all HITL emails globally; Add per-agent toggle to disable HITL approval notification emails #146 is per-agent granularity on top of that. They are additive, not redundant — ship Add per-agent toggle to disable HITL approval notification emails #146 independently, cross-reference when Notification preferences (Settings → Notifications shows 'Coming soon') #133 is scoped so the two layers compose cleanly.

• Worth fixing? Fix later. Not a GA blocker, but the load-test / programmatic-approval scenarios are concrete and the implementation is straightforward (one migration, one struct field, one branch, one API field, one checkbox in the HITL settings panel). Upgrade to "fix now" if a customer escalates the inbox-flood during testing.

[jiashuoz]

Refresh (mechanics drifted; the feature ask still stands)

Revisiting this — the underlying request is still valid and unbuilt (there's no per-agent way to hold a send without also emailing the owner). But the implementation sketch above references machinery that has since been retired, so here's the corrected wiring against main.

What changed since this was filed

• hitl_enabled is gone. It was retired in migrations/042_retire_hitl.sql. A send is now held for review because the agent's outbound gate action is review (outbound_policy_action, migrations/041_scan_config.sql), not because of a boolean HITL flag. The HITL mechanism fields (hitl_ttl_seconds, hitl_expiration_action) survive on agent_identities and now belong to the protection config.
• The swag annotation pipeline is gone. The /v1 surface is Huma-generated; SDK bases regenerate via make generate from api/openapi.yaml. No RegisterAgentRequest/UpdateAgentRequest swag annotations to touch.
• Notification is now durable via River (QueueNotify). The email is no longer sent inline — it's enqueued.

Corrected implementation sketch

1. Trigger site (the branch that skips the notify).
The approval-notification job is enqueued inside HoldForApprovalCore at internal/agent/api.go:989 via a.notifyEnq.EnqueueNotifyTx(ctx, tx, m.ID) — the hold row and the QueueNotify job are written in one transaction (see docs/design/hitl-notify-river.md). The opt-out is a guard here:

if a.notifyEnq != nil && agent.NotifyOnHold {
    jobID, err := a.notifyEnq.EnqueueNotifyTx(ctx, tx, m.ID)
    // ...
}

When the flag is off we simply don't enqueue the job — the hold, TTL expiry worker, dashboard view, and CLI/API approve|reject paths are all unaffected.

2. Storage — on agent_identities, not agents.

ALTER TABLE agent_identities
    ADD COLUMN IF NOT EXISTS notify_on_hold BOOLEAN NOT NULL DEFAULT TRUE;

Idempotent + non-destructive (additive ADD COLUMN, safe per the migration guidelines in CLAUDE.md). Default TRUE preserves today's behavior.

3. API surface — put it in the protection config, not a swagged agent field.
The natural home is the beta protection resource (PUT /v1/agents/{email}/protection, internal/httpapi/protection.go), under the existing holds section that already owns ttl_seconds / on_expiry:

"holds": { "ttl_seconds": 604800, "on_expiry": "reject", "notify": true }

Thread it through ProtectionHoldsView → identity.ProtectionConfig → the UpdateAgentProtection UPDATE (internal/identity/protection.go) → the agent_identities read-back. Then make generate regenerates the TS + Python SDK types. This keeps the whole screening/hold posture in one place (account-scope only) rather than scattering a HITL knob onto the agent resource.

4. CLI / Web — surface as part of the protection/holds settings rather than a standalone --no-notify, to match where the knob now lives.

Tradeoff to keep (still accurate)

If notifications are off and nobody watches the dashboard, held sends silently expire and act per hitl_expiration_action (approve|reject). The API doc: string for notify should call this out.

The original motivation is unchanged and, if anything, stronger — the E2E/load-test case (~70 held sends → ~70 owner emails) is exactly the "queue-then-reject isn't safe for testing on prod" pain we keep hitting.