---
name: hermes-external-contact-messaging
description: Configure and operate Hermes as a supervised messaging relay for external contacts over Photon/iMessage/SMS without granting them owner-level agent powers.
version: 1.2.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [hermes, photon, imessage, sms, contact-book, sandbox, relay, gateway, safety]
---

# Hermes External Contact Messaging

Use this when Alex wants Hermes/Hermie to send messages to family, clients, or other external contacts, receive their replies, and relay or respond safely **without** letting those contacts command Alex's full Hermes agent.

This skill complements the protected `hermes-agent` skill. Load `hermes-agent` first for authoritative CLI/config docs, then use this skill for the external-contact trust model and operational pattern.

## Core principle

Do **not** treat external contacts as normal owner/admin Hermes users. Separate:

- **Owner/admin**: Alex; full tools, filesystem/server access, cron, memory writes, outbound messaging authority.
- **External contact**: can send/receive messages in their own thread only; no server tools, no private session access, no contact-book-wide sending, no arbitrary commands.

Start with **supervised relay** by default, then graduate to limited auto-replies only after the routing and safety behavior is proven.

## Recommended modes

1. **Relay-only mode** — safest default
   - External contact replies are forwarded to Alex.
   - Hermes does not answer the contact except for a minimal acknowledgement if configured.
   - Alex replies with commands like “Reply to my sister: …”.

2. **Supervised sandbox mode** — recommended first automation step
   - Contact can receive limited text responses from a restricted agent/persona.
   - No terminal/file/web/cron/memory/send-message-to-others tools.
   - Personal, sensitive, ambiguous, or actionable requests are forwarded to Alex.

3. **Limited auto-reply mode** — only after testing
   - Allow narrow canned intents such as “who is this?”, “I’ll relay that to Alex”, or simple scheduling/coordination.
   - Keep a deny-by-default policy for tool-like or owner-impersonation requests.

## Contact policy shape

Use a small explicit policy per contact or contact group:

```yaml
contacts:
  sister:
    handles:
      - "+1XXXXXXXXXX"
    display_name: "Alex's sister"
    mode: supervised_relay
    allowed_actions:
      - receive_message
      - forward_to_owner
      - send_owner_approved_reply
      - limited_auto_reply
    denied_actions:
      - terminal
      - file_access
      - web
      - cron
      - memory_write
      - send_to_other_contacts
      - owner_impersonation
```

## Photon/iMessage operational workflow

### Personal or single-agent Hermes

1. **Normalize the phone number** to E.164, preserving `+1` for US numbers.
2. **Pre-authorize local Hermes inbound access** by adding the contact to `PHOTON_ALLOWED_USERS` in `~/.hermes/.env`.
   - Keep Alex's own number in the list.
   - Multiple entries are comma-separated.
3. **Register/provision the number in Photon** if needed:
   ```bash
   hermes photon setup --phone +1XXXXXXXXXX
   ```
   This may report `PHOTON_ALLOWED_USERS already set — leaving it as-is`; that does not necessarily mean the cloud-side target is allowed.
4. **Verify outbound with a direct send probe**, but do not expose raw tokens or full phone numbers in user-facing output.
5. **Verify inbound routing** by having the contact reply and confirming Hermes classifies them as an external contact rather than owner/admin.
6. **Only then enable any sandbox auto-reply behavior.**

### Product-managed multi-tenant Hermes

Do not expose personal CLI onboarding as customer UX. The product operator authorizes Photon once at the trusted platform/control-plane boundary. Customers should not create Photon accounts, run device login, or receive Photon approval URLs/codes.

The customer flow is:

1. Privately collect the customer's iMessage-capable E.164 number. Photon needs it to register/bind the user, but it must not enter ordinary chat transcripts or logs.
2. The trusted backend uses its platform Photon management credential to register the user and obtain `assignedPhoneNumber`—the shared-pool line assigned for that conversation.
3. Show one instruction: **Text this number to continue.**
4. A trusted central router maps Photon user/space identity to the exact tenant Coordinator. Tenant containers must not receive the platform management token or unfiltered cross-tenant streams.
5. Mark setup ready only after the assigned line exists and a real inbound text reaches the intended tenant. Dedicated business numbers are a premium/provider-plan option; never imply the free shared pool gives every tenant a permanent dedicated line.

Operator device authorization may expire and require one platform reauthorization. Treat that as control-plane maintenance, never as a customer onboarding step.

## Important Photon pitfalls

Local Hermes allowlisting and Photon cloud-side target permission are separate layers.

A number can be present in `PHOTON_ALLOWED_USERS` and successfully registered by `hermes photon setup --phone ...`, yet outbound sends can still fail upstream with:

```text
AuthenticationError: [spectrum-imessage] Target not allowed for this project
/photon.imessage.v1.MessageService/SendTextMessage PERMISSION_DENIED
```

Interpretation:

- Hermes local allowlist is ready for inbound authorization.
- Photon/Spectrum project still does not permit sending to that target.
- On shared-line Photon plans, each registered user may get a different `assignedPhoneNumber`; if outbound initiation is blocked, have the contact text **their own assigned agent line** first to test whether Photon opens/establishes the target from their side.
- Look for a Photon dashboard approval/target allow step or contact Photon support; do not keep retrying identical sends.

Also watch for Photon secret rotation. In some Hermes versions, `hermes photon setup` regenerates `PHOTON_PROJECT_SECRET` on every run. A running sidecar reads the secret only at startup, so rerunning setup can make outbound sends fail until gateway/sidecar restart; an upstream Hermes PR (#50761) changes setup to reuse valid secrets. Before rerunning setup for a contact, prefer checking current users with the Spectrum users API, and after any setup/rotation restart the gateway from outside the gateway process.

See `references/photon-target-allowed-pitfall.md` for the session-derived probe pattern, direct sidecar diagnostics, open-issue context, and error signature.

For multi-tenant product onboarding, use `references/tenant-safe-photon-onboarding.md`: Photon must be presented as iMessage rather than Android Messages/RCS; distinguish personal CLI setup from platform-managed provisioning; keep the platform management token out of tenant runtimes; privately collect E.164, return the assigned line, route inbound through a trusted tenant map, and verify a real text round trip before status becomes ready.

For any shared multi-tenant messaging project or inbound stream, also load `references/multi-tenant-shared-messaging-router-security.md`. It defines the fail-closed contract for signed nonce/phone-bound results, transactional claims and immediate old-handset revocation, provider-envelope semantic verification (including Photon's shared-mode `space.phone === "shared"` sentinel), first-DM proof and space pinning, current tenant authority reconciliation, Coordinator continuity, durable idempotency/outbox states, symlink-safe non-root volume bridges, data minimization, adversarial tests, and exact-revision release gates.

## Safe reply behavior

When forwarding inbound messages to Alex, include:

- Contact display name / relationship if known.
- Redacted handle unless Alex explicitly needs the full number.
- Message text and timestamp.
- Suggested reply only if helpful.

Example owner-facing relay:

> Your sister replied: “Sounds good, call me later?”
>
> Suggested reply: “Cool, I’ll call after dinner.”

When sending to the contact, confirm or clearly report the exact message body and whether the send actually succeeded. Never say a message was sent unless the send API returned success/message id or an equivalent confirmed result.

## Skill maintenance notes

- If future Hermes adds first-class per-contact sandbox profiles/policies, update this skill with the exact config path and commands.
- If Photon changes the cloud target-allow process, update the pitfall section and reference file.