Required updates for Watcher

In enforce mode, a tool call that needs grading now waits for a Watcher client that is not running. If the client does not answer in time, Watcher denies the call. The call no longer goes to the coding agent's own permission flow. Check that enforce-mode machines and containers keep the client running before you update.

Admins and org-viewers can inspect flagged calls' inputs and results without full session access.

Watcher resolves user roles from one YAML policy and checks the resulting permissions across the API and Analyzer.

What's new?

• This applies to Claude Code, Codex and GitHub Copilot CLI in enforce mode. When a call needs grading and the Watcher client does not answer, the hook waits for it. That happens while the client starts, while it restarts after a crash or an update, and after someone quits it. If the client answers, the call is graded as usual.
• If the client does not answer within the wait, Watcher denies the call. The wait lasts about 10 seconds, or up to two minutes while the client is starting up or updating, counted from when it stopped answering. The reason says that the Watcher client on the machine did not respond. It asks the developer to run watcher doctor in a terminal. The call does not go to a permission prompt. Your organization's on_grading_failure setting does not apply, so a container set to allow gets the denial too.
• Calls made during the same outage share one wait. A long outage costs one wait, and later calls are denied quickly.
• Calls that terminal thresholds or command rules decide never wait.
• In enforce mode, the hooks log watcher not running (...); enforce mode waits for it if the call needs grading. Cases that do not wait keep logging watcher not running ... falling through to native permission flow.
• These cases do not wait and behave as before: observe mode, paused mode, a snooze, a .watcher-ignore file, a machine that is signed out or whose credentials the deployment rejects, an unavailable credential helper, and the one-minute grading pause after repeated failures to reach the deployment. A Watcher server or grading provider that fails while the client answers still takes the configured failure decision. See When the Watcher client is not running.
• Both roles gain tool-calls:content:read:flagged. Other content restrictions are unchanged.
• Always-ask prompts qualify; grading-failure fallbacks do not.
• WorkOS supplies identity and role assignments. Its user-token permissions only grant access to the two supported WorkOS widgets. Proxy roles use the same YAML policy for Watcher permissions.
• Watcher Cloud uses the shipped role defaults. Cloud customers cannot edit their definitions. Self-hosters can replace role lists and add custom roles.
• An empty role list grants no Watcher permissions, including for admins. WorkOS widget access is separate. Ownership and temporary session approvals still permit their scoped access.
• Missing or unknown proxy roles no longer select member; they grant no permissions, matching WorkOS role resolution.
• Clients need org:managed-settings:read or org:settings:read to fetch resolved managed client settings.
• API keys retain their explicit scopes. The internal: namespace is reserved for server jobs and cannot be granted by user roles or API keys.

Required upgrade steps

Enforce mode waits for the Watcher client

These steps apply to self-hosted deployments and Watcher Cloud. They matter for machines and containers whose enforcement mode is enforce.

1. Make sure every enforce-mode container starts the client before the agent, detached with setsid, and keeps it running. A container whose client is not running gets denied calls after the wait. See What has to be true inside the container.
2. Tell developers on enforce-mode machines to keep the client running, and not to quit it to pause reviews. To pause reviews on purpose, they can snooze grading or use a .watcher-ignore file where your organization allows it. For machines that should not be reviewed, an admin can change the enforcement mode in the managed settings.
3. Roll the new client out with Update Watcher. The change takes effect on each machine when its client updates.
4. To verify, use an updated test machine in enforce mode. Run watcher autostart stop, then ask Claude Code to run echo "$HOME", which needs grading. watcher logs hooks shows the enforce mode waits for it line. After the wait, the call is denied with a reason that suggests watcher doctor. Run watcher autostart start to start the client again.

Access to flagged tool calls

Self-hosted: review org-viewer assignments before upgrading. Watcher Cloud: review org-viewer assignments; Apollo manages rollout timing.

Self-hosted deployments can retain findings-only access by overriding the role's grants without tool-calls:content:read:flagged or sessions:content:read:any. This applies to both WorkOS and proxy mode. Cloud uses the shipped role defaults.

Self-hosted: follow Update Watcher. Verify as an org-viewer in another user's session: flagged-call content is visible; routine-call content and the transcript remain restricted.

Roles resolved from YAML

1. All deployments: audit assigned roles and existing WorkOS grants against the intended YAML, including integrations that relied on custom grants or admin wildcard access. Keep org:managed-settings:read or org:settings:read for clients that pull configuration, including API-key clients. Remove any reserved internal: grants from API keys and custom integrations.
2. Self-hosted deployments: prepare a separate copy of role YAML for the target release. Each override replaces the whole list; include every grant to retain. Use only public Watcher permission names. Widget permissions belong in WorkOS, outside YAML. Fix typos and remove unsupported grants before deployment; invalid configuration prevents startup. Omitted roles keep shipped defaults. Leave the mounted file unchanged until deploying the new image: older images reject roles. In proxy mode, configure the trusted proxy to send a configured role name for each user, including member explicitly where intended. Missing, blank, or unknown role headers no longer receive member grants.
3. WorkOS deployments: the environment owner checks the two widget grants on admin and reviews any grants on other roles or organization-level overrides. Setup commands leave existing roles and grants unchanged. Refresh user tokens after changing provider grants or role assignments; old tokens retain widget access until expiry.
4. Deploy the target image and prepared YAML together. Self-hosters follow Update Watcher; Kubernetes users supply the file through Helm with the target chart and matching image tag. Once every API replica loads the new policy, verify each credential, an allowed and a denied API operation, and both Analyzer widgets. Check that a removed admin grant stays absent.