Code Review — PR #965 (Email Triage Agent / Gmail integration)

Summary

Substantial, well-engineered first cut of the Email Triage Agent. The architectural commitments (AC1–AC4) are not just claimed in prose — they're load-bearing in the code: EmailAgentConfig has no cloud-LLM fields and the base_url allowlist is enforced at startup (AC3), backends are Protocol-based and injectable for the eval seam (AC4), and destructive tools are gated through TOOLS_REQUIRING_CONFIRMATION (AC2). The three-layer prompt-injection defense (system prompt → <<<UNTRUSTED_EMAIL_BODY_*>>> delimiters → I3 batch threshold) is implemented and pinned by tests.

Test coverage is the standout: token-freshness assertions against httpx.MockTransport, parametrized ordering-invariant tests across every mutate tool ("no phantom DB row on Gmail failure"), an explicit token-non-leakage test on error envelopes, and heuristic regression tests that pin #848's 4-bucket taxonomy and the system-label-ID-vs-human-name distinction from #916. The PR also incidentally fixes a pre-existing connectors_demo bug (bare strings → ConnectorRequirement objects in registry.py) and refactors _format_connector_error into gaia.connectors.formatting so the email agent gets its own re-grant message without forking the formatter.

Nothing in the diff blocks merge. The findings below are doc drift, dead code, and quality cleanups that should land in a follow-up.

Issues

🟡 Documentation drift — SHA1 references after the SHA256 cutover

The recent commit 53a93e4e flipped the message-ID derivation from SHA1 to SHA256, but two prose locations still describe the old algorithm:

tests/fixtures/email/_schema.md:15-17

Each entry in `ground_truth.json` is keyed by the Gmail message id (16-char
SHA256 prefix derived deterministically from the mbox `Message-ID` header by
`tests/fixtures/email/fake_gmail.py::mbox_message_to_gmail_payload`).

tests/fixtures/email/fake_gmail.py:176 — the mbox_message_to_gmail_payload docstring still says "The id and threadId are SHA1-derived from Message-ID…". The code at lines 186/190 uses hashlib.sha256(...). Update the docstring to match.

This drift is minor today but actively misleads anyone hand-deriving an ID to add a ground-truth row.

🟡 fake_gmail.py:151 still uses SHA1 for attachment IDs

att_id = "att_" + hashlib.sha1(raw).hexdigest()[:16] if raw else "att_empty"

Inconsistent with the message-ID flip. Not a security finding (synthetic test fixture, deterministic IDs only), but if the policy is "no SHA1 for any newly-introduced fixture identifiers," promote this to SHA256 for consistency. If the policy is narrower (only message IDs need to migrate), drop a one-line comment here saying so — otherwise the next reader will assume it's an oversight.

🟡 Standalone cli() in src/gaia/agents/email/cli.py:114 is unreachable dead code

# Standalone entry point — also wired in setup.py if desired in a follow-up.
def cli() -> int:  # pragma: no cover — wrapper around argparse
    parser = argparse.ArgumentParser(prog="gaia email")
    ...

The only path users actually take is gaia email → gaia.cli.handle_email_command → asyncio.run(email_main(args)). The standalone cli() is not registered as a console_scripts entry in setup.py, has its own argparse that duplicates (and could drift from) the gaia email subparser in src/gaia/cli.py, and is # pragma: no cover'd so any drift goes unnoticed.

Two clean options:

• Delete it. The if __name__ == "__main__" block and the cli() wrapper add no value while the canonical entry is gaia email.
• Wire it. Add gaia-email = gaia.agents.email.cli:cli to setup.py's console_scripts (matching gaia-code/gaia-emr) and remove the # pragma: no cover so it's actually exercised.

Per the "no half-finished work" rule in CLAUDE.md, the current "wired in setup.py if desired" middle state shouldn't ship.

🟡 repr(exc) leaks internal exception state into LLM-visible envelopes

Twenty-five tool wrappers across read_tools.py, organize_tools.py, reply_tools.py, delete_tools.py, and calendar_tools.py follow this pattern:

except Exception as exc:
    return _envelope_err(repr(exc))

Bearer-token leakage is already test-pinned (test_error_does_not_leak_authorization_header) at the backend level, so the known sensitive field is safe. But repr(exc) for unexpected exception types (KeyError, ValueError, httpx.LocalProtocolError, dict-walk failures inside decode_message_body, etc.) will surface raw internal state to the LLM context window and to any downstream UI rendering — including potentially message bodies, partial JSON, or file paths.

Suggested pattern (or move into a small helper to keep this DRY across the five tool files):

except ConnectorsError as exc:
    return _envelope_err(str(exc))   # connectors errors are already shaped for users
except Exception as exc:
    log.exception("tool %s failed", tool_name)
    return _envelope_err(f"{type(exc).__name__}: {exc}")

type(exc).__name__: message is a strict subset of repr(exc) — same actionable signal for the LLM, no risk of repr exposing constructor-arg strings that the test suite hasn't anticipated. The full traceback still goes to the structured log via log.exception.

🟢 Minor nits

• src/gaia/agents/email/cli.py:46 — agent construction error swallowed into a printed string; the cause chain is lost. For a one-shot CLI this is acceptable, but consider log.exception("email-agent failed to start") so debug invocations preserve the traceback. The pattern is already used a few lines down in _one_shot/_interactive.
• src/gaia/agents/email/cli.py:71-110 — _one_shot and _interactive duplicate the result.get("answer") or result.get("response") or str(result) extraction. Trivial DRY opportunity.
• The PR description claims "No silent fallbacks" — the code holds up to that. Worth pinning a one-liner test that asserts EmailAgentConfig rejects base_url="https://api.openai.com" with an exception whose message contains "AC3" (you have a config-rejection test; just verify the error string mentions the AC ID so future readers know which guard tripped).

