Summary

R3 Q8a's "the other way mostly, like 'Kora, email me that pdf etc.'" — the outbound counterpart to PR #176's inbound Sea_Ticket save. Kora's reasoning engine now has a tool to compose and send an email to the operator when the response is too long, structured, or attachment-heavy for Slack DM.

Bucket spec: 17_cc_bucket_prompts/KR-EMAIL-OUTBOUND-COMPOSE-TOOL_kora_emails_operator.md.

Cap_matrix coord — RESOLVED INLINE ✅

The spec's STOP-ASK condition ("cap_matrix.kora row needs substrate-team coordination") does not apply — cap_matrix is Kora-side config (per-caller allowed_caps in mcp_callers.yaml + per-tool requires_cap_gate flag), not a substrate-side table.

• The new tool kora__send_email_to_operator ships with requires_cap_gate: True — external MCP callers are default-deny; operators can grant the cap per-caller via mcp_callers.yaml if they ever want to.
• Kora's own reasoning loop bypasses cap_matrix entirely via the in-process REASONING_TOOL_ALLOWLIST in kora_cli/reasoning/tool_registry.py. This PR adds the tool to that allowlist alongside the 5 existing read-only tools.

No substrate-team coord needed. No IsoKron PM message required.

Security: why recipient pinning lets this enter the reasoning loop

The original tool_registry.py docstring deliberately excluded kora__send_email from the reasoning surface ("Kora already responds via the Slack DM channel; meta-sends would be confusing + Loop-risky") — the real underlying risk was caller-controlled recipients opening a mass-send vector. kora__send_email_to_operator neutralizes this: the executor itself pins recipient to KORA_EMAIL_JOSHUA_ADDRESS; the tool input schema has no to field. Loop-risk is addressed by KORA_EMAIL_OUTBOUND_HOURLY_CAP (default 5/hr).

The deliberate scope expansion is documented in the updated tool_registry.py module docstring + the system prompt's mutation-boundary section. The other mutating tools (request_state_transition, create_sea_ticket, send_slack_dm, send_email, request_pause/resume/stop, send_test_alert) stay excluded — see test_allowlist_excludes_caller_controlled_mutating_tools.

Env vars added

Sample audit entry

Success path:

{
  "emitted_at": "2026-05-23T22:14:09.412000+00:00",
  "seam": "tool.email_to_operator_sent",
  "details": {
    "subject_chars": 24,
    "body_chars": 1841,
    "attachment_count": 1,
    "attachment_total_bytes": 184132,
    "status": "sent",
    "smtp_message_id": "<20260523221409.kora@stormhavenenterprises.com>",
    "sent_at": "2026-05-23T22:14:09Z"
  },
  "caller_session_id": "mcp:kora_reasoning_self",
  "source": "reasoning"
}

Rejection path:

{
  "emitted_at": "...",
  "seam": "tool.email_to_operator_sent",
  "details": {
    "subject_chars": 220,
    "body_chars": 1841,
    "attachment_count": 0,
    "status": "rejected",
    "rejection_reason": "subject_too_long",
    "rejection_detail": {"subject_chars": 220, "max_chars": 200}
  },
  "caller_session_id": "mcp:kora_reasoning_self",
  "source": "reasoning"
}

Body content never appears in audit — only sizes. Recipient field absent (always operator).

Sample reasoning-engine invocation

When Joshua DMs "kora email me a summary of today's probe activity with the audit JSONL attached", Kora's reasoning loop would emit a tool_use block like:

{
  "type": "tool_use",
  "name": "kora__send_email_to_operator",
  "input": {
    "subject": "[Kora] Probe activity summary — 2026-05-23",
    "body": "Here's today's rundown:\n\n- 4 probes ran...\n\n(full audit attached)",
    "attachments": [
      {"filename": "audit-2026-05-23.jsonl", "content_path": "/var/lib/kora/audit-export.jsonl"}
    ]
  }
}

Tool result returned to Claude:

{
  "status": "sent",
  "smtp_message_id": "<...>",
  "sent_at": "2026-05-23T22:14:09Z",
  "attachment_count": 1,
  "attachment_total_bytes": 184132
}

Files

• NEW kora_cli/tools/__init__.py + kora_cli/tools/email_to_operator.py (~480 lines)
• NEW tests/kora_cli/tools/test_email_to_operator.py (22 tests)
• MOD kora_cli/listeners/mcp_tools.py — new tool descriptor + dispatcher (thin wrapper around the pure-Python module)
• MOD kora_cli/reasoning/tool_registry.py — add to allowlist + ST2 dispatch path with synthetic Caller + pull from both descriptor lists
• MOD kora_cli/audit/jsonl_sink.py — new tool.email_to_operator_sent SeamName Literal entry
• MOD kora_docs/00_canonical_current_state/kora_system_prompt.md — usage guidance + mutation-boundary exception note
• MOD tests/kora_cli/reasoning/test_anthropic_engine_tool_use.py — bump 5→6 tool count assertions; broaden allowlist-exclusion test to cover all forbidden mutating tools

Test plan

• 22 tools-module tests pass: recipient pinning, all validation rejections, attachments (happy + missing file + size cap), hourly cap (3 → 4th rejected), SMTP exception + SendResult-failed paths, audit shape (no body content), registry integration (tool advertised, synthetic Caller dispatch, other mutating tools still excluded).
• Regression: 353 passed across tools + mcp_tools + audit + handlers + intent + reasoning.
• ruff check clean on all changed files.

🤖 Generated with Claude Code