[DOCS] Setup and agent view docs omit endpoint-security scan delays for new binaries after v2.1.162

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

Automatic updates / claude update verification, plus the related background-service startup troubleshooting after a new binary is installed

Current Documentation

The setup page currently says:

Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code. Run claude doctor to see the result of the most recent update attempt.

Later on the same page it says:

To apply an update immediately without waiting for the next background check, run: ``bash claude update ``

The agent view troubleshooting page currently says:

If attaching, peeking, or claude logs reports that the background service did not respond, the supervisor process has likely stalled. Stop it and let the next claude agents start a fresh one. To keep your background sessions running through the restart, pass --keep-workers:

What's Wrong or Missing?

The current docs cover updates and background-service recovery separately, but they do not document the scan-delay behavior added in v2.1.162.

The v2.1.162 changelog says Claude Code now waits out endpoint-security scanning of newly installed binaries during background-service startup and claude update verification instead of failing after 5 seconds.

That leaves two missing pieces in the live docs:

A. claude update does not document security-scan verification delays

The setup page tells readers to run claude update and check claude doctor, but it does not explain that on machines with endpoint security or antivirus tooling, verification of a newly installed binary may pause while the scanner finishes.

B. Background-service troubleshooting does not distinguish a temporary scan delay from a stalled supervisor

The agent-view page currently frames "background service did not respond" as a stalled supervisor that should be restarted. It does not mention that immediately after installing a new binary, startup may be delayed by endpoint-security scanning rather than an actual supervisor failure.

Without that note, users on managed or security-hardened machines can misread a temporary post-update delay as a broken update or a stuck background service.

Suggested Improvement

Add a short note in setup near the auto-update/manual-update sections, and cross-reference it from the agent-view troubleshooting section.

For example:

On machines with endpoint security or antivirus scanning, a newly installed Claude Code binary may take longer to verify the first time it starts or immediately after claude update. Wait for the scan to finish before retrying or treating the update as failed. Use claude doctor to inspect the last update attempt.

And in the agent-view troubleshooting section, clarify that a post-update startup delay can be caused by security scanning of the new binary, whereas claude daemon stop --any --keep-workers is the recovery path for a genuinely stalled supervisor.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/setup | 185-189, 253-259 | Documents background/manual updates and claude doctor, but not endpoint-security scan delays while verifying a newly installed binary |
| https://code.claude.com/docs/en/agent-view | 521-529 | Documents recovery for an unresponsive background service, but not the temporary startup delay case after a new binary is installed |

Total scope: 2 pages affected

Version context: v2.1.162 changelog: background-service startup and claude update verification now wait out endpoint-security scanning of new binaries instead of failing after 5 seconds.