Strengths

• Test discipline. The tests/unit/email/test_gmail_client.py suite uses httpx.MockTransport against the real LiveGmailBackend rather than mocking the class — request shapes, token freshness, error mapping, and Authorization-header hygiene are all observable. This is the right testing seam for HTTP clients.
• Adversarial parametrized invariant test. TestOrderingInvariantParameterized runs every mutate tool through a forced-failure path and asserts zero rows in email_actions. Pins the "Gmail call before DB write" rule against future refactors.
• AC3 enforced structurally, not by convention. EmailAgentConfig has no use_claude / use_chatgpt / claude_api_key fields, and gaia.cli.handle_email_command deliberately does not pass cloud-LLM flags through. The unit test (test_email_agent_local_llm_enforcement.py) parameterizes over the forbidden field names so a future "let's just add a use_claude flag" attempt fails CI.
• Defense-in-depth on prompt injection. I1 (system prompt + body delimiters) and I3 (per-turn organize counter with sentinel) are independent — even if a clever email body convinces the LLM to ignore the system prompt, I3 still cuts off mass-organize attempts. Both are explicitly tested.
• Refactor + bug fix in scope. Extracting _format_connector_error to gaia.connectors.formatting (with an _AGENT_GRANT_MIGRATION_MESSAGES dict for agent-specific re-grant copy) and fixing the pre-existing bare-string bug in agents/registry.py for connectors_demo are both genuine improvements that earn their place in this PR.
• No silent fallbacks. EmailAgentConfig.validate() raises on remote base_url, the backends raise ConnectorsError with actionable context (status code + body excerpt + "Reconnect" hint), and restore_message_impl raises RuntimeError("undo window") past the retention window rather than no-oping.
• Audit ordering on send_now. The recent fix (commit 8091df57) explicitly avoids masking a successful send when the audit-write fails — the comment-justified try/except around the DB write is the right shape.

Verdict

Approve with follow-ups. Merge unblocked. Recommend a quick follow-up PR (or amend before merge if convenient) for the SHA1 → SHA256 doc drift in _schema.md and fake_gmail.py's mbox_message_to_gmail_payload docstring — those actively mislead. The standalone cli() decision (wire-or-delete) and the repr(exc) cleanup are good targets for the next sprint. Excellent groundwork for #963 (Outlook backend) — the Protocol-based seam will pay off there.

Nice work, @itomek.

Summary

Solid execution of a non-trivial feature: 25 tools across 5 mixins, real OAuth token plumbing, a clean Protocol seam for eval, a SQLite undo log, three-layer prompt-injection defense, and thoughtful B2 ordering invariants. AC3 (local-LLM only) is enforced architecturally, not just by convention — EmailAgentConfig has no cloud-LLM field and base_url runs through an allowlist. The test bench is unusually thorough: httpx.MockTransport-driven behavioral tests for the live backend, parameterized ordering-invariant tests, prompt-injection scenario fixtures, and a regression-pinned heuristic test that explicitly calls out PR #916's mistakes.

One concrete security concern worth fixing before merge (CRLF header injection in _build_rfc822), plus a few quality nits. The PR also bundles two welcome side-quest fixes: the pre-existing connectors_demo bare-string required_connections bug and the missing gmail.modify scope.

Issues

🔴 Critical

1. CRLF header injection in _build_rfc822 — to, subject, and extra_headers values are interpolated unsanitized. src/gaia/agents/email/gmail_backend.py:578-601

header_block = "\r\n".join(f"{k}: {v}" for k, v in headers.items())
rfc822 = f"{header_block}\r\n\r\n{body}"

If any value contains \r\n, it splits a single header into multiple headers (or terminates the header block early and injects body content). Exploitation paths:

• forward_message_impl (reply_tools.py:209-218) reads Subject from the inbound message and passes it straight through to send_message → _build_rfc822. An adversary mailing the user a message whose subject contains a literal CRLF (Gmail sometimes preserves these in headers; certainly preserves them in payload.headers[].value returned from the API) can append a Bcc: header on every forward. This is the same input-trust gap that I1/I3/I4 already harden against in body content — header values from inbound mail are untrusted in exactly the same way.
• draft_reply_impl / send_now_impl: to and subject are LLM-decided. A successful prompt-injection (which I3/I4 already acknowledge as possible — defense is layered) could steer the LLM to include CRLF in either field.

Defense in depth: validate at the seam where the bytes get serialized.

