Skip to main content
Working with an agent? Give them a link to this page as markdown.

Required updates for Watcher

POST /api/v1/hooks/aperture now serves every Tailscale Aperture hook stage. Watcher reads metadata.stage to tell them apart. The separate /api/v1/hooks/aperture/pre-request and /api/v1/hooks/aperture/pre-response URLs are removed. If you configured Aperture enforcement with either of them, update Watcher first, then point those hooks at /api/v1/hooks/aperture.

The server now refuses requests from Watcher clients that report a version older than 0.41.0, the first release that grades through the server's managed monitors. Their requests get HTTP 426 with a message to run watcher update (on releases before 0.19.0, which lack that command, to uninstall and re-run the installer), except grade requests, which get that message as a maximum score so the client stops the tool call instead of letting it through. The server's version check stays open to those clients, so updating works as before.

Custom and MCP tool names are hashed in server logs.

The self-host release ZIP includes the Watcher Helm chart alongside the Docker Compose files.

The managed monitors replace Watcher's original built-in graders, and this release retires them. Summarize, Default - Security and Agent Reliability are archived, along with the 2026-08 versions of Policy Triage and Policy Gateway. The current Policy Triage and Policy Gateway are hidden but keep running, because Watcher clients older than 0.41 grade every gated tool call with them; a later release archives them as well.

Watcher no longer ingests sessions from an S3 bucket. That path had been paused since the gateway hook endpoint replaced it, so no working feature goes away. Its leftovers are removed from the API and the Python SDK.

The managed monitors now take policy only from their built-in rubric and your organization's custom instructions. Earlier clients read a WATCHER.md file from the project folder and from ~/.apollo_monitor/ and sent its text with each graded call. Any process that can write a file on the developer's machine, including the coding agent being monitored, could use that file to loosen review.

What's new?​

  • POST /api/v1/hooks/aperture adds Watcher's notice to pre_request deliveries. It decides on the pending tool calls in pre_response deliveries. It observes post_complete deliveries, and deliveries that name no stage, as before. Existing observation subscriptions to this URL or to /api/v1/hooks/aperture/entire-request keep working unchanged.
  • A refused tool call no longer withholds the allowed calls in the same response where per-call edits are possible. Watcher replaces each refused call with a notice through the agent's own shell tool, or removes it, and the allowed calls still run. A refused Gemini call, and an escalation no notice can carry, still block the whole response. This uses the per-call edits in current Aperture releases.
  • Gemini tool calls can now be enforced. Before, they always failed closed.
  • The enforcement setup now shows two hook entries on the one URL: a fail-open hook for the notice and observation, and a fail-closed hook for enforcement.
  • In the Python SDK, aperture_pre_request_hook and aperture_pre_response_hook are replaced by aperture_hook. Set metadata.stage in the payload to pre_request or pre_response; it returns AperturePreRequestResponse or AperturePreResponseResponse respectively. A payload without a stage is treated as an observation and returns ApertureHookAccepted. aperture_entire_request_hook is unchanged.
  • A refused client stops every gated tool call until it updates. Instead of grading the call, the server answers with the upgrade message as a maximum score: on the Auto profile the call is denied with that message, and on the default profile the user is asked to approve it, with the message in the prompt. Command rules and per-tool thresholds still apply first.
  • The server rejects a refused client's uploads, so its sessions aren't recorded until it updates; sessions a gateway records independently are unaffected.
  • Clients older than 0.15.1, and clients whose user agent was changed with WATCHER_HEADER_USER_AGENT, don't report their version, so the server can't identify them and keeps serving them. They still need updating.
  • Clients of every supported release send their version with each request, so nothing else changes for them. The Python SDK, the Analyzer and other integrations are not affected.
  • Non-built-in names use mcp:HASH when starting with mcp__, or custom:HASH otherwise. HASH is the first eight lowercase SHA-256 hex digits of the full UTF-8 name (no newline). Built-in names and stored tool calls are unchanged.
  • The chart is in watcher-self-host/chart/ after you extract the ZIP.
  • Its chart version, app version, and default image tag match the release.
  • Follow Kubernetes infrastructure to deploy into an existing cluster. The chart does not provision a cluster.
  • A grade call (POST /api/v1/grade, or grade in the Python SDK) skips the archived graders. A call that names only archived graders is rejected with 400, and the error names them; one that also names a runnable grader returns that grader's grades alone. Past grades from every retired grader stay visible in the Analyzer and the API.
  • None of the retired graders appear in grader lists or on the Analyzer's Monitors page any more, so the Analyzer no longer offers them to copy. Through the API, fetching an archived Summarize, Default - Security or Agent Reliability by ID still returns it for copying into a custom grader. Policy Triage and Policy Gateway, current and 2026-08, are hidden from customer credentials.
  • Plan to bring every Watcher client to 0.41 or later. Clients older than 0.41 still grade through Policy Triage and Policy Gateway. Once those are archived, grading fails on those clients, and on the Auto profile they then allow gated tool calls without grading, because that profile ships with on_grading_failure: allow. The release that archives them will say so.
  • GET /api/v1/organization/settings no longer returns polling_enabled, s3_input_prefix, s3_output_bucket, s3_output_prefix or s3_assume_role_arn. PATCH rejects a request that sends any of them with 422.
  • The Python SDK no longer has the ApertureLog type, and an aperture-log upload to POST /api/v1/ingest is rejected with 422. The server had already stopped accepting that format.
  • The Watcher client no longer reads WATCHER.md from the project folder or from ~/.apollo_monitor/.
  • The server ignores the grading_guidelines field of a monitoring input, whether an older client, a gateway hook or the Python SDK sends it. Requests that include the field are still accepted.
  • Tool calls are graded by the built-in rubric and your custom instructions alone. A call that a WATCHER.md file loosened may now be escalated or denied, and a call that a file asked to be escalated may now be allowed.

