# Proctoring & AI Policy

> What the apps record during an exam, the event feed you can read, and how AI assistance is governed.

Canonical: https://grout.app/developer/documentation/exams/proctoring/

## Proctoring requirements

`proctoring: { camera, microphone, screen }` on an exam lists what the student must grant before the exam opens. The app records in segments and uploads them with the submission. Recordings never leave the institution: guardians cannot see them, and the API only returns their URLs to keys with `submissions:write`.

## Event feed

Every attempt keeps a rolling log of events the app observed. Read it per submission:

```bash
curl $API/submissions/sub_…/events -H "Authorization: Bearer $KEY"
```

```json
{ "attempt": { "id": "att_…", "started_at": "…", "expires_at": "…", "hidden_released_at": "…" },
  "counts": { "focus_lost": 3, "sample_tests_run": 5, "submitted": 1 },
  "events": [ { "type": "focus_lost", "at": "2026-09-14T10:03:12Z" }, { "type": "focus_gained", "at": "…", "detail": { "away_seconds": 14 } } ] }
```

| Type | Meaning |
|---|---|
| `attempt_started`, `attempt_resumed`, `attempt_abandoned` | Attempt lifecycle |
| `focus_lost`, `focus_gained{away_seconds}` | Window lost/regained focus |
| `screen_locked`, `screen_unlocked`, `system_suspend`, `system_resume` | OS-level interruptions |
| `recording_started`, `recording_stopped`, `recorder_error`, `segment_uploaded`, `segment_upload_failed` | Recorder health |
| `sample_tests_run{passed,failed}`, `hidden_tests_released` | GroutCode test activity |
| `submitted{submission_id}` | Final submission |

Use `counts` for quick flags (many `focus_lost`, a `recorder_error`) and the raw list for review.

## AI policy

`ai_policy: { allowed, model_tier, max_interactions }` governs the in-app assistant for the exam:

- `allowed: false` disables it entirely.
- `model_tier`: `any`, `cloud` (hosted models only) or `local` (on-device models only).
- `max_interactions`: budget per attempt.

The policy is enforced by the app; what the student actually used is reported at submit in `ai_usage_data` (`total_interactions`, `models_used`, and for GroutCode the transcript attachment).

Institution-wide defaults can be stored in `PUT /institution/config` (`default_ai_policy`, `default_proctoring`, `allowed_toolchains`); new exams created in the portal inherit them in a future app release.