def _build_rfc822(
    *,
    to: str,
    subject: str,
    body: str,
    extra_headers: Optional[Dict[str, str]] = None,
) -> str:
    """Build an RFC 2822 message wrapped in URL-safe base64.

    Used for ``drafts.create``, ``drafts.send``, ``messages.send``. We
    construct manually instead of using ``email.message.EmailMessage`` to
    avoid double-encoding edge cases — Gmail expects the raw bytes
    base64url-encoded in a single ``raw`` field.
    """
    headers = {
        "To": to,
        "Subject": subject,
        "Content-Type": 'text/plain; charset="utf-8"',
    }
    if extra_headers:
        headers.update(extra_headers)
    # Defense in depth against CRLF header injection. ``to``/``subject``
    # can be LLM-decided or lifted from inbound mail (e.g. forward
    # preserves the original Subject), so any newline in a header value
    # would let an attacker append arbitrary headers like ``Bcc:``.
    for k, v in headers.items():
        if "\r" in v or "\n" in v:
            raise ValueError(
                f"refusing to send: header {k!r} contains CRLF — "
                f"possible injection attempt"
            )
    header_block = "\r\n".join(f"{k}: {v}" for k, v in headers.items())
    rfc822 = f"{header_block}\r\n\r\n{body}"
    return base64.urlsafe_b64encode(rfc822.encode("utf-8")).decode("ascii").rstrip("=")

Please add a unit test covering each of the three vectors (raw subject in inbound forward, LLM-controlled to, LLM-controlled extra_headers value).

cc @kovtcharov-amd.

🟡 Important

2. Broad except Exception swallow in send_now_impl audit write. src/gaia/agents/email/tools/reply_tools.py:171-184

try:
    action_store.record_draft(db, draft_id=sent_id, ...)
    action_store.mark_draft_sent(db, draft_id=sent_id)
except Exception:
    log.warning("send_now: audit write failed for sent_id=%s ...", sent_id)

The reasoning ("don't mask a successful send") is sound, but Exception is too wide — it'll silently swallow TypeError/AttributeError if record_draft's signature drifts, masking real bugs. Narrow to the SQLite/IO surface:

        try:
            action_store.record_draft(
                db, draft_id=sent_id, to=to, subject=subject, body=body
            )
            action_store.mark_draft_sent(db, draft_id=sent_id)
        except sqlite3.Error as exc:
            # Audit-write failures must NOT mask a successful send. Log
            # but don't raise — the email already left the user's
            # account; the agent must not retry.
            log.warning(
                "send_now: audit write failed for sent_id=%s (%s) — "
                "send DID succeed but audit row missing",
                sent_id,
                exc,
            )

(Requires import sqlite3 at the top of the file. This narrows the swallow to the genuine "DB write blew up" case while keeping signature-drift bugs loud.)

🟢 Minor

3. _envelope_ok / _envelope_err is duplicated five times. It's defined identically in calendar_tools.py:23-28, delete_tools.py, organize_tools.py:29-34, read_tools.py, and reply_tools.py. Trivially extract to gaia/agents/email/tools/_common.py (or gaia/agents/email/_envelope.py) so the JSON envelope shape lives in one place — currently a future change to the envelope contract has to touch five files in lockstep, and reviewers have to verify the bodies haven't drifted.

4. Integration test reaches into private _delete() for draft cleanup. tests/integration/test_email_agent_live_gmail.py:108

live_backend._delete(f"/drafts/{draft_id}")

Either expose delete_draft() as a public method on LiveGmailBackend (one-liner — wraps _delete), or # noqa with a comment explaining the test is the only consumer. Right now it's a quiet sharp-edge: any future rename of _delete will silently break the live test (which already runs only when GMAIL_LIVE_TEST=1, so the breakage won't surface in CI).

5. Error envelope f"{type(exc).__name__}: {exc}" could leak token/PII fragments. Multiple call sites (e.g. organize_tools.py) format exceptions for the JSON envelope this way. The Gmail backend already has good token-scrub tests (test_error_does_not_leak_authorization_header), but if a ConnectorsError ever wraps something with a token in its message, this format propagates it into the LLM context. Consider running the envelope formatter through the same redact patterns from verbose.py (_REDACT_PATTERNS) before serializing. Not blocking — current tests pass — but worth a follow-up issue.

Strengths

