E1707. Approval identity required

Severity: ERROR. Class: HITLIdentityRequired (subclass of RuntimeError).

What happened

No top-level email key in ~/.controlzero/config.yaml (written by controlzero install <agent> --email <addr>). The SDK refuses approval traffic.

Why it matters

Approvals need a human identity. The API key is a machine credential; it doesn't tell us who triggered the request.

How to fix

Run controlzero install <agent> --email <your-email> (for example controlzero install claude-code --email you@example.com). This writes the top-level email key into ~/.controlzero/config.yaml, which is the only place the SDK reads the operator email from. In CI or other non-TTY environments, pass --email explicitly at install time. There is no CONTROLZERO_REQUESTOR_EMAIL environment variable and no user_email= constructor argument.

Catching this error

except RuntimeError catches this. Setup error.

See also

• Approval Workflow. The parent concept
• SDK: Approval callback. The request_approval + wait API
• Errors index