feat: AI command intent analysis on approval prompts

[jasmine889966]

What

Before surfacing an approval prompt, ask the model to summarize what the command will do in a couple of bullet points, so the consequences are clear at a glance.

When the engine decides a tool call needs_user, it runs one extra single-turn provider.complete (tools disabled, mirroring the compaction summarize_span pattern) and attaches the result as intent on the PERMISSION_REQUIRED event. The approval card renders it as a short, restrained annotation — transparent background, a small CSS dot, secondary-grey text, with the most critical terms bolded.

Why

Approval prompts today show the raw command and ask the user to decide. For anyone who isn't fluent in shell (or the specific tool's args), "is this safe to allow?" is a real question. A two-bullet, plain-English summary of the consequences turns the approve/deny decision from "do I trust this string?" into "do I accept these outcomes?".

How

• Dependency injection, off by default. TurnEngine gains an optional intent_analyzer callable (default None = feature off, upstream behavior unchanged). None short-circuits before any work, so this is a strict no-op for callers that don't opt in.
• Opt-in. The feature defaults to off; users enable it in Settings ("Explain commands before I approve them"). This keeps it a strict no-op for existing tests (which drive approvals through scripted providers) and for users who don't want the extra round trip.
• Synchronous, before the card. Analysis runs inside _authorize, before PERMISSION_REQUIRED is emitted, so the card appears already annotated (no loading flicker). The call sits inside _interruptible so a user Stop resolves immediately, and a wait_for timeout is swallowed by try/except — the approval flow never crashes on a slow/failed analysis (it degrades to no annotation).
• Carried through every path. The annotation rides on both the live event payload and PermissionRequest.intent, and approval_prompt_data writes it into the Inbox snapshot, so unattended/reconnected cards show it too.

Notes

• 20s timeout covers cloud-model tail latency (the analyzer runs the session's own model, which may route through a provider with non-trivial first-token latency). The approval flow is unaffected on timeout — it just renders without the annotation. Happy to tighten if a smaller bound is preferred.
• The opt-in default was chosen after CI showed that defaulting to on consumed a scripted provider response in upstream approval tests. Flipping back to opt-in fixed them.

Files

• coworker/intent_analysis/ — new module: prompts.py (English system prompt), analyzer.py (extract the operation description from the tool call, run one round trip, clean to bullet lines).
• coworker/engine.py — PermissionRequest.intent, TurnEngine.__init__ params, the _authorize analysis branch.
• coworker/agent.py — build_engine forwards intent_analyzer.
• coworker/server/manager.py — injects the analyzer at both build_engine sites when the pref is on, carries intent through approval_prompt_data, exposes the pref via get_settings / set_intent_analysis.
• coworker/server/app.py — POST /v1/settings/intent-analysis.
• GUI — render the annotation on the live card and the Inbox card, plus a Settings toggle.

Tests

• tests/test_intent_analysis.py — prompt construction, input extraction, output cleaning, analyzer success/failure/empty.
• tests/test_engine_intent.py — the None/success/timeout-no-crash/raises/stop branches of _authorize, build_engine passthrough, manager intent carry-through, and the REST toggle roundtrip.
• ApprovalCard.test.tsx — annotation renders when present, is absent when missing, and forces the full card for routine file writes (which otherwise render as a compact one-line row).

All backend tests pass (including the upstream test_durable_resume / test_ui_refresh approval tests); frontend tests are type-checked and follow the existing render/getByText pattern.