• AC3 enforced by structure, not policy. config.py:validate() checks urlparse(base_url).hostname against an allowlist; EmailAgentConfig has no cloud-LLM field at all; the CLI handler omits --use-claude/--use-chatgpt. Three independent layers — exactly the architectural posture this should have.
• B2 ordering invariant rigorously tested. Every mutate tool is unit-tested with a "Gmail raises → no DB row" assertion, parameterized across the surface. This is the right place to spend test budget — phantom undo entries are the failure class that can corrupt the user's mailbox state.
• Prompt-injection defense is layered as designed. I1 (system prompt + <<<UNTRUSTED_*>>> delimiters), I3 (>5 ops / >3 senders batch threshold), and I4 (attack scenario fixtures) compose cleanly; the system prompt's framing of bodies as DATA is well-written.
• httpx.MockTransport driving the live backend tests is exemplary. test_gmail_client.py tests request shape, token freshness per-request, and Authorization-header scrubbing on errors — all without mocking the class under test. The token-leak test (test_error_does_not_leak_authorization_header) is the right paranoia.
• Heuristic regression tests pin the actual mistake to avoid (feat(agents): add GAIA Inbox Zero Agent for LLM-powered email triage #916). test_triage_heuristics.py explicitly asserts "Promotions" (human name) does NOT match — that's the bug the lifted heuristic would have inherited if not caught.
• Clean tool-registry isolation in conftest. tests/unit/email/conftest.py snapshot-and-restores _TOOL_REGISTRY and redirects Path.home() — exactly the right belt-and-braces for tests that touch a process-wide singleton plus a state DB.
• Pre-existing connectors_demo bug fix is the right call. Promoting required_connections=["google"] (bare strings) to ConnectorRequirement objects matches the framework contract; doing it now (when the email agent is the first real consumer) is the right time.
• Documentation surface is good. docs/guides/email.mdx covers setup, scopes, AC3, and the undo log; CLI reference is updated; nav entry in docs.json. No "ship without docs" pattern.

Verdict

Approve with required follow-up. The CRLF validation (issue #1) is small, isolated, and testable — please land it in this PR. The audit-write narrowing (#2) is also worth doing here because it's adjacent to the same review surface. Issues #3–#5 are fine as a follow-up. Once #1 lands with tests, this is ready to merge.

Summary

This is a substantial, carefully-engineered PR that lands a real Gmail integration with the rigour you'd want for an agent that mutates a user's mailbox: AC3-style architectural enforcement of local-LLM-only, three-layer prompt-injection defence, an undo-window action store, CRLF header-injection guards, and a clean Protocol-based eval seam. Test coverage is impressive (eight new unit files plus integration). Most of my comments are quality-of-life polish — no blockers found in the parts I reviewed.

Issues

🟡 Important

1. Hardcoded default model bypasses the project-wide constant — src/gaia/agents/email/agent.py:194

effective_model_id = config.model_id or "Qwen3.5-35B-A3B-GGUF"

The rest of the codebase imports DEFAULT_MODEL_NAME from gaia.llm.lemonade_client (see src/gaia/chat/sdk.py:17, src/gaia/chat/app.py:24, src/gaia/llm/providers/lemonade.py:10). When that default changes, every other entry point updates atomically — except this one. Suggest:

        from gaia.llm.lemonade_client import DEFAULT_MODEL_NAME

        effective_model_id = config.model_id or DEFAULT_MODEL_NAME

2. Triage integration test soft-skips on regression — tests/integration/test_email_agent_triage.py:110-116

# Soft gate — issue warning, don't fail until heuristic+LLM combo lands.
if accuracy < floor:
    pytest.skip(
        f"category accuracy {accuracy:.2f} below floor {floor:.2f} — "
        "LLM-fallback path not yet wired into triage_inbox_impl. "
        "This test will harden once the planning loop integrates."
    )

pytest.skip makes a real heuristic regression invisible in CI — the run goes green either way. Until the LLM-fallback wiring lands, consider pytest.xfail(strict=False) (still skipped on failure, but the result is recorded) or warnings.warn(...) plus an explicit assertion that the spam sub-floor (which is gated hard above) has not regressed. Skipping in response to a numeric threshold means the only signal you currently get from this test is "the heuristic didn't crash".

🟢 Minor

3. Dropped step in numbered comment block — src/gaia/agents/email/tools/triage_heuristics.py:218,229

The numbered rule comments jump 5 → 7 (no step 6). Either a renumbering during review missed an entry or step 6 was deleted. Re-numbering 7/8/9 → 6/7/8 keeps the block self-consistent for future readers.

4. Inline import inside __init__ — src/gaia/agents/email/agent.py:185

from pathlib import Path

Path is used unconditionally on every construction; the inline form has no lazy-load benefit and the rest of the file already imports at module top. Move to the top-of-module import block.

5. CLI test uses bare try/except SystemExit: pass — tests/unit/test_email_cli.py:1876-1881

try:
    cli.main()
except SystemExit:
    pass

This is a fine pattern for argparse-driven CLIs, but consider asserting exc.value.code == 0 (or the expected non-zero) — currently a parse error in main() would silently pass the test instead of failing with a useful message.

Strengths

• AC3 enforcement is architectural, not just documented. Stripping cloud-LLM fields from EmailAgentConfig plus the base_url allowlist makes "no cloud LLM here" a property of the config schema rather than a convention to remember. Hard to regress.
• Ordering invariant on destructive actions. Gmail call FIRST, action-store row only on Gmail success — the unit-test suite explicitly pins this with _RaisingFakeGmail so a future refactor can't reintroduce phantom undo entries. Excellent defensive design.
• Header-injection defence has actual tests. _build_rfc822 rejects CRLF/LF in to, subject, and extra_headers (so a forwarded/inbound In-Reply-To can't smuggle a Bcc:). Three explicit unit tests in test_gmail_client.py:7490-7517 lock this down.
• Token-leak guard. test_error_does_not_leak_authorization_header (test_gmail_client.py:7452-7465) is exactly the test most teams forget to write — it'll catch the day someone "helpfully" wraps httpx.HTTPStatusError and drags request headers into the error message.
• Eval seam via Protocol. GmailBackend / CalendarBackend Protocols with FakeGmailBackend swap-in let unit tests cover the full agent loop without HTTP, and tests/unit/email/test_gmail_client.py separately drives the live backend through httpx.MockTransport. Two layers of confidence with no real network.

Verdict

Approve with suggestions. None of the issues are blockers — issue 1 (hardcoded model) and issue 2 (soft-skip in CI) are worth addressing in a follow-up, the rest are stylistic. Solid landing for the Email Triage Agent.

Review — feat(email): Gmail integration for Email Triage Agent

Summary

Substantial, well-architected feature: a full Email Triage Agent built on the connectors framework, with AC3 (local-LLM only) enforced architecturally, a three-layer prompt-injection defense, and a clean Protocol-based eval seam. Test coverage is broad (unit + integration + adversarial + a token-leakage test). The change is ready to merge after addressing two non-trivial issues — a UI import-ordering breakage and an I3 batch-threshold gap that materially weakens its anti-prompt-injection guarantee for half the organize tools.

Issues

🔴 Critical

1. ConnectorsSection.tsx interleaves declarations between import statements — src/gaia/apps/webui/src/components/ConnectorsSection.tsx:22-47

const SCOPE_LABELS and function scopeLabel (lines 22-42) sit between two import groups (lines 12-20 and 43-47). ES modules hoist imports, so this still compiles, but it fails ESLint's import/first rule and is the kind of incomplete-refactor smell that produces real bugs the moment someone moves the helper or adds an import statement adjacent to it. This file is in the actively-edited UI; it will get caught by the next lint pass.

import { useEffect, useState, useCallback } from 'react';
import {
    CheckCircle2,
    AlertCircle,
    Loader2,
    ExternalLink,
    ChevronDown,
    ChevronUp,
} from 'lucide-react';
import * as api from '../services/api';
import { useChatStore } from '../stores/chatStore';
import { useConnectorsSSE } from '../hooks/useConnectorsSSE';
import type { ConnectorRow } from '../types';
import './ConnectorsSection.css';

// Human-readable labels for well-known OAuth scope URIs.
// Unrecognised scopes fall back to the last path segment of the URI.
const SCOPE_LABELS: Record<string, string> = {
    'https://www.googleapis.com/auth/gmail.readonly':        'Read emails',
    'https://www.googleapis.com/auth/gmail.modify':          'Organize emails (archive, label, trash)',
    'https://www.googleapis.com/auth/gmail.send':            'Send emails on your behalf',
    'https://www.googleapis.com/auth/gmail.compose':         'Compose emails',
    'https://www.googleapis.com/auth/calendar.readonly':     'View calendar events',
    'https://www.googleapis.com/auth/calendar.events':       'Create & respond to calendar events',
    'https://www.googleapis.com/auth/drive.readonly':        'Read Google Drive files',
    'https://www.googleapis.com/auth/drive.file':            'Manage Drive files created by this app',
    'https://www.googleapis.com/auth/spreadsheets.readonly': 'Read Google Sheets',
    'https://www.googleapis.com/auth/spreadsheets':          'Edit Google Sheets',
    'openid':   'Identify you',
    'email':    'See your email address',
    'profile':  'See your basic profile info',
};

function scopeLabel(scope: string): string {
    return SCOPE_LABELS[scope] ?? scope.split(/[/.:]/).pop() ?? scope;
}

🟡 Important

2. I3 batch-threshold collapses for five organize tools — src/gaia/agents/email/tools/organize_tools.py:250, 266, 282, 298, 314

mark_read, mark_unread, add_star, remove_star, and label_message all call agent._record_organize_op(message_id, "") with an empty-string sender. The inline comment is honest about it ("treats unknown senders as 'one bucket'"), but the consequence is that the distinct-sender arm of the I3 threshold (>3 senders) can never trip for these five tools — only the >5 ops arm can, and the threshold check is op_count AND sender_count. So an attacker who phishes the LLM into "mark every email from boss@ as read" can chain 1000 mark_read calls and the safeguard the docs/tests advertise will not fire.

This is one of three documented prompt-injection defenses. If the trade-off (one Gmail GET per op) is the right call for these specific tools, that's defensible — but the docs and the test names should not claim "I3 protects organize ops." A grep-able choice: either fetch the sender like archive_message does, or rename the threshold to bulk_mutation_threshold and document explicitly that label/read/star do not participate in distinct-sender accounting.

Cheapest fix that preserves the current architecture: have these closures do the same single-fetch gmail.get_message(...) that archive_message_impl already does (organize_tools.py:228), and pass _extract_sender(prior) instead of "". The cost is one cached HTTP round trip; the benefit is the I3 contract actually holds.

3. Live integration test reaches into a private method — tests/integration/test_email_agent_live_gmail.py:108

live_backend._delete(f"/drafts/{draft_id}")

Test cleanup uses the protected _delete because the backend has no public delete_draft. Two clean fixes:

• (a) preferred — promote delete_draft to the GmailBackend Protocol; cleaning up draft state is a legitimate caller need (any future Outlook backend will have the same need), and an end-user "discard this draft" flow is a likely Phase 2 ask.
• (b) — keep production minimal but expose a _test_delete(path) test seam so the integration test isn't paying for the leak via underscore-access.

As written, any internal HTTP-method rename will silently break this cleanup, leaving stale drafts in the test mailbox. Mark TODO if (a) is too much for this PR; the current state is OK if tracked.

4. Broad except Exception in every tool closure swallows real bugs — src/gaia/agents/email/tools/organize_tools.py (and reply/delete/calendar mirrors)

Pattern repeated ~20× in this PR:

except ConnectorsError as exc:
    return _envelope_err(str(exc))
except Exception as exc:
    log.exception("email tool error: %s", type(exc).__name__)
    return _envelope_err(f"{type(exc).__name__}: {exc}")

The ConnectorsError carve-out is right. The bare Exception catch makes a KeyError on a missing payload field indistinguishable to the LLM from a 500 from Gmail — both come back as a string envelope and the agent's planning loop is invited to "try again." That violates CLAUDE.md's No Silent Fallbacks rule: legitimate errors should propagate to the agent's centralized handler, not be turned into envelope strings inside every tool closure.

The log.exception call gives the human operator the traceback, but it doesn't undo the LLM-facing degradation. Recommend either:

• narrow to specific failure types (KeyError, ValueError, httpx.RequestError, sqlite3.Error), or
• let unknown exceptions propagate and centralize the wrapping in Agent._invoke_tool / similar.

If kept, every tool's docstring should at least say "returns {ok: false, error: ...} on any failure" so the LLM sees the contract. Right now docstrings don't reflect that envelope shape.

5. send_now_impl swallows sqlite3.Error but a full disk raises OSError — src/gaia/agents/email/tools/reply_tools.py:177

except sqlite3.Error as exc:
    log.warning(...)

The reasoning is correct: the email left the user's account, an audit-write failure must not mask a successful send. But a full disk surfaces as OSError (or a subclass of it) before sqlite3.Error ever fires, so this guard misses the most likely real-world failure. Either widen:

        except (sqlite3.Error, OSError) as exc:
            # Audit-write failures must NOT mask a successful send. Log
            # but don't raise — the email already left the user's
            # account; the agent must not retry.
            log.warning(
                "send_now: audit write failed for sent_id=%s (%s) — "
                "send DID succeed but audit row missing",
                sent_id,
                exc,
            )

…or document explicitly that disk-full raises through the agent (and get reviewer alignment that that's the desired behavior).

🟢 Nits

6. CLI context-size = 32k may be tight for 50-message triage — src/gaia/cli.py (email: 32768)

Triage default is max_messages=50, body limit 4000 chars (read_tools.DEFAULT_BODY_LIMIT_CHARS). 50 × ~4kB = 200kB ≈ 50k tokens before subjects/labels — already over the 32k allotment. The code likely gets away with it because most triage messages are short, but a worst-case batch will overflow. Either raise the default to 65536 to match code, or bound max_messages in the triage tool.

7. Redaction regex over-matches on Message-ID headers — src/gaia/agents/email/verbose.py:45

re.compile(r"(?=[A-Za-z0-9_\-]{40,})(?=[A-Za-z0-9_\-]*\d)[A-Za-z0-9_\-]{40,}"),

Any 40+-char alphanumeric token containing a digit is redacted. RFC 5322 Message-IDs commonly look like [email protected] — the local-part alone often exceeds 40 chars and contains digits. Effect: log lines lose Message-ID context. Low impact (logs only) but a quick win is to anchor the pattern to known token shapes (e.g., Bearer\s+...) or skip strings containing @.

8. Override key duplication between formatting.py and scopes.py

gaia.connectors.formatting._AGENT_GRANT_MIGRATION_MESSAGES keys on "builtin:email"; that constant also lives in gaia.agents.email.scopes.AGENT_NAMESPACED_ID. Two places to update if the namespace ever changes. Consider importing the constant in formatting.py if there's no circular-import barrier.

9. tests/unit/agents/test_email_agent_local_llm_enforcement.py:6537-6541 test_lemonade_env_var_added_to_allowlist — fine, but the URL host gpu-host.local doesn't match _LOCAL_HOSTS, so this test is the only thing exercising the env-allowlist code path. Worth pinning that fact in the comment so a future hardener doesn't delete the env-var arm thinking it's redundant.

Strengths

• AC3 enforced architecturally, not by convention. EmailAgentConfig has no cloud-LLM field; validate() raises with "AC3" in the message. test_email_subcommand_does_not_pass_use_claude pins that the CLI namespace doesn't surface those flags. The combination — config + CLI + parametrized allowlist test (test_remote_hosts_rejected over openai/anthropic/googleai/example.com) — makes regressions hard to introduce silently.
• Eval seam via Protocol. GmailBackend / CalendarBackend Protocols + FakeGmailBackend(mbox_path) lets the eval harness run without OAuth, and the fake returns Gmail-API-shaped JSON, not stdlib email.Message, so the unit tests exercise the same parsing code as the live path.
• Three-layer prompt-injection defense, all three layers tested:
  • I1 — <<<UNTRUSTED_EMAIL_BODY_*>>> delimiters + system prompt that names them and gives concrete attack examples (test_system_prompt_warns_about_specific_attack_patterns).
  • I3 — per-turn organize counter with explicit boundary tests at the (5, 3) edge.
  • I4 — phishing payload baked into the stub mbox so the wrapper-placement is verifiable end-to-end (test_phishing_body_appears_inside_untrusted_wrapper).
• CRLF header injection defense in _build_rfc822 with explicit cases for \r\n in to, bare \n in subject, and CRLF in extra_headers — covers the realistic attack via reply-threading where In-Reply-To is built from inbound mail.
• "Gmail call first, DB write only on success" ordering invariant parametrized over archive / label / trash so any future mutator gets the same test. Adversarial B2 covered.
• Token freshness made observable. TestTokenFreshness.test_each_request_invokes_access_token_fn proves per-request token refresh, not "fetch once and reuse."
• Explicit token-leakage-in-error test. test_error_does_not_leak_authorization_header is the right kind of paranoid test.
• HTML body stripping (script/style/head/meta). Drops both the visible HTML noise and the hidden-instruction-via-<style> attack vector before delimiter wrapping.
• Test isolation belt-and-braces. _autouse_isolate_home redirects Path.home() to tmp_path, and _autouse_snapshot_tool_registry saves/restores _TOOL_REGISTRY between tests — both prevent the kind of cross-test pollution that this codebase has been bitten by before.
• Pre-existing bug fixes carried as part of the PR: connectors_demo was passing bare strings as required_connections instead of ConnectorRequirement objects (registry.py:385); google catalog was missing gmail.modify — and a regression test (test_google_catalog_declares_gmail_modify_scope) is named explicitly so it's grep-able.
• Docs are complete and consistent. docs/guides/email.mdx covers setup/CLI/privacy/troubleshooting; docs/docs.json updated; docs/reference/cli.mdx has the email row. AC3 language matches the code.

Verdict

Approve with changes. Issues 1 (UI imports) and 2 (I3 sender bypass) need to land before merge — both are small mechanical fixes. Issues 3-5 are defensible-as-is if the author wants to track them in follow-ups; I'd push for at least 4 to be addressed because the silent-fallback pattern is explicitly called out in CLAUDE.md as the kind of thing that turns into long-tail bugs. Strengths far outweigh the issues — the AC3 architectural enforcement and the prompt-injection defense layering are exemplary.

Summary

Substantial, well-architected addition: an EmailTriageAgent with Gmail + Calendar wired through the connectors framework, a Backend Protocol seam for eval, three-layer AC3 (local-LLM-only) enforcement, prompt-injection hardening (untrusted-body delimiters + batch-threshold counter), an undoable action store, and broad test coverage (unit + integration + adversarial). Mixin composition is clean and the ordering invariant ("Gmail call before DB write") is pinned by parameterized tests for every mutator. The connectors_demo bare-string bug fix and the SCOPE_LABELS/connector_id UI rename are appropriate cleanups.

A few issues to address before merge — most importantly a per-turn counter that never actually resets per-turn, which both contradicts its docstring and weakens the I3 batch-threshold protection it was added to enforce.

Issues

🟡 Per-turn organize counter never resets between turns

src/gaia/agents/email/agent.py:179-189 and agent.py:221-232

The docstring says "Reset per process_query() call by _reset_organize_counter", but _reset_organize_counter is only called from _register_tools (line 227), which runs once at agent construction. Across multiple turns in the same agent instance (the normal Agent UI / chat case) the counter accumulates indefinitely:

• Turn 1: archive 4 emails → counter = 4
• Turn 2: archive 3 more across 2 new senders → counter = 7, senders = 4 → batch threshold trips spuriously, blocking a legitimate request

The test_reset_zeroes_counters unit test only verifies the function works when called explicitly — there's no test asserting it fires per turn. Either wire _reset_organize_counter() into a per-turn hook (override process_query or a turn-start callback in the base Agent), or update the docstring to say "reset at construction only" and accept the multi-turn accumulation as known behavior — but the latter materially weakens the I3 protection (after a few normal turns, the threshold trips on every action and users learn to click through).

        # I3 — batch-organize counters. Reset at the start of every
        # process_query() turn via _on_turn_start. Per-turn isolation is
        # essential — accumulating across turns trips the threshold on
        # legitimate sequential requests.
        self._organize_op_count = 0
        self._organize_distinct_senders: set[str] = set()

…and add the per-turn reset (e.g. override process_query or whichever turn hook the base Agent exposes) so the counter actually rolls over. Also add a regression test:

def test_organize_counter_resets_between_turns(agent):
    agent._record_organize_op("m1", "[email protected]")
    asyncio.run(agent.process_query("any noop"))
    assert agent._organize_op_count == 0

🟡 Live-Gmail smoke test's "no send" guard is a tautology

tests/integration/test_email_agent_live_gmail.py:94-99

The comment says "the agent in this test must NEVER have send_draft bound" and "a refactor that accidentally calls send raises AttributeError on a method that doesn't exist on this fixture", but:

1. The test never constructs an agent — it talks to LiveGmailBackend directly.
2. The assertion checks for _send_for_smoke, a literal made-up attribute name commented # placeholder. It always passes.
3. LiveGmailBackend.send_draft and send_message do exist (gmail_backend.py:545).

So the Adversarial S5 protection described in the docstring is not actually exercised. Replace the placeholder with a real safeguard — wrap the backend in a no-send proxy, or assert the methods are deliberately monkey-patched out:

        # Real S5 guard: a refactor that accidentally invokes send_*
        # against this fixture must AttributeError, not silently send.
        for forbidden in ("send_draft", "send_message"):
            assert not hasattr(live_backend, forbidden) or getattr(
                live_backend, forbidden
            ).__name__ == "_blocked_in_smoke", (
                f"live_backend.{forbidden} is callable in a smoke test — "
                f"a regression here would dispatch real mail."
            )

…or, more simply, wrap the live backend in a class that explicitly removes those methods before yielding it.

🟡 Live-test cleanup silently swallows draft-delete failures

tests/integration/test_email_agent_live_gmail.py:107-110

try:
    live_backend._delete(f"/drafts/{draft_id}")
except Exception as exc:
    print(f"WARN: live_backend._delete failed: {exc}")

Per the "no silent fallbacks" rule in CLAUDE.md, except Exception: print masks real cleanup failures. Combined with the docstring claim at lines 22-24 ("Post-teardown assertion: the marker subject must not match any draft after cleanup") which isn't actually implemented, an orphan draft can be left in the user's real Gmail account silently.

Either implement the promised post-teardown sweep or re-raise the cleanup error after logging. At minimum:

        try:
            live_backend._delete(f"/drafts/{draft_id}")
        except Exception as exc:
            pytest.fail(
                f"draft cleanup failed for id={draft_id} marker={marker!r}: "
                f"{exc}. An orphan smoke-test draft may be in your account; "
                f"search Gmail for the marker subject and delete manually."
            )
        # Post-teardown sweep — confirm no draft with the marker remains.
        leftover = [
            d for d in live_backend.list_drafts(max_results=50).get("drafts", [])
            if marker in (d.get("subject") or "")
        ]
        assert not leftover, f"orphan drafts after cleanup: {leftover}"

🟡 Triage integration test under-delivers on AC4 docstring

tests/integration/test_email_agent_triage.py:11-15 and lines 96-116

The module docstring promises "AC4 verification … the test asserts current >= baseline - tolerance so a regression on the LLM/model is detected", but in practice only spam is hard-asserted (line 96). Category accuracy uses pytest.xfail (line 112), which is informational and does not fail CI — a category-accuracy regression would slip in as a "yellow" marker most reviewers ignore.

If LLM-fallback isn't ready, weaken the docstring claim rather than the gate. If you want the gate now, change pytest.xfail to pytest.fail or assert accuracy >= floor. As-is, the docstring oversells the protection:

"""
Integration test for end-to-end email triage against a live Lemonade.

Skipped automatically when Lemonade is not running (via ``require_lemonade``).
The test loads the synthetic stub mbox into a ``FakeGmailBackend`` and
runs the agent's triage tool end-to-end, comparing per-message
classifications to ``ground_truth.json``.

PARTIAL AC4 verification: spam classification is hard-gated (label-driven,
deterministic). Category accuracy is currently soft-gated via ``pytest.xfail``
because the heuristic-only path has structural ceilings; the gate will tighten
to ``assert accuracy >= floor`` once the LLM-fallback path lands.
"""

🟢 Stale docstring on OAuthPkceHandler.get_credential return shape

src/gaia/connectors/oauth_pkce.py:43-46

The class docstring still claims:

{"access_token": str, "expires_at": int, "scopes": [str]}

but the actual return at lines 73-76 no longer includes expires_at (this PR removed the tuple destructuring of get_or_refresh, which has long returned just a str). Drop expires_at from the docstring:

    ``get_credential`` returns an access-token dict compatible with
    Google's token endpoint; the dict shape is:
      ``{"access_token": str, "scopes": [str]}``

🟢 Stale comment in registry refers to renamed field

src/gaia/agents/registry.py:377-384

The fix-up comment for the connectors_demo bare-string bug references ".provider/.scopes/.reason" but _reg_to_info (agents.py:95) now reads .connector_id. Tiny doc rot:

                    # #962 fix — pre-existing bug: this previously listed
                    # bare provider strings (``["google", "mcp-github"]``)
                    # but ``AgentRegistration.required_connections`` is
                    # typed as ``List[ConnectorRequirement]`` and the UI
                    # router calls ``.connector_id``/``.scopes``/``.reason``
                    # on the items. Bare strings silently broke
                    # ``_reg_to_info`` in agents.py. Convert to the
                    # canonical objects so the registry stays consistent.

Strengths

• AC3 enforcement is exemplary defense-in-depth: surface (no use_claude field), validation (base_url allowlist with LEMONADE_BASE_URL extension), and tests at all three layers (test_email_agent_local_llm_enforcement.py, parametrized field-name forbidlist, host-rejection with explicit "AC3" mention in the error).
• CRLF header-injection defense in _build_rfc822 validates to, subject, and extra_headers — covers the forwarded-Subject vector that's easy to miss. Pinned by test_gmail_client.py:8009-8054.
• Untrusted-body delimiter pattern is a genuinely good prompt-injection mitigation: the system prompt names the delimiter, every body returned to the LLM is wrapped, and the unit test verifies the wrap is present and contains the suspicious phrase (test_email_agent_prompt_injection.py:6838-6852).
• Adversarial B2 ordering invariant pinned by parameterized tests — every mutator (archive, label, trash) raises on Gmail failure with zero rows in email_actions. Easy to grep, hard to silently regress (test_email_agent_tools.py:7215-7247).
• Token-per-request discipline verified by httpx.MockTransport (test_gmail_client.py:7919-7946) — three list calls produce three token fetches, and the Authorization header uses the value the function returned at call time. Catches the stale-token-cache class of bug.
• Token leak guard (test_gmail_client.py:7972-7985) — error path explicitly excludes the Bearer token from the message body. Worth keeping forever.
• Body preview truncation to 100 chars prevents accidental persistence of MFA codes / JWT tokens / URLs in the action log (action_store.py). The redaction pattern in verbose.py complements this nicely.
• connectors_demo bare-string bug fix in registry.py — converting ["google", "mcp-github"] to canonical ConnectorRequirement objects stops the silent UI breakage. Thank you for catching this in passing.
• _reg_to_info rename provider → connector_id unifies naming with the frontend (ConnectorsSection.tsx:537) and matches ConnectorRequirement.connector_id. Test updated correctly (test_agent_required_connectors.py:8367).
• Backend Protocol with Live + Fake parallel implementations is the right shape for the eval seam — the heuristic test (test_triage_heuristics.py) is independent of any LLM and pins the system-label-ID matching contra PR feat(agents): add GAIA Inbox Zero Agent for LLM-powered email triage #916's human-name regression.
• Doc coverage is comprehensive: docs/guides/email.mdx, docs/reference/cli.mdx, and docs/docs.json all updated.
• @pytest.mark.gmail_live marker properly excluded from CI so the live test never hits real Gmail in automation.

Verdict

Request changes. All four 🟡 items are tractable: the counter-reset bug is a 5-line fix plus a test; the live-test placeholder, cleanup except: print, and triage docstring are localized to single files. Once those land, this is a strong, well-tested foundation for the email pipeline and a good model for the upcoming Outlook backend (#963).