Required updates for Watcher
Direct file edits and recognized shell writes by a coding agent to Watcher's own settings and to the hook configurations Watcher installs now need a person's approval. Scripts and build steps the agent runs can still change these files; use MDM protection where that must be prevented.
Agent inventory is a new Alpha feature. It is off by default, and nothing is collected until an organization admin turns it on. It is a best-effort list meant to shape your agent adoption strategy, and it does not replace a full MDM.
Gateway hooks can review pending tool calls through Tailscale Aperture before the agent executes them.
The Watcher client now starts browser sign-in only
from Sign in to Watcher in the macOS menu bar, or from watcher when you
run it from a desktop terminal while signed out. Each opens a one-time page
that hands off to your identity provider.
When Codex resumes a session, it can restore the sandbox that session last ran with, even over the settings Watcher writes for enforce mode. The Watcher client now reports such a session as not enforcing when its sandbox lets commands run without asking for approval. It already did this for a session that runs with approvals turned off. This needs the Watcher client from this release.
Watcher records GitHub Copilot CLI subagents as separate sessions linked to their parents. Children can upload before the parent's turn finishes.
The Analyzer dashboard shows its green all-clear only when Watcher evaluated tool calls or reviewed sessions in the selected period. A period with no activity, or one in which grading did not run, now shows a neutral state. Read a neutral state as "Watcher checked nothing", not as a result.
Watcher can now record a call that a gateway withheld after a denial or an escalation in enforce mode as blocked. Before, the Analyzer showed a withheld escalation as one nobody answered. Every change below except the last affects teams that enforce Watcher through a gateway that calls Watcher's gateway hooks. The last one applies to every session. All of them need the server from this release.
Watcher now refuses any command-rule pattern that
contains the text (?(, which starts a regular-expression conditional group.
The regular-expression engine has a memory-safety defect in conditional groups,
so Watcher rejects them before compiling the pattern.
Watcher now caps a tool output longer than 100,000 characters in a Claude Code, Codex or GitHub Copilot CLI transcript. Any image embedded in its text is replaced by a short marker first; if the text is still too long, it keeps its first 75,000 and last 25,000 characters, around a marker that names how many characters were removed and the SHA-256 of the text they were removed from. An output packed with more than one image per 1,000 characters keeps its images, and only its middle is removed. One such output could be larger than a single bounded upload request, which stopped the Watcher client from uploading the rest of that session.
What's new?
- Edits, writes and recognized shell writes to files under
~/.apollo_monitor/,.watcher-ignore, or the agent hook configs Watcher installs (Claude Code.claude/settings.jsonand.claude/settings.local.json, Codex.codex/hooks.jsonand.codex/config.toml, and Copilot hooks) need a person's approval, in user and project locations, including in the Auto profile. A profile that turns review off for a tool skips this check for that tool. - The Watcher client judges a file by where its path
leads, so symlinks, hard links and a
cdbefore the write reach the same check. - Skills and unattended runs that edit those files, for example a skill that
updates
.claude/settings.json, now wait for approval or are refused. - Two built-in allow rules approve fewer commands.
sedis approved only for scripts that print, andyq --split-expno longer counts as a read-only data tool. Those commands go to grading instead. - Administrators who want to relax one of the new rules should set its
decisionto"off"or copy the whole rule, rather than adding a partial entry, until every machine runs a client with this release: older clients treat a partial entry as an incomplete rule and turn off rule approvals. An allow rule for these files must name the home path, such as~/.apollo_monitor/settings.local.yaml, to take effect. - A new admin-only managed client setting,
agent_inventory.enabled, turns agent inventory on or off. The switch on the Analyzer's agent inventory page edits it, and needsorg:settings:write. If you distribute settings by MDM, set the key in the Analyzer settings editor and in the settings file your MDM ships. - Only admins can see inventory data. Its Analyzer page and read endpoints need
org:settings:read, which only theadminrole has by default. - While it is on, each Watcher client reports the coding agents installed on its machine and their versions every hour. For agents whose session files it can count, it also reports when each was last used and how many sessions changed in the last 7 days. Session files are counted by name and date and never opened. Every report is stored.
- Coverage shows, per person and agent, whether Watcher received sessions from recent use: monitored, gap or not supported. It is worked out each time the inventory is read. Sessions sent through Watcher's SDK examples, for agents such as Cursor and Cline, count toward coverage.
- Gateway hooks record which clients send traffic, including tools Watcher does not otherwise record, without storing any request content. A person the gateway names becomes a Watcher user.
- Nothing is deleted yet. Turning inventory off stops new reports and sightings and keeps the stored data. Machines that have not reported for 90 days are hidden.
watcher inventory showlists the agents the client finds.--jsonprints the current local scan.
See Agent inventory.
- The pre-response endpoint supports Aperture's
tool_call_pre_responsehook. Allowed calls pass through. Supported refused shell calls become notice commands; unsupported refused calls block the pending batch. - The pre-request endpoint adds instructions explaining denial notices and escalation questions to the model request.
- Keep the
entire_requestobservation hook alongside enforcement to record full transcripts and tool results without grading judged calls again. /api/v1/hooks/aperture/entire-requestis the canonical observation URL. The deprecated/api/v1/hooks/aperturealias continues to work.- Opening
http://localhost:8228(or/login) in a browser no longer starts sign-in. The page says to use the menu bar orwatcher logininstead. - The Start sign-in button after Sign out is gone for the same reason.
- In a dev container, sign in with
watcher logininside the container, or through the machine's own client, rather than by opening the container's forwarded port. watcher login, the terminal sign-in that you approve from a browser on any device, is unchanged.- This covers the
danger-full-accessandexternal-sandboxsandboxes, and any sandbox with network access. In these sandboxes, many commands run without a permission request, so Watcher can record them but cannot stop them. - On macOS, such a session shows the "Not enforcing" warning in the menu bar
and a notification. On every platform,
watcher doctornames the sandbox. - Watcher detects the restored sandbox. It does not prevent it.
- The warning stays up when Codex asks for permission in such a session. It clears once the session's approval policy and sandbox are both back to settings that ask for approval.
- To restore enforcement, start a new session instead of resuming, without approval or sandbox command-line options. See Common failures.
- Each child links to its immediate parent and the call that started it, including nested children and children that make no tool calls.
- Resuming a session preserves child identities and parent links.
- The tool-call outcomes card shows "No activity in this period" when there were no sessions. It shows "No tool calls were checked in this period" when there were sessions but Watcher evaluated no tool call. It adds the reason when one is known: grading is paused because the organization reached its monthly usage limit, or Watcher is paused in the organization's settings.
- The Sessions to Review card shows "No activity in this period" when there were no sessions, and "No sessions were reviewed in this period" when there were sessions but none was reviewed.
- The all-clear line counts the tool calls Watcher did not need to ask anyone about. That count includes calls your settings allow without grading, so the line no longer says Watcher judged them safe.
- When a session has no Deep Review report because none of its tool calls were graded, the session page says why: it made no tool calls, your organization's policy decided its calls without grading, or its calls were not checked.
- A gateway that uses the
raw format can
declare, with
withholds_refused_calls, that it withholds every call Watcher denies or escalates in enforce mode. Watcher then records those calls as blocked when it decides them. Refusals from a gateway that does not set the flag stay pending, as before. See withheld calls. - When that gateway records the reply the agent received, it can name the calls it withheld. Transcripts show each named call just before that reply. A call Watcher refused is marked as blocked by the gateway. A call Watcher allowed, but that the gateway withheld because another call in the same response was refused, is marked as cancelled by the gateway.
- The LiteLLM example in this release sets the flag and names the calls it withheld. An older copy of the example does neither, so redeploy it to get this behavior. Against a server older than this release, the new example sends each request again without the new fields and logs a warning. Replies and decisions are still recorded, but refusals stay pending and transcripts do not show the withheld calls until the server is updated.
- A refused call that a gateway withheld is a flagged tool call, like any other refusal, so readers who can open only flagged tool calls can open it. A call Watcher allowed is not flagged, even when the gateway cancelled it. Tool-call search within a trajectory includes the withheld calls its transcript shows.
- For a tool set to always ask, an escalation that ended blocked with nobody answering now counts as denied by Watcher. Before, it counted as a routine always-ask prompt. Other blocked escalations nobody answered already counted as denied. This applies to every session, whichever way it was recorded. The session list, dashboard counts and transcripts classify sessions when they are read, so sessions recorded before the update are counted the same way and these counts can change after it. New Slack alerts use the same classification.
- A pattern containing
(?(is treated like a pattern that does not compile, wherever the rule comes from: managed settings, a profile, or a local settings file. The check is a plain text match, so an escaped bracket followed by an optional group, such as\(?(\d+), is rejected too. - An active rule with such a pattern never matches, even when it is a deny or human-review rule, and it turns off automatic rule approvals for its tool until it is fixed. Other valid deny and human-review rules still apply.
- Saving managed settings with an active rule that uses such a pattern fails with a validation error naming the rule.
- A self-hosted server whose deployment managed-settings file has an active
rule with such a pattern stops at startup with
managed_settings_file_invalid_at_startupin its log. - A client whose local settings have an active rule with such a pattern cannot
get its calls graded by an updated server, so they follow the client's
grading-failure behaviour. Updating the client does not fix this: rewrite the
rule or set its decision to
"off". - The Analyzer shows these outputs with the markers in place of what was removed; the removed part is not stored. Graders, Deep Review included, already dropped embedded images and saw a text output this long only as a short excerpt of its start and end, and still do. A tool search result whose definitions were removed shows graders only what was kept and the marker.
- A Codex tool search's result, the tool definitions it found, is cut by whole definitions instead: those that fit in the first 75,000 and last 25,000 characters of its stored text are kept, around a marker naming how many were removed. A single definition too large to fit is removed whole.
- The deployment applies the cap to whatever any client version sends, so a conversation is stored the same way whichever client uploaded it.
- The cap does not apply to a conversation sent to the Watcher API as structured messages, or as a raw provider request and response.
- A session stored before this release with an output over the cap starts a second branch at that output if it is ever uploaded in full again.
Required upgrade steps
Command-rule patterns reject conditional groups
These steps apply to self-hosted deployments and Watcher Cloud organizations
whose rules use (?(. Developers should also check their local settings files
and profiles.
- Search every custom rule pattern for
(?(: the deployment managed-settings file on self-hosted servers, the managed settings saved in the Analyzer, and local settings files. - Rewrite each match without a conditional group, for example as two rules or
with alternation (
a|b). Where(?(comes from an escaped bracket before an optional group, as in\(?(\d+), write the bracket as a character class:[(]?(\d+). - Save the managed settings and confirm they save without a validation error.
- Follow Update Watcher for self-hosted servers and clients. Watcher Cloud administrators do not update the hosted server.