Required upgrade steps​

One Aperture hook URL, and per-call decisions for pending tool calls

These apply to self-hosted deployments and to Watcher Cloud. Skip them if no Aperture hook points at /pre-request or /pre-response.

  1. Update Watcher on every server first. The old URLs then return HTTP 404: Aperture withholds pending calls on a fail-closed enforcement hook and skips the notice on a fail-open one, so nothing runs unchecked. Do not change the URLs before the update. On an older server /api/v1/hooks/aperture only observes, so an enforcement hook pointed there early would not hold calls.
  2. In the Aperture configuration, change the url of every hook that ends in /api/v1/hooks/aperture/pre-request or /api/v1/hooks/aperture/pre-response to end in /api/v1/hooks/aperture instead. Keep each hook's other settings.
  3. To verify, run one agent turn with a tool call through the enforced grant. The call runs or gets a Watcher notice; the answer is not guardrail hook unavailable.

To roll back to an earlier version, restore the old hook URLs first, then roll back Watcher.

Watcher clients older than 0.41.0 are refused

These steps apply to self-hosted deployments and Watcher Cloud organizations.

  1. Bring every Watcher client to 0.41.0 or later. A client installed with the public installer and running through its login agent updates itself within about two and a half hours of reading the server's version. Update the others yourself: run watcher update on clients that run only in the foreground or predate the automatic check, reinstall a client from a release that predates watcher update, and publish 0.41.0 or later to an internal mirror (see Update Watcher clients).

See Update Watcher for the update procedure.

Custom tool names in server logs

Self-hosted operators: when upgrading, update any log filters or alerts matching these names to the hashed values and check they still match. No action otherwise.

Built-in graders from before the managed monitors are retired

These steps apply to self-hosted deployments and Watcher Cloud organizations that grade through the API.

  1. Replace any script or integration that grades with Summarize, Default - Security or Agent Reliability, or with the 2026-08 Policy Triage or Policy Gateway. Grade tool calls with the managed monitors by role (POST /api/v1/monitors/triage/grade or /api/v1/monitors/gateway/grade), adding organization rules as custom instructions, or copy the archived grader into a custom grader and grade with that.

See Update Watcher for the update procedure.

S3 ingestion settings are removed

These steps apply to self-hosted deployments and Watcher Cloud organizations whose scripts call the organization settings API or import ApertureLog.

  1. Remove the five S3 fields above from any PATCH /api/v1/organization/settings request your scripts send.
  2. Remove ApertureLog imports from scripts that use the Python SDK.

WATCHER.md files and grading_guidelines are ignored

These steps apply to self-hosted deployments and Watcher Cloud organizations whose developers keep WATCHER.md files, or whose integrations send grading_guidelines.

  1. Collect the guidance those files or fields carried that your organization still wants applied, especially restrictions: without them, calls they escalated may be allowed.
  2. Add it to your organization's custom instructions in the Analyzer or through the monitor customization API, before the update where you can. Custom instructions apply to the whole organization, so name the repository or project a rule is for. Write them as Custom instructions describes. Only organization admins can change these instructions.
  3. On self-hosted deployments, follow Update Watcher. Watcher Cloud administrators do not update the hosted server.