Expose enabled vs gated commands at connect time (#324)

[tig]

Closes #324.

Problem

A freshly provisioned session enables the standard observation/actuation tools (ToolCatalog.ProvisionedByDefault) but leaves launch and every raw send_command built-in (chars:, winr, mouse:, VK_* keys, chords) gated. Per the #318 field report, an agent could only discover that set by hitting command-disabled one command at a time.

Change

Expose the enabled/gated split at connect time so the agent can batch a single request-command-access before its first actuation.

• initialize result now carries a commandAccess object:

  {
    "enabledTools": ["capture","query","displays","windows","window","find","wait-for","invoke","drag","click","focus","clipboard","record"],
    "gatedTools": ["launch"],
    "rawSendCommandGated": true,
    "note": "Gated commands need the operator's consent before first use: call request-command-access ... in ONE call ..."
  }

  Derived from ToolCatalog.CommandAccessDefaults (the ProvisionedByDefault flags) — single source of truth in code, so it never drifts as provisioning defaults change (acceptance criterion Possible to Map Command to Key Combo? #2). Omitted in bootstrap mode (only tools are provision-session/end-session; no gated surface).

• session-start / session-status results stamp the live table via AgentToolExecutor.LiveCommandAccess, so an agent can re-check that a grant landed. Both surfaces share one builder (ToolCatalog.CommandAccessMap) and note, so shape/guidance can't diverge.

• Connect-time prose (AgentInstructions.md PROVISION / COMMAND ACCESS) now points at the field instead of relying on trial-and-error; docs (agent_control.md, AGENTS.md) updated.

Why initialize over the provision handoff (issue Option A)

BuildAgentPrompt only renders on the operator's "Provision new…" dialog — a self-provisioning agent (bootstrap → provision-session → reconnect) never sees it, and it's operator-pasted prose decoupled from the instance. initialize is true connect-time, zero round-trip, reaches every path, and (via session-status) gives live post-grant accuracy.

Note on the "one call" goal

The realistic win is knowing the shape up front (launch + raw built-ins gated) so the agent batches the built-ins its plan uses in one round — it still can't enumerate specific built-ins it hasn't planned yet, so the target isn't literally zero command-disabled ever.

Acceptance

• Agent connecting to a provisioned instance sees which commands need consent before first actuation (initialize.commandAccess).
• List stays accurate when provisioning defaults change — derived from ToolCatalog, not hand-maintained prose.

Tests

• Dispatch_Initialize_IncludesCommandAccessDefaults — launch gated, capture/invoke enabled, rawSendCommandGated true, every gated name is a real catalog tool.
• Dispatch_SessionStatus_IncludesLiveCommandAccess_ReflectingTheTable — live table drives the split; an enabled launch/chars: flips out of the gated set.
• Full xUnit suite green (1039 passed, 22 skipped).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e010a4f9cf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".