From de583d4b1cc27d251e1098cab9c5de41443e5344 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Sun, 25 Oct 2026 14:39:33 +0000 Subject: [PATCH] docs: Claude Code v2.1.310 - mods can intercept settings reads, 3 new Agent SDK query methods, Desktop SSH via OpenSSH on Windows Co-Authored-By: claude-yolo[bot] --- content/.metadata.json | 280 +++++++++--------- .../en/docs/claude-code/agent-sdk/hooks.md | 4 +- .../docs/claude-code/agent-sdk/typescript.md | 60 +++- .../en/docs/claude-code/claude-projects.md | 13 +- .../en/docs/claude-code/desktop-changelog.md | 63 +++- content/en/docs/claude-code/desktop.md | 63 +++- content/en/docs/claude-code/errors.md | 2 + .../en/docs/claude-code/features-overview.md | 2 +- content/en/docs/claude-code/glossary.md | 4 +- content/en/docs/claude-code/hooks.md | 2 +- .../docs/claude-code/how-claude-code-works.md | 2 +- .../en/docs/claude-code/monitoring-usage.md | 2 +- .../en/docs/claude-code/plugins-reference.md | 2 +- .../en/docs/claude-code/plugins/components.md | 2 +- .../en/docs/claude-code/plugins/loading.md | 2 +- .../claude-code/plugins/manifest-reference.md | 2 +- .../en/docs/claude-code/plugins/mods/api.md | 54 +++- .../docs/claude-code/plugins/mods/create.md | 2 + .../docs/claude-code/plugins/mods/events.md | 76 ++++- .../claude-code/plugins/mods/interface.md | 11 +- .../claude-code/plugins/mods/reference.md | 12 +- .../claude-code/plugins/mods/troubleshoot.md | 60 ++++ .../claude-code/plugins/troubleshooting.md | 8 +- content/en/docs/claude-code/sandboxing.md | 28 +- .../self-hosted-environments-reference.md | 17 +- .../en/docs/claude-code/settings-reference.md | 4 +- ...k-settings-on-team-and-enterprise-plans.md | 2 +- .../10593882-share-and-unshare-chats.md | 6 +- ...the-claude-lti-in-canvas-by-instructure.md | 2 +- ...being-asked-to-verify-my-payment-method.md | 2 +- .../11869629-use-claude-with-android-apps.md | 2 +- ...or-team-and-seat-based-enterprise-plans.md | 10 +- ...12173-get-started-with-claude-in-chrome.md | 2 +- ...eam-plan-from-monthly-to-annual-billing.md | 4 +- ...11783-create-and-edit-files-with-claude.md | 6 +- .../12157520-claude-code-usage-analytics.md | 2 +- .../support/12260368-use-incognito-chats.md | 2 +- .../support/12293051-use-claude-in-xcode.md | 2 +- ...age-usage-credits-for-paid-claude-plans.md | 2 +- ...6728-troubleshoot-claude-error-messages.md | 2 +- ...d-using-the-desktop-extension-allowlist.md | 8 +- .../12618689-use-claude-code-in-the-cloud.md | 6 +- ...analytics-for-team-and-enterprise-plans.md | 24 +- ...2446-claude-in-chrome-permissions-guide.md | 4 +- .../12997503-team-plan-billing-faqs.md | 2 +- .../13132885-set-up-single-sign-on-sso.md | 8 +- ...3133195-set-up-jit-or-scim-provisioning.md | 6 +- ...1-configuring-session-security-settings.md | 6 +- .../13189465-log-in-to-your-claude-account.md | 2 +- ...13345190-get-started-with-claude-cowork.md | 2 +- ...13371040-log-in-to-your-console-account.md | 2 +- ...13641943-visual-and-interactive-content.md | 6 +- .../support/13837440-use-plugins-in-claude.md | 4 +- ...gn-tasks-from-anywhere-in-claude-cowork.md | 4 +- ...ur-tasks-with-projects-in-claude-cowork.md | 12 +- ...sync-works-for-enterprise-organizations.md | 4 +- .../14604842-cyber-verification-program.md | 2 +- ...t-a-default-model-for-your-organization.md | 2 +- ...nage-model-access-for-your-organization.md | 8 +- ...1-get-started-with-1password-for-claude.md | 2 +- ...rstanding-your-pro-or-max-plan-invoices.md | 2 +- ...16893491-get-started-with-smart-reports.md | 14 +- ...claude-in-google-docs-sheets-and-slides.md | 4 +- ...ooled-group-budgets-on-enterprise-plans.md | 2 +- .../17203415-set-up-claude-for-intune.md | 22 +- ...rience-for-your-enterprise-organization.md | 4 +- .../8114491-get-started-with-claude.md | 2 +- ...8230524-delete-or-rename-a-conversation.md | 16 +- .../support/8325618-paid-plan-billing-faqs.md | 2 +- ...nt-to-a-team-or-enterprise-organization.md | 2 +- ...77-how-can-i-create-and-manage-projects.md | 6 +- 71 files changed, 685 insertions(+), 328 deletions(-) diff --git a/content/.metadata.json b/content/.metadata.json index ba33ec1773..558f2bc4f2 100644 --- a/content/.metadata.json +++ b/content/.metadata.json @@ -1,7 +1,7 @@ { "metadata": { "version": "2.0", - "fetch_date": "2026-10-25T10:17:54.014400Z", + "fetch_date": "2026-10-25T14:38:28.344183Z", "section": "all" }, "items": [ @@ -5777,15 +5777,15 @@ "url": "https://code.claude.com/docs/en/how-claude-code-works", "status": "success", "path": "en/docs/claude-code/how-claude-code-works.md", - "sha256": "0e27ec5df14be0571ab8a247a45ddecf28b67792706cde8fa5ab02fcbf2befa0", - "size": 19873 + "sha256": "148f87b89f7341cffa6d81fc33a3cacf10033d31addc79685b4878bcb4b7d112", + "size": 19846 }, { "url": "https://code.claude.com/docs/en/features-overview", "status": "success", "path": "en/docs/claude-code/features-overview.md", - "sha256": "753436faa0a5105d8a89fd8b0ba37cbd160f665849f2a87d170f102719ddbc0b", - "size": 29096 + "sha256": "8dfe7fd9840225b38d7d2c98e1b0feec93120411432cbceba608b7a6cfe253dc", + "size": 29134 }, { "url": "https://code.claude.com/docs/en/claude-directory", @@ -5861,8 +5861,8 @@ "url": "https://code.claude.com/docs/en/claude-projects", "status": "success", "path": "en/docs/claude-code/claude-projects.md", - "sha256": "8bb9be97e92f52715db825954a136c2ef25ec4d642a79bb2050c54a2161ac53b", - "size": 61815 + "sha256": "68f1d3a01452674c1827ff12ff9c28d958e6fb7b308dbba95f27ef416b9c4af5", + "size": 62710 }, { "url": "https://code.claude.com/docs/en/mobile", @@ -5938,8 +5938,8 @@ "url": "https://code.claude.com/docs/en/desktop", "status": "success", "path": "en/docs/claude-code/desktop.md", - "sha256": "03298b688d61d56339526e6bd9fde6ce5bb75cfce6a0881a8cb673f29ab5e056", - "size": 190920 + "sha256": "352d0d4a6be0ce61fdc594e5aa612a1120734362bd8551ba454e06b70a064a20", + "size": 195845 }, { "url": "https://code.claude.com/docs/en/desktop-linux", @@ -6218,8 +6218,8 @@ "url": "https://code.claude.com/docs/en/errors", "status": "success", "path": "en/docs/claude-code/errors.md", - "sha256": "e7e040fc79e9742fdcb1c7e8b51a5c7c4fec41bd80919943cbb8357d789b40a1", - "size": 583873 + "sha256": "e3168e263fe716157db08eb4ff05cf2c3f2b0ca37b5387321d245b75caf5b089", + "size": 584282 }, { "url": "https://code.claude.com/docs/en/plugins/overview", @@ -6267,8 +6267,8 @@ "url": "https://code.claude.com/docs/en/plugins/components", "status": "success", "path": "en/docs/claude-code/plugins/components.md", - "sha256": "9da4bed2412f440540da2d3830d65972c83fe838c3e17230c0feed3e5e3281c0", - "size": 40199 + "sha256": "4e824b70bbe00db2d487ab5aeac1c63575fdc151b0d0a3eff573f461ce6f6d4b", + "size": 40417 }, { "url": "https://code.claude.com/docs/en/plugins/dependencies", @@ -6316,22 +6316,22 @@ "url": "https://code.claude.com/docs/en/plugins/mods/create", "status": "success", "path": "en/docs/claude-code/plugins/mods/create.md", - "sha256": "c50f7af09c92d5d90cef1018af11c38cc44de7ea6ffab0d83c9348ff7a3dbd7c", - "size": 24648 + "sha256": "c03a4d3223146fbccdb3b66dae188f9710bd22ceefca089996d3f78e897cccd5", + "size": 24942 }, { "url": "https://code.claude.com/docs/en/plugins/mods/reference", "status": "success", "path": "en/docs/claude-code/plugins/mods/reference.md", - "sha256": "67d7904c54ee156a598757f1d22e6362ae69a94f96ee13d67728b150c01fe73c", - "size": 43737 + "sha256": "3976adf126b966edb572e64b5f73b53f00c5f25305fae255e5fe8acbca7d07c9", + "size": 45006 }, { "url": "https://code.claude.com/docs/en/plugins/mods/interface", "status": "success", "path": "en/docs/claude-code/plugins/mods/interface.md", - "sha256": "715e5e3f65cf1f5ce7a49aaa0a3f7e6784a71564fe1dacd70c09bb8ee5c14aee", - "size": 51724 + "sha256": "1ae63daab4ad8bef231752b67d9f3842f1750850b304ce145cf999011f2c4d97", + "size": 52240 }, { "url": "https://code.claude.com/docs/en/plugins/mods/gallery", @@ -6344,15 +6344,15 @@ "url": "https://code.claude.com/docs/en/plugins/mods/events", "status": "success", "path": "en/docs/claude-code/plugins/mods/events.md", - "sha256": "17fb213580517a4a28e39f31d3327a2ff9f0727aeef5d5938ebe1940d23a7124", - "size": 30001 + "sha256": "b9796410d8829a2f1f3f87dd37dc2978d522fe263637ee84ec7599125b4db629", + "size": 36807 }, { "url": "https://code.claude.com/docs/en/plugins/mods/api", "status": "success", "path": "en/docs/claude-code/plugins/mods/api.md", - "sha256": "3aeb3747155313b4644206c33076ca4d8fc75781a24cf86729adf73ab4e39743", - "size": 34666 + "sha256": "22f65826477f6148930d6bac59c9f2e5ff2effadf7e4f53b9326309ecaeb252b", + "size": 40070 }, { "url": "https://code.claude.com/docs/en/plugins/mods/test", @@ -6365,8 +6365,8 @@ "url": "https://code.claude.com/docs/en/plugins/mods/troubleshoot", "status": "success", "path": "en/docs/claude-code/plugins/mods/troubleshoot.md", - "sha256": "3381d30c9ec852d78d38bc442fb1fe117defd3279e75ca06f049518dc4928069", - "size": 29821 + "sha256": "66e85b07f0b4295007a36fcbd47865d43b6b5badb16d6906f497d384e6026394", + "size": 36022 }, { "url": "https://code.claude.com/docs/en/plugins/create-marketplace", @@ -6407,22 +6407,22 @@ "url": "https://code.claude.com/docs/en/plugins/troubleshooting", "status": "success", "path": "en/docs/claude-code/plugins/troubleshooting.md", - "sha256": "74c7512a773a9dc3ef034a55fbaf60062359ffa5296c92077ce442f92ca6da83", - "size": 97192 + "sha256": "5a4c0fec04ed0fa6d49baefe214e9bbd1053daa758421a879e76e3f664e6113e", + "size": 97265 }, { "url": "https://code.claude.com/docs/en/plugins/loading", "status": "success", "path": "en/docs/claude-code/plugins/loading.md", - "sha256": "b254d1372a3cd61f36e884d31002f09071425dc57d0a79aa1f250790e4c7881f", - "size": 43876 + "sha256": "4384e0e85677682e34e68362a70b06e4a6ef74a7f03e3ad044c0e817b1c35c0e", + "size": 43799 }, { "url": "https://code.claude.com/docs/en/plugins/manifest-reference", "status": "success", "path": "en/docs/claude-code/plugins/manifest-reference.md", - "sha256": "2e9a4d61356e87ee92b7292586e81388cb98e2ac029a42952ed756dad85a00a0", - "size": 43117 + "sha256": "a10a371d18d571e769f99720d4402f3ec13ceb668561266f57145cfa940fa4ed", + "size": 43335 }, { "url": "https://code.claude.com/docs/en/plugins/marketplace-reference", @@ -6631,8 +6631,8 @@ "url": "https://code.claude.com/docs/en/monitoring-usage", "status": "success", "path": "en/docs/claude-code/monitoring-usage.md", - "sha256": "724557e4ac516929ff398c4daa36420c59bbf170695681b999ba35321bc1905d", - "size": 172308 + "sha256": "a2762ce43f1bbb8b58f19a445c82428ef32020c0aa100c487def756dc9a47dbd", + "size": 172415 }, { "url": "https://code.claude.com/docs/en/costs", @@ -6701,8 +6701,8 @@ "url": "https://code.claude.com/docs/en/settings-reference", "status": "success", "path": "en/docs/claude-code/settings-reference.md", - "sha256": "2d71c202b432896cfa95eaec34dcf4522d1712c093296bad2bdaaeb1bf3cf7d1", - "size": 441685 + "sha256": "312fa9bab67ab75cf80d75b30e20bda143632b3acd52b08f40fd37da10635954", + "size": 441930 }, { "url": "https://code.claude.com/docs/en/settings-example", @@ -6736,8 +6736,8 @@ "url": "https://code.claude.com/docs/en/sandboxing", "status": "success", "path": "en/docs/claude-code/sandboxing.md", - "sha256": "589325fa4c7318fcaea12da6f2c4fd0ee26633f2c43898fcebbd248e75f7de11", - "size": 104561 + "sha256": "c81fee95ac9d9eec8571cfeecff26954d06e7c0f1a7de119b8efc5650e2cdf48", + "size": 107062 }, { "url": "https://code.claude.com/docs/en/sandbox-environments", @@ -6792,8 +6792,8 @@ "url": "https://code.claude.com/docs/en/self-hosted-environments-reference", "status": "success", "path": "en/docs/claude-code/self-hosted-environments-reference.md", - "sha256": "e0c9f9d5c6c1e1fc9a0bcd3ff7b028ed04682ed2528b2d6ccccb47dca21ba4e9", - "size": 55676 + "sha256": "52222c28155e306ed0ac4813d39adfe7f5d2cd7c35a9fc21b93e062c4b6c12d1", + "size": 56173 }, { "url": "https://code.claude.com/docs/en/self-hosted-environments-identity", @@ -6918,8 +6918,8 @@ "url": "https://code.claude.com/docs/en/hooks", "status": "success", "path": "en/docs/claude-code/hooks.md", - "sha256": "3ce0f8a007da9192d076b08ca1aa9332b28c12f443189066e3534b1595eaeb47", - "size": 281780 + "sha256": "73138cd79f2cc7bd34f1f990afd86ebded5686cb6d679f629d38134282f2b1c0", + "size": 281737 }, { "url": "https://code.claude.com/docs/en/channels-reference", @@ -6932,8 +6932,8 @@ "url": "https://code.claude.com/docs/en/glossary", "status": "success", "path": "en/docs/claude-code/glossary.md", - "sha256": "109ca94cf31213552a032c5b5e689af5d3e28c55565195249068b7ff2d591021", - "size": 30263 + "sha256": "0c8e34969548bf1d89c1176488df2c5deed04efb4511ddff849734fc2177152c", + "size": 30298 }, { "url": "https://code.claude.com/docs/en/agent-sdk/overview", @@ -7093,8 +7093,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/hooks", "status": "success", "path": "en/docs/claude-code/agent-sdk/hooks.md", - "sha256": "cb989402cb14b1ac8ca85ffdb3edd7093c1a08a9ff0ce3207caa4f0b59f842c8", - "size": 45845 + "sha256": "fd0706dee09c3cdeb76c21a68723e0184e50e2eb4fac48dd3f2ae1a08e4f3b92", + "size": 46054 }, { "url": "https://code.claude.com/docs/en/agent-sdk/file-checkpointing", @@ -7142,8 +7142,8 @@ "url": "https://code.claude.com/docs/en/agent-sdk/typescript", "status": "success", "path": "en/docs/claude-code/agent-sdk/typescript.md", - "sha256": "018d7961aae1aa9cc3f9965f3a1a8442ad4909301d25ab83d0ccdb471c14c3f6", - "size": 302450 + "sha256": "65c93cdd9ca5e10374d7ea7a15c6d1e6534c9f7e86898d488501d6360ca6d211", + "size": 308129 }, { "url": "https://code.claude.com/docs/en/agent-sdk/typescript-v2-preview", @@ -9921,7 +9921,7 @@ "url": "https://support.claude.com/en/articles/8114491-get-started-with-claude", "status": "success", "path": "support/8114491-get-started-with-claude.md", - "sha256": "23649f508ddefbdd6ebf59cf4129b914ff4e06d611563f4947e0aa3cf71b7ecd", + "sha256": "277525f4d104d258eb536c58914897dc7c8da4dac2cb362dd20e7913aba7c063", "size": 5207 }, { @@ -9998,8 +9998,8 @@ "url": "https://support.claude.com/en/articles/8230524-delete-or-rename-a-conversation", "status": "success", "path": "support/8230524-delete-or-rename-a-conversation.md", - "sha256": "c344bb5f493697f1b53cd324708a1c2d9faf7f97dbb258135f7ce439c3c402a6", - "size": 5883 + "sha256": "b0bad140f1f568e4a6ea194d7ce6fd98dd5df8a59598db9502c2da277bf77c00", + "size": 5885 }, { "url": "https://support.claude.com/en/articles/8241126-upload-files-to-claude", @@ -10068,8 +10068,8 @@ "url": "https://support.claude.com/en/articles/8325618-paid-plan-billing-faqs", "status": "success", "path": "support/8325618-paid-plan-billing-faqs.md", - "sha256": "966d6592c4573f2231eef8a4d4cb63900cd1ed187b264f29895ad9f0abc0d7f4", - "size": 4955 + "sha256": "c4a90cfc3965d93fb9fb540fa58212a589380049d992bbf4f2bba9a453c138eb", + "size": 4951 }, { "url": "https://support.claude.com/en/articles/8325621-i-would-like-to-input-sensitive-data-into-my-chats-with-claude-who-can-view-my-conversations", @@ -10306,8 +10306,8 @@ "url": "https://support.claude.com/en/articles/9267400-move-your-personal-claude-account-to-a-team-or-enterprise-organization", "status": "success", "path": "support/9267400-move-your-personal-claude-account-to-a-team-or-enterprise-organization.md", - "sha256": "4910a29757dd49f5adc862ebcb37878442b50ce6952d8b7c021abbfde9aee849", - "size": 10268 + "sha256": "1ff3d6eef0790ded9f87c64aeff79b21480ec30ebeffa18ce90e980c6d94a491", + "size": 10276 }, { "url": "https://support.claude.com/en/articles/9301722-updates-to-our-acceptable-use-policy-now-usage-policy-consumer-terms-of-service-and-privacy-policy", @@ -10348,7 +10348,7 @@ "url": "https://support.claude.com/en/articles/9519177-how-can-i-create-and-manage-projects", "status": "success", "path": "support/9519177-how-can-i-create-and-manage-projects.md", - "sha256": "18b7784b9532654dcb67af38709ea99c03e7ab2650061a76cc5ab57700b36b90", + "sha256": "79eb66a3a586086efa8bb34230e0ebb1704510fb4a047da9f1c70df1b454b06d", "size": 9203 }, { @@ -10649,8 +10649,8 @@ "url": "https://support.claude.com/en/articles/10504844-manage-user-feedback-settings-on-team-and-enterprise-plans", "status": "success", "path": "support/10504844-manage-user-feedback-settings-on-team-and-enterprise-plans.md", - "sha256": "99552e92f83dfe789d41c6984802378ffeee5d83185b74a82d74b0cd9672c52f", - "size": 1036 + "sha256": "23f3888190eea371188d88cdf1ff966464b9a5084e7b96407e1eacc5d1e609f7", + "size": 1038 }, { "url": "https://support.claude.com/en/articles/10504853-manage-user-feedback-settings-on-claude-console", @@ -10670,8 +10670,8 @@ "url": "https://support.claude.com/en/articles/10593882-share-and-unshare-chats", "status": "success", "path": "support/10593882-share-and-unshare-chats.md", - "sha256": "a48484eddcd8b28f05cfc0e72ebd41b51ecf1cc0b3f8280f13f01e978544498f", - "size": 4020 + "sha256": "74f778594fd661431a190d3d9256c937f5fcbc05a725a69aee2c32d465edd7f8", + "size": 4014 }, { "url": "https://support.claude.com/en/articles/10684626-enable-and-use-web-search", @@ -10866,7 +10866,7 @@ "url": "https://support.claude.com/en/articles/11725453-set-up-the-claude-lti-in-canvas-by-instructure", "status": "success", "path": "support/11725453-set-up-the-claude-lti-in-canvas-by-instructure.md", - "sha256": "78926520ca9d050c86cb1c69a1def6b9701967b552e3be66ed81c6e29a606d9d", + "sha256": "8808e9b5f20b0c6545f67074cc6d28c49390d6c100a4893ac3b0c58e98c38624", "size": 2750 }, { @@ -10887,7 +10887,7 @@ "url": "https://support.claude.com/en/articles/11818288-why-am-i-being-asked-to-verify-my-payment-method", "status": "success", "path": "support/11818288-why-am-i-being-asked-to-verify-my-payment-method.md", - "sha256": "bbb83f5e66c801037c8372b190f582cac43489787688910ee3ca274d69b9a1c2", + "sha256": "3fbaa7c04d2a93b4dd51bea86025d26b0ba7a262d3236f5ab3a77ad034da3e4e", "size": 814 }, { @@ -10922,8 +10922,8 @@ "url": "https://support.claude.com/en/articles/11869629-use-claude-with-android-apps", "status": "success", "path": "support/11869629-use-claude-with-android-apps.md", - "sha256": "e0dc7306b81d0a4527ba9a4638099d9416c38e57befa1e29bc10cf8409393d6c", - "size": 13997 + "sha256": "bb5f7431dab5a1c8c989f98543bb10e419187b5115de3d40cdb23134f9a3b1df", + "size": 13993 }, { "url": "https://support.claude.com/en/articles/11932705-automated-security-reviews-in-claude-code", @@ -10957,15 +10957,15 @@ "url": "https://support.claude.com/en/articles/12005970-manage-usage-credits-for-team-and-seat-based-enterprise-plans", "status": "success", "path": "support/12005970-manage-usage-credits-for-team-and-seat-based-enterprise-plans.md", - "sha256": "9f201e51126e266b3b03223b2c66fad9703d6ffbd0933a05e1115087bbf1376f", - "size": 9703 + "sha256": "b3834d54ef6e2dc99a8ee3e2f5e88f5ee4464ba81e998a79084dbaecfda36e7a", + "size": 9719 }, { "url": "https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome", "status": "success", "path": "support/12012173-get-started-with-claude-in-chrome.md", - "sha256": "26677a23489f7cc7a7a01e29173485e49bf4e4d352880dfa0dc9ea0590e9c610", - "size": 14708 + "sha256": "f5e68de5cc17aabd23e67d5834f4ffe6d84a37eca4c58c30a498106fb5b55825", + "size": 14706 }, { "url": "https://support.claude.com/en/articles/12053672-what-happens-to-a-user-s-data-when-they-are-removed-from-a-team-or-enterprise-organization", @@ -10978,8 +10978,8 @@ "url": "https://support.claude.com/en/articles/12083917-change-your-team-plan-from-monthly-to-annual-billing", "status": "success", "path": "support/12083917-change-your-team-plan-from-monthly-to-annual-billing.md", - "sha256": "9c5864588f0ab9acc768114028549ed2bcb21842af2f3bdc863d91b9bff8ed18", - "size": 1394 + "sha256": "fa6350ff0fd5a811838db701608f5fa8b8c02d705b2f267f4531e2127b812297", + "size": 1396 }, { "url": "https://support.claude.com/en/articles/12109679-creating-a-new-account-after-deletion", @@ -10992,8 +10992,8 @@ "url": "https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude", "status": "success", "path": "support/12111783-create-and-edit-files-with-claude.md", - "sha256": "59ba598766922785d227ae9a4193595b3681ac45d2de4941e9a5fd32ac5e52ee", - "size": 17989 + "sha256": "178d5df90199e9e57f5ede1cc3094b852bc505fb9062a6d88f5cbc35b8a987b8", + "size": 17981 }, { "url": "https://support.claude.com/en/articles/12119250-model-safety-bug-bounty-program", @@ -11020,22 +11020,22 @@ "url": "https://support.claude.com/en/articles/12157520-claude-code-usage-analytics", "status": "success", "path": "support/12157520-claude-code-usage-analytics.md", - "sha256": "b4c15de8b2bd01d5fa7205d810ff3db8186badc101c56c9b084211e5513cdd62", + "sha256": "da2da6487fdbe7fcca4b7894d2dc34fa7e420871af1cb7c780625fd5f7629ed1", "size": 6368 }, { "url": "https://support.claude.com/en/articles/12260368-use-incognito-chats", "status": "success", "path": "support/12260368-use-incognito-chats.md", - "sha256": "d12a9fcea0ca916cf74bd781ccf5c88384cd38c8c29ca1e2466a735926269208", - "size": 4374 + "sha256": "285def80b329ad7a2e7724636eea1d554d6b56717dc19bdbdf02579c34622d43", + "size": 4376 }, { "url": "https://support.claude.com/en/articles/12293051-use-claude-in-xcode", "status": "success", "path": "support/12293051-use-claude-in-xcode.md", - "sha256": "2499488a619e83fc0b2a2590edda99cf3fee0292c349ce1745bb19b64a6745a0", - "size": 1907 + "sha256": "e4b960cdb70b66034d0d9042c32b993ee6cf117907887a0d98144fdebfd7ac35", + "size": 1905 }, { "url": "https://support.claude.com/en/articles/12304248-manage-api-key-environment-variables-in-claude-code", @@ -11076,14 +11076,14 @@ "url": "https://support.claude.com/en/articles/12429409-manage-usage-credits-for-paid-claude-plans", "status": "success", "path": "support/12429409-manage-usage-credits-for-paid-claude-plans.md", - "sha256": "31d318cf5bbc215f8440eadccfa7cdc595bb0bc59229553c5bb0406edeff32d1", - "size": 7972 + "sha256": "581fb9b7c445085905908b6d5c76723e41ec92c8b85d1c629ec8f6a7ced4cfb4", + "size": 7968 }, { "url": "https://support.claude.com/en/articles/12466728-troubleshoot-claude-error-messages", "status": "success", "path": "support/12466728-troubleshoot-claude-error-messages.md", - "sha256": "241a8605cb9bdb7190e00e94b84eab55ba3b3dc263127a2ff2b399061051ad35", + "sha256": "46e716c392d5e0018ba6573dccd40236456048ac4973f43d7b0993117127d8af", "size": 5141 }, { @@ -11093,13 +11093,6 @@ "sha256": "d95d3030f1f400fbfa245a9d9a384f1bc31832f720003e1fbc13e0fb5f2c2562", "size": 12504 }, - { - "url": "https://support.claude.com/en/articles/12512176-what-are-skills", - "status": "success", - "path": "support/12512176-what-are-skills.md", - "sha256": "a13a73083525e24968ee3bdde608a371ab3f722fe2ba3ad753aea4b55a1441e2", - "size": 5979 - }, { "url": "https://support.claude.com/en/articles/12512180-use-skills-in-claude", "status": "success", @@ -11125,8 +11118,8 @@ "url": "https://support.claude.com/en/articles/12592343-enabling-and-using-the-desktop-extension-allowlist", "status": "success", "path": "support/12592343-enabling-and-using-the-desktop-extension-allowlist.md", - "sha256": "5cf9757bee9dd83481a933dd92cfe28438482ffad38c98d87124cbd729933435", - "size": 5720 + "sha256": "2e2fd80e6f6eab37927ae1cca2d387f59a35c652f25ec234e8066328dc445c7e", + "size": 5714 }, { "url": "https://support.claude.com/en/articles/12611117-deploy-claude-desktop-for-macos", @@ -11139,8 +11132,8 @@ "url": "https://support.claude.com/en/articles/12618689-use-claude-code-in-the-cloud", "status": "success", "path": "support/12618689-use-claude-code-in-the-cloud.md", - "sha256": "bef3671e71d068da7d00b22ddb440cfdf4e218b7f3c8b39c91d1aa4435c14003", - "size": 11056 + "sha256": "3e9dbd6cc53ae00cca4d0d6238359ab0409e43a54e128960462a13fb938eb3c5", + "size": 11066 }, { "url": "https://support.claude.com/en/articles/12622667-enterprise-configuration-for-claude-desktop", @@ -11195,8 +11188,8 @@ "url": "https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans", "status": "success", "path": "support/12883420-view-usage-analytics-for-team-and-enterprise-plans.md", - "sha256": "727d007ccda196b7ee6e749d65c2f24ecbd503f6ab96b9622b9f77ef34a11df2", - "size": 15103 + "sha256": "a06911736f1af8397100f47f366d4c8cb310878ecd6d466b9cc8038a1d003254", + "size": 15113 }, { "url": "https://support.claude.com/en/articles/12902405-claude-in-chrome-troubleshooting", @@ -11216,8 +11209,8 @@ "url": "https://support.claude.com/en/articles/12902446-claude-in-chrome-permissions-guide", "status": "success", "path": "support/12902446-claude-in-chrome-permissions-guide.md", - "sha256": "2015e27c2a403646de9a4ecae8fb40dcdc72245d0a8ee03021f90d41706c1baa", - "size": 9101 + "sha256": "2256e00bc32d3609fdab2499cf6af5426ae2586838185013606b5ca9d8bc2bad", + "size": 9099 }, { "url": "https://support.claude.com/en/articles/12938627-how-to-gift-a-claude-subscription", @@ -11244,8 +11237,8 @@ "url": "https://support.claude.com/en/articles/12997503-team-plan-billing-faqs", "status": "success", "path": "support/12997503-team-plan-billing-faqs.md", - "sha256": "4a7c680dadf5a436c733d65cc7113ae019f7cb5c317f0ea47323623f59c2505c", - "size": 5411 + "sha256": "00af81c3c1c83ebbea0499b248723c75fe6bc7bf4a8d4ee0dfccbfb057214063", + "size": 5415 }, { "url": "https://support.claude.com/en/articles/13015708-access-the-compliance-api", @@ -11293,15 +11286,15 @@ "url": "https://support.claude.com/en/articles/13132885-set-up-single-sign-on-sso", "status": "success", "path": "support/13132885-set-up-single-sign-on-sso.md", - "sha256": "c1edeaf0c60ad8c694841eb9799cfc3c58c4b1298b087cbc8f68e1a1afc94200", - "size": 13645 + "sha256": "825eb1a6c026c6997334cfca4de5ce2125ec0602029c93f8bb8e077f9047b28d", + "size": 13641 }, { "url": "https://support.claude.com/en/articles/13133195-set-up-jit-or-scim-provisioning", "status": "success", "path": "support/13133195-set-up-jit-or-scim-provisioning.md", - "sha256": "5113ad65680491becb6a85a540654cb5ef117df3e2125f27e4de42dceeec34ef", - "size": 22525 + "sha256": "8df36fbe18ce2ebcf41d1890eec7feebc65d21320b38942c1a493d4d6313ab77", + "size": 22527 }, { "url": "https://support.claude.com/en/articles/13133750-manage-members-on-team-and-enterprise-plans", @@ -11328,8 +11321,8 @@ "url": "https://support.claude.com/en/articles/13163631-configuring-session-security-settings", "status": "success", "path": "support/13163631-configuring-session-security-settings.md", - "sha256": "14faa46486aa1dc032e1dfff73b0ddd8b11cee8480d248e5a8b8ca6c97e61c82", - "size": 3705 + "sha256": "b086b55354f66c59fb1f9d84e5bd75059c85693db80339d2e7b0000d6de8c4b7", + "size": 3701 }, { "url": "https://support.claude.com/en/articles/13171706-crisis-helpline-support-in-claude", @@ -11342,8 +11335,8 @@ "url": "https://support.claude.com/en/articles/13189465-log-in-to-your-claude-account", "status": "success", "path": "support/13189465-log-in-to-your-claude-account.md", - "sha256": "149d93e2935658c5c65a1d0befa2a8e0737407f4b3cfcb15c71329854120e867", - "size": 7039 + "sha256": "33d00d93d5043c3bbc45c99bef799deefffd361ee509a7b5ed679b3a8c8a3e7f", + "size": 7041 }, { "url": "https://support.claude.com/en/articles/13198485-enforce-network-level-access-control-with-tenant-restrictions", @@ -11377,8 +11370,8 @@ "url": "https://support.claude.com/en/articles/13345190-get-started-with-claude-cowork", "status": "success", "path": "support/13345190-get-started-with-claude-cowork.md", - "sha256": "94c9344bf59f7e89f634ec2d9406ca9b9d7ab56e452e15dafcc867207563380b", - "size": 22036 + "sha256": "be9465f152ef1225a7d3093f53a02268d773578616bed34400272e206bc85396", + "size": 22042 }, { "url": "https://support.claude.com/en/articles/13346458-customize-your-console-appearance-settings", @@ -11405,8 +11398,8 @@ "url": "https://support.claude.com/en/articles/13371040-log-in-to-your-console-account", "status": "success", "path": "support/13371040-log-in-to-your-console-account.md", - "sha256": "c1c91b813d8e7cfcd46d150917b87aaedd8f2dbaf423a254adce437898da21d8", - "size": 4613 + "sha256": "e143ae91f3855a5917d13e2c84e18659a88b035b36ea66b65f26e74a62573fd6", + "size": 4609 }, { "url": "https://support.claude.com/en/articles/13393991-purchase-and-manage-seats-on-enterprise-plans", @@ -11461,8 +11454,8 @@ "url": "https://support.claude.com/en/articles/13641943-visual-and-interactive-content", "status": "success", "path": "support/13641943-visual-and-interactive-content.md", - "sha256": "193ddd220cbb32ae0f9958516355f7a888244a3713922b5365a6e6ffe8ef0ee0", - "size": 6505 + "sha256": "d35775e6d4cbf39f1320c6fe2ae627b54cc05eda05ae054a3fb4598ae70facf4", + "size": 6517 }, { "url": "https://support.claude.com/en/articles/13663666-use-visual-and-interactive-content-on-team-and-enterprise-plans", @@ -11517,8 +11510,8 @@ "url": "https://support.claude.com/en/articles/13837440-use-plugins-in-claude", "status": "success", "path": "support/13837440-use-plugins-in-claude.md", - "sha256": "e35fca217e4a3f1de3a04b6a966a1ee8f34ecdefa3876713092579138f396fca", - "size": 15187 + "sha256": "85ae273cc5ffe8ad9108c578055b88a6d48592cd767f3a4933f27139f6e561f7", + "size": 15195 }, { "url": "https://support.claude.com/en/articles/13854387-schedule-recurring-tasks-in-claude-cowork", @@ -11615,7 +11608,7 @@ "url": "https://support.claude.com/en/articles/13947068-assign-tasks-from-anywhere-in-claude-cowork", "status": "success", "path": "support/13947068-assign-tasks-from-anywhere-in-claude-cowork.md", - "sha256": "4703d6923f83610c6f94f37bf263cbf62f1ef581ed29f3af5d92c604937addee", + "sha256": "f6ab68b5140c0f00eed98ac57428fd033eb5fdab1a1f1e9bb72d226e566c38bc", "size": 8969 }, { @@ -11636,8 +11629,8 @@ "url": "https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork", "status": "success", "path": "support/14116274-organize-your-tasks-with-projects-in-claude-cowork.md", - "sha256": "2239ece88f8a7f7eb46f411a9dcec36fc1d1d1e807d2d6f922d7f2d7c7c7d80a", - "size": 7847 + "sha256": "b8400553bdecb17b47d408d5e2d237a0e8c9dbd377830554b124a7950bd85a30", + "size": 7841 }, { "url": "https://support.claude.com/en/articles/14128542-let-claude-use-your-computer-in-cowork", @@ -11706,8 +11699,8 @@ "url": "https://support.claude.com/en/articles/14499648-how-scim-sync-works-for-enterprise-organizations", "status": "success", "path": "support/14499648-how-scim-sync-works-for-enterprise-organizations.md", - "sha256": "3128c623a2fd7bedc17922e9ddf70ecaf49e25166b5224074c665a141f453e49", - "size": 7674 + "sha256": "848e8db3a139e56cf95687d87759fe978f8d39efc298dd6282d4a81fb7be745e", + "size": 7670 }, { "url": "https://support.claude.com/en/articles/14503520-available-beta-and-research-preview-features", @@ -11818,8 +11811,8 @@ "url": "https://support.claude.com/en/articles/14604842-cyber-verification-program", "status": "success", "path": "support/14604842-cyber-verification-program.md", - "sha256": "ade1311fba73e1314b122a91cecd46d0991597ff80faf871ed8f0893971e75ed", - "size": 36004 + "sha256": "4f9bf2a2b1f2d9cd4ec027ba12565cbd5f1448a6d2025d07e192b47d1f6100bf", + "size": 36008 }, { "url": "https://support.claude.com/en/articles/14625619-claim-and-migrate-accounts-on-your-domain", @@ -11930,8 +11923,8 @@ "url": "https://support.claude.com/en/articles/15330088-set-a-default-model-for-your-organization", "status": "success", "path": "support/15330088-set-a-default-model-for-your-organization.md", - "sha256": "eebd37111c1ed44910c78fd4ec56dd4d8acf2e2bdc988519a7893b941e8a7610", - "size": 11309 + "sha256": "57d62c4f9565ad398c306ad3c7f4f6eec8f0d3fb242e73c9cb810363b26680d9", + "size": 11311 }, { "url": "https://support.claude.com/en/articles/15330651-claude-enterprise-admin-api-reference-guide", @@ -12042,8 +12035,8 @@ "url": "https://support.claude.com/en/articles/15694740-manage-model-access-for-your-organization", "status": "success", "path": "support/15694740-manage-model-access-for-your-organization.md", - "sha256": "0b463ed2a76a794f1be0e4c58b19a39bf6514293a9e4db69334c5aee7caa4be8", - "size": 10332 + "sha256": "9f38114be9bb26699d6fe7185b03a4038cf51ea90fde43122fa824a82820a100", + "size": 10338 }, { "url": "https://support.claude.com/en/articles/15707726-using-claude-for-legal-work-privilege-confidentiality-and-how-to-think-about-configuration", @@ -12077,7 +12070,7 @@ "url": "https://support.claude.com/en/articles/15936181-get-started-with-1password-for-claude", "status": "success", "path": "support/15936181-get-started-with-1password-for-claude.md", - "sha256": "ccf21e24c3630bda4b49b0bd41c9c48c64af1c42530b6c9ebddc3cc5663eb26d", + "sha256": "0ce9051c0e1da0ded15062df93bd92baa1721613874a8fe79b6d3535489a7e39", "size": 5058 }, { @@ -12126,7 +12119,7 @@ "url": "https://support.claude.com/en/articles/16607638-understanding-your-pro-or-max-plan-invoices", "status": "success", "path": "support/16607638-understanding-your-pro-or-max-plan-invoices.md", - "sha256": "e155850ff2a2e944f27e98540566e02bc41f80a37af0ac0dbd7bada714b49050", + "sha256": "bf1d240280a1a8a80eb70e2a104eed3170bf3c0b5d7d657a47525eef4cb811b1", "size": 5834 }, { @@ -12210,8 +12203,8 @@ "url": "https://support.claude.com/en/articles/16893491-get-started-with-smart-reports", "status": "success", "path": "support/16893491-get-started-with-smart-reports.md", - "sha256": "c330df52a75a59a17b5759a93c0c864fbdaef5cb69609e73a16f8afe01b465b3", - "size": 15959 + "sha256": "c2af57b7ba6c5a3d4b054cafa8d178129b4f76de8fd81392daaf1e57f4e0b4b2", + "size": 15963 }, { "url": "https://support.claude.com/en/articles/16923645-get-started-with-claude-docs", @@ -12231,8 +12224,8 @@ "url": "https://support.claude.com/en/articles/16951679-use-claude-in-google-docs-sheets-and-slides", "status": "success", "path": "support/16951679-use-claude-in-google-docs-sheets-and-slides.md", - "sha256": "c9da553bcc1e4ac53f08a922edb100bb2d7360fd007054e7f496f432ffd97b92", - "size": 21894 + "sha256": "034df69945eeee7f5b7fade373ba08ff7124e09f43f96a0c1d67e383ab68391c", + "size": 21902 }, { "url": "https://support.claude.com/en/articles/16952184-set-up-salesforce-in-claude-for-your-organization", @@ -12259,8 +12252,8 @@ "url": "https://support.claude.com/en/articles/17005973-manage-pooled-group-budgets-on-enterprise-plans", "status": "success", "path": "support/17005973-manage-pooled-group-budgets-on-enterprise-plans.md", - "sha256": "8a95d0725721d963a652ce72bb0049b23a1c1d4bb69e52b76bf941f44c51b889", - "size": 6982 + "sha256": "2cc9d8b6fc3985439f5e36950b496c6d533164deaaae1cb532edce904b6a7d1c", + "size": 6980 }, { "url": "https://support.claude.com/en/articles/17007452-what-is-a-limit-reset", @@ -12308,8 +12301,8 @@ "url": "https://support.claude.com/en/articles/17203415-set-up-claude-for-intune", "status": "success", "path": "support/17203415-set-up-claude-for-intune.md", - "sha256": "c4f103eb139989ddcbf424c6fc39abba427e2d9a753641064c94bab6368d408c", - "size": 11375 + "sha256": "04b0b5b8b21c3c4ee6d5438b9539d505dabb127b377862092471e79123656c67", + "size": 11369 }, { "url": "https://support.claude.com/en/articles/17318731-use-claude-code-local-mode-and-claude-cowork-local-mode-on-a-hipaa-ready-enterprise-plan", @@ -12336,7 +12329,7 @@ "url": "https://support.claude.com/en/articles/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization", "status": "success", "path": "support/17444462-set-up-and-manage-the-new-unified-claude-experience-for-your-enterprise-organization.md", - "sha256": "0c9db15a79df465a2610924de0c4c51df980215dec35ba0b50bed054cf1b5b27", + "sha256": "d8a13f882c15d9472041aaf671ce24347924885d0d3ad127acd406de54a835cf", "size": 24638 }, { @@ -14380,8 +14373,8 @@ "url": "https://code.claude.com/docs/en/desktop-changelog", "status": "success", "path": "en/docs/claude-code/desktop-changelog.md", - "sha256": "03298b688d61d56339526e6bd9fde6ce5bb75cfce6a0881a8cb673f29ab5e056", - "size": 190920 + "sha256": "352d0d4a6be0ce61fdc594e5aa612a1120734362bd8551ba454e06b70a064a20", + "size": 195845 }, { "url": "https://code.claude.com/docs/en/plugin-relevance", @@ -14408,8 +14401,8 @@ "url": "https://code.claude.com/docs/en/plugins-reference", "status": "success", "path": "en/docs/claude-code/plugins-reference.md", - "sha256": "2e9a4d61356e87ee92b7292586e81388cb98e2ac029a42952ed756dad85a00a0", - "size": 43117 + "sha256": "a10a371d18d571e769f99720d4402f3ec13ceb668561266f57145cfa940fa4ed", + "size": 43335 }, { "url": "https://code.claude.com/docs/en/plugin-hints", @@ -29770,7 +29763,12 @@ "size": 170 } ], - "failures": [], + "failures": [ + { + "url": "https://support.claude.com/en/articles/12512176-what-are-skills", + "error": "HTTP 429" + } + ], "dead": [ { "url": "https://code.claude.com/docs/en/claude-tag", @@ -30975,9 +30973,9 @@ ], "summary": { "total": 4552, - "downloaded": 4252, + "downloaded": 4251, "skipped": 0, - "failed": 0, + "failed": 1, "dead": 300, "success_rate": 100.0 } diff --git a/content/en/docs/claude-code/agent-sdk/hooks.md b/content/en/docs/claude-code/agent-sdk/hooks.md index 6b29057c0c..2753319bb7 100644 --- a/content/en/docs/claude-code/agent-sdk/hooks.md +++ b/content/en/docs/claude-code/agent-sdk/hooks.md @@ -771,7 +771,9 @@ Claude Code runs each callback with a timeout, which you set in seconds with the When a callback exceeds its timeout, Claude Code cancels it and discards its output, and the session continues rather than hanging. What happens next depends on the event: -* `PreToolUse`: Claude Code blocks the tool call. In its place, Claude receives a tool result saying the hook didn't respond before its timeout, and the turn continues. Before v2.1.210, Claude Code reported the timeout to Claude as a user rejection, which made unattended sessions stop and wait for input. +* `PreToolUse`: Claude Code blocks the tool call. If every other hook returned nothing or only an `allow` decision, the tool result tells Claude the hook didn't respond before its timeout, and the turn continues. If another of your hooks already denied the call, its deny still reaches Claude: the tool result includes that hook's reason, and the timeout text can follow it. + + Before v2.1.210, Claude Code reported the timeout to Claude as a user rejection, which made unattended sessions stop and wait for input. * `PostToolUse` and `PostToolUseFailure`: Claude Code keeps the tool result and the turn continues. * `UserPromptSubmit` and [`UserPromptExpansion`](https://code.claude.com/docs/en/hooks#userpromptexpansion): Claude Code blocks the prompt with a message naming the hook and the timeout, and the session continues. Before v2.1.208, Claude Code ended the query with `error_during_execution` when a callback on these events timed out. * `Stop` and `SubagentStop`: the timed-out callback counts as returning no decision. The agent or subagent stops as if that callback had allowed it, and a decision from your other hooks on the event still applies. Before Claude Code v2.1.273, a timed-out `Stop` or `SubagentStop` callback counted as a failed hook run, and Claude Code discarded the decisions of your other hooks on the event. diff --git a/content/en/docs/claude-code/agent-sdk/typescript.md b/content/en/docs/claude-code/agent-sdk/typescript.md index ea538cf742..1d6c266e7a 100644 --- a/content/en/docs/claude-code/agent-sdk/typescript.md +++ b/content/en/docs/claude-code/agent-sdk/typescript.md @@ -309,12 +309,13 @@ function getSessionMessages( | `options.dir` | `string` | `undefined` | Project directory to find the session in. When omitted, searches all projects | | `options.limit` | `number` | `undefined` | Maximum number of messages to return | | `options.offset` | `number` | `undefined` | Number of messages to skip from the start | +| `options.includeSystemMessages` | `boolean` | `false` | When `true`, also return system messages such as compact boundaries alongside user and assistant messages | #### Return type: `SessionMessage` | Property | Type | Description | | :- | :- | :- | -| `type` | `"user" \| "assistant"` | Message role | +| `type` | `"user" \| "assistant" \| "system"` | Message role. `"system"` appears only when `options.includeSystemMessages` is `true` | | `uuid` | `string` | Unique message identifier | | `session_id` | `string` | Session this message belongs to | | `message` | `unknown` | Raw message payload from the transcript | @@ -632,13 +633,19 @@ interface Query extends AsyncGenerator { }): Promise; reloadSkills(): Promise; reloadOutputStyles(): Promise; + seedReadState(path: string, mtime: number): Promise; accountInfo(): Promise; reconnectMcpServer(serverName: string): Promise; toggleMcpServer(serverName: string, enabled: boolean): Promise; setMcpServers(servers: Record): Promise; + setMcpPermissionModeOverride( + serverName: string, + mode: 'default' | 'auto' | null + ): Promise<{ warning?: string }>; readMcpResource(serverName: string, uri: string): Promise; streamInput(stream: AsyncIterable): Promise; stopTask(taskId: string): Promise; + backgroundTasks(toolUseId?: string): Promise; close(): void; } ``` @@ -665,15 +672,55 @@ interface Query extends AsyncGenerator { | `reloadPlugins(options?)` | Reloads plugins from disk, so plugins you install or edit mid-session reach the running session. Resolves with an [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listing the session's commands, subagents, plugins, and MCP server status. Requires Agent SDK v0.2.85 or later. The [`holdOnCacheImpact` option](#sdkcontrolreloadpluginsresponse) requires Agent SDK v0.3.268 or later | | `reloadSkills()` | Reloads skills from disk, so skills you add or edit mid-session become available to the running session. Resolves with an [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listing the skills available after the reload. Requires Agent SDK v0.3.163 or later | | `reloadOutputStyles()` | Re-reads [output styles](https://code.claude.com/docs/en/output-styles.md) from disk, so a style file you add or edit mid-session becomes available to the running session. Resolves with an [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listing the style names available after the reload. Requires Agent SDK v0.3.261 or later | +| `seedReadState(path, mtime)` | Marks a file as already read so a later Edit doesn't fail with `File has not been read yet`. See [`seedReadState()`](#seedreadstate). Requires TypeScript SDK v0.2.83 or later | | `accountInfo()` | Returns account information | | `reconnectMcpServer(serverName)` | Reconnect an MCP server by name. If the name also matches an entry in a settings file such as `.mcp.json` or `~/.claude.json`, Claude Code reconnects the server you configured through [`mcpServers`](#options) or `setMcpServers()`, not the settings-file entry. That resolution order requires Claude Code v2.1.257 or later | | `toggleMcpServer(serverName, enabled)` | Enable or disable an MCP server by name, with the same name resolution as `reconnectMcpServer()`. Disabling a server disconnects it and removes its tools. See [`toggleMcpServer()`](#togglemcpserver) for the Claude Code version this needs for each kind of server | | `setMcpServers(servers)` | Replace the MCP servers this method manages: servers added through it and [in-process SDK servers](#createsdkmcpserver). Resolves with an [`McpSetServersResult`](#mcpsetserversresult) naming which servers were added and removed, and any errors; that section says which other servers stay connected | +| `setMcpPermissionModeOverride(serverName, mode)` | Overrides the permission mode for one MCP server's tools with a stricter mode than the session's, or clears the override with `null`. Only available in streaming input mode. See [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Requires TypeScript SDK v0.3.187 or later | | `readMcpResource(serverName, uri)` | *Alpha.* Reads one MCP Apps `ui://` resource from a connected MCP server so your application can render a tool's widget. Resolves with an [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requires TypeScript Agent SDK v0.3.280 or later | | `streamInput(stream)` | Stream input messages to the query for multi-turn conversations | | `stopTask(taskId)` | Stop a running background task by ID | +| `backgroundTasks(toolUseId?)` | Moves the running Bash commands and subagents that the turn is waiting on to the background, the same as pressing Ctrl+B in the interactive terminal. See [`backgroundTasks()`](#backgroundtasks). Requires TypeScript SDK v0.2.139 or later | | `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources | +#### `setMcpPermissionModeOverride()` + +Overrides the permission mode for one MCP server's tools with a stricter mode than the session's, or clears the override with `null`. Use it when a session runs in a mode that skips per-action prompts but one server's tools should still be reviewed. Requires TypeScript SDK v0.3.187 or later. + +Pass one of three values as `mode`: + +* `'default'`: Claude Code evaluates that server's tool calls as [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) does. +* `'auto'`: Claude Code routes that server's tool calls through the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier. Claude Code rejects this value when the classifier isn't available to the session. +* `null`: clears the override. + +The override only takes effect while the session is in a mode that skips per-action prompts: `bypassPermissions` or `auto`. In any other session mode Claude Code ignores the override, so it can never widen what the session allows. + +The promise resolves with `{ warning }` when no server by that name is known yet. Claude Code stores the override anyway and applies it once a server with that exact name connects, so the warning is a typo check, not a failure. + +Only available in streaming input mode, the same constraint as `setModel()` and `setPermissionMode()`. + +#### `seedReadState()` + +Marks a file as already read so a later Edit doesn't fail with `File has not been read yet`. Use it when your application has dropped an earlier `Read` result from the conversation context and Claude will edit that file next. Requires TypeScript SDK v0.2.83 or later. + +Pass `mtime` as the file's modification time at the moment of that earlier read, in whole milliseconds since the epoch, for example `Math.floor(stat.mtimeMs)`. If the file on disk changed after that time, Claude Code skips the mark. + +The promise resolves whether or not the file was marked, so a resolved promise doesn't tell you which happened. + +#### `backgroundTasks()` + +Moves the running Bash commands and subagents that the turn is waiting on to the background, the same as pressing Ctrl+B in the interactive terminal. Pass the `toolUseId` of a tool call to background only the Bash command or subagent that call started, or omit it to background every foreground task. Requires TypeScript SDK v0.2.139 or later. + +Each backgrounded tool call returns to Claude immediately with a running-in-the-background result, the turn continues, and Claude Code emits an [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) when the task finishes. + +In a session where background tasks are enabled, the promise resolves to a boolean: + +* **`true`**: a task was backgrounded, or you omitted `toolUseId`. +* **`false`**: the `toolUseId` you passed matched no foreground task. + +If background tasks are disabled for the session, such as with [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars), the promise rejects instead and nothing is backgrounded. + #### `applyFlagSettings()` Changes [settings](https://code.claude.com/docs/en/settings.md) on a running session without restarting the query. Use it when a setting that has no dedicated setter needs to change mid-session, such as tightening `permissions` after the agent reads untrusted input. `setModel()` and `setPermissionMode()` are dedicated setters for those two keys; `applyFlagSettings()` is the general form that accepts any subset of the settings keys, and passing `model` here behaves the same as `setModel()`. @@ -1472,11 +1519,20 @@ type SDKMessage = | SDKPermissionDeniedMessage | SDKPromptSuggestionMessage | SDKAPIRetryMessage + | SDKControlRequestProgressMessage + | SDKModelRefusalFallbackMessage + | SDKModelRefusalNoFallbackMessage | SDKMirrorErrorMessage | SDKInformationalMessage | SDKConversationResetMessage; ``` +Three messages in this union report control-request progress and model refusals. Each has `type: "system"`, so tell them apart by the `subtype` listed with each one: + +* `SDKControlRequestProgressMessage`, `subtype: "control_request_progress"`: reports progress on a long-running control request that your client sent. `request_id` matches the message to that request, and `status` is `"started"` or `"api_retry"`. Requires Agent SDK v0.3.203 or later. +* `SDKModelRefusalFallbackMessage`, `subtype: "model_refusal_fallback"`: emitted when the model ends the stream with a refusal and the turn is retried on a fallback model. Carries `original_model` and `fallback_model`. Requires Agent SDK v0.3.170 or later. +* `SDKModelRefusalNoFallbackMessage`, `subtype: "model_refusal_no_fallback"`: emitted when the model ends the stream with a refusal and no retry runs, for example because no fallback model is configured. Carries `original_model`. Requires Agent SDK v0.3.193 or later. + ### `SDKAssistantMessage` Assistant response message. @@ -1636,6 +1692,7 @@ type SDKResultMessage = stop_reason: string | null; ttft_ms?: number; ttft_stream_ms?: number; + time_to_request_ms?: number; user_message_uuid?: string; user_message_uuids?: string[]; resume_reason?: string; @@ -1701,6 +1758,7 @@ Several fields on the result carry diagnostic detail beyond `subtype`: * `api_error_status`: the HTTP status code of the API error that terminated the conversation. Absent or `null` when the turn ended without an API error. * `ttft_ms`: time to first token in milliseconds, measured when the first complete assistant message arrives. Present on the success arm only. * `ttft_stream_ms`: time in milliseconds until the first `message_start` stream event, when the response stream opens. Lower than `ttft_ms`; the gap between the two is time spent streaming the first message. Present on the success arm only. +* `time_to_request_ms`: time in milliseconds from the start of the turn until Claude Code sends the API request. Present on the success arm only. Requires Claude Code v2.1.162 or later. * `user_message_uuid`: the `uuid` of the message you sent that this turn answered. See [`user_message_uuid`](#user_message_uuid) for which results carry it. * `user_message_uuids`: the `uuid`s of every message you sent that Claude Code answered in this turn. See [`user_message_uuids`](#user_message_uuids). * `resume_reason`: why this turn continues one that a restart interrupted. Present on both arms. See [`resume_reason`](#resume_reason). diff --git a/content/en/docs/claude-code/claude-projects.md b/content/en/docs/claude-code/claude-projects.md index 900b62a73b..2252050835 100644 --- a/content/en/docs/claude-code/claude-projects.md +++ b/content/en/docs/claude-code/claude-projects.md @@ -111,7 +111,7 @@ On your first project, Claude takes a turn of its own as soon as the project is The project is now listed under **Projects** in the sidebar, and its conversation is open. [Your first batch](#your-first-batch) covers what to set up before you send it work. -### Start from an existing cloud session +### Start from an existing session If a cloud session you started yourself is doing work that belongs in a project, open its sidebar menu and choose **Move to project**, then pick from the submenu: @@ -120,7 +120,12 @@ If a cloud session you started yourself is doing work that belongs in a project, A **Set up project** banner can also appear above a cloud session's message box. If you use it instead of **Continue as new project**, the result is the same, except that the session's running turn stops once the project opens. -A local session doesn't have these options. To continue its work in a project, describe the work in the project conversation, or push its branch, add that repository to the project, and name the branch in the task. +A session on your own machine gets the same sidebar menu at claude.ai/code once you connect it through [Remote Control](https://code.claude.com/docs/en/remote-control.md#start-a-remote-control-session). From a project, Claude can't read the transcript of a session that connected while [**Require trusted devices**](https://code.claude.com/docs/en/remote-control.md#trusted-devices) was on for your account. If that setting is off: + +1. If the session isn't connected yet, run `/remote-control` in it. If it connected while that setting was on, disconnect it and connect it again first. +2. In a browser, find the session's row in the sidebar at [claude.ai/code](https://claude.ai/code), open its menu, and pick from the same submenu. + +If **Require trusted devices** is on, or you don't use Remote Control, describe the work in the project conversation yourself. Or push the session's branch, add its repository to the project, and tell Claude the branch name. ### Set up GitHub access @@ -425,7 +430,7 @@ Several Claude Code features let more than one session work at the same time, so * **Cloud sessions**: every thread is a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) unless you ask Claude to run it on your machine. Either way, Claude starts and tracks it instead of you. You can also bring the work of a cloud session you started yourself into a project: choose [**Move to project**](#start-from-an-existing-cloud-session) in that session's sidebar menu. * **Scheduled tasks**: when you ask for scheduled work in a project, Claude creates a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) that runs as threads in that project and appears on its **Scheduled tasks** tab. Scheduled tasks you create outside a project keep working on their own. * **Remote Control**: [Remote Control](https://code.claude.com/docs/en/remote-control.md) connects claude.ai to a Claude Code session running on your machine. When you ask Claude in a project to run a thread on your computer, the project [uses Remote Control to do it](#run-a-thread-on-your-own-computer). -* **Local sessions and agent view**: a session you start yourself in your terminal, IDE, or the desktop app's local environment can't be added to a project. [Agent view](https://code.claude.com/docs/en/agent-view.md) is a screen for tracking several local sessions side by side, and you still start each one and give it its task yourself. +* **Local sessions and agent view**: a session you start yourself in your terminal, IDE, or the desktop app's local environment stays outside your projects, though you can [bring its work into one](#start-from-an-existing-cloud-session). [Agent view](https://code.claude.com/docs/en/agent-view.md) is a screen for tracking several local sessions side by side, and you still start each one and give it its task yourself. * **Worktrees**: a [worktree](https://code.claude.com/docs/en/worktrees.md) gives each local session its own working copy of a repository. Cloud threads don't need them: each clones its repositories into its own cloud sandbox and works on its own branch. * **Agent teams**: an [agent team](https://code.claude.com/docs/en/agent-teams.md) is one session that starts teammate sessions for a single task, on your machine or inside a cloud session, and ends with that task. * **Subagents**: a [subagent](https://code.claude.com/docs/en/sub-agents.md) runs inside one session, does a side task in its own context window, and returns a summary to that session. A project's threads are whole sessions that Claude starts and that report back to the project conversation, and a thread can still use subagents for its own side tasks. @@ -437,7 +442,7 @@ Several Claude Code features let more than one session work at the same time, so * Projects are available at claude.ai/code, in the desktop app, and in the Claude mobile app, not in the terminal CLI, the VS Code extension, or the JetBrains plugin, and not through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. * Project threads are [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md), or sessions on your own machine through [Remote Control](https://code.claude.com/docs/en/remote-control.md), with Anthropic as the model provider in both cases. [Security](https://code.claude.com/docs/en/security.md) and [Data usage](https://code.claude.com/docs/en/data-usage.md) cover how cloud sessions are isolated and what's retained, and [Connection and security](https://code.claude.com/docs/en/remote-control.md#connection-and-security) covers how a thread on your machine connects and what's stored. -* You can't add a session you started yourself on your machine to a project. A project reaches your machine only by [running a thread there through Remote Control](#run-a-thread-on-your-own-computer), and that section lists what it needs. +* You can't add a session you started yourself on your machine to a project, though you can [bring its work into one](#start-from-an-existing-cloud-session). A project reaches your machine by [running a thread there through Remote Control](#run-a-thread-on-your-own-computer), and that section lists what it needs. * A cloud thread's sandbox pauses between turns and resumes when the thread continues. If the sandbox can't be resumed, the thread continues from a fresh clone, so uncommitted changes can be lost. On long tasks, ask Claude to commit and push work in progress. * A project belongs to one user. You can't share a project or its threads with another user, and thread transcripts don't have the share option other cloud sessions have. There are no organization-level controls for projects during the beta. * A thread belongs to the one project that started it. You can't move or copy a thread to another project, or move it out to stand alone. [**Move to project**](#start-from-an-existing-cloud-session) goes the other way only: it brings a cloud session's work into a project. You can't merge two projects into one. diff --git a/content/en/docs/claude-code/desktop-changelog.md b/content/en/docs/claude-code/desktop-changelog.md index c4b73a477d..07756492bf 100644 --- a/content/en/docs/claude-code/desktop-changelog.md +++ b/content/en/docs/claude-code/desktop-changelog.md @@ -984,7 +984,12 @@ A Linux or macOS remote machine needs a supported processor, an SSH server with * **System**: an x86\_64 or arm64 processor. The machine also has to meet Claude Code's [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements). On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run `ldd --version` there. On a musl-based distribution such as Alpine Linux, also install the [packages that Claude Code needs](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions). * **SFTP**: the SSH server has to offer the SFTP subsystem, which a `Subsystem sftp` line in its `sshd_config` turns on. To check, connect to the same host and port with `sftp` in a terminal on your computer. A working server shows the `sftp>` prompt. -* **Sessions per connection**: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server's `sshd_config` sets `MaxSessions 1`, raise it, for example to OpenSSH's default of 10. +* **`MaxSessions 1` on the server**: to connect to a server whose `sshd_config` sets `MaxSessions 1`, do one of these: + * **Your computer runs macOS or Linux**: update to Claude Desktop v3.1623.0 or later + * **Your computer runs Windows**: make sure that Desktop [connects through the OpenSSH client](#use-your-ssh-configuration), because Desktop's built-in SSH client can't connect to that server + * **You can change the server**: raise `MaxSessions`, for example to OpenSSH's default of 10 +* **Logins with `MaxSessions 1`**: use a login that works without a prompt, such as a key that your SSH agent holds. Desktop logs in at least twice each time it connects or reconnects. Expect at least one more login for each [terminal](#run-commands-in-the-terminal) tab, and for each Desktop session in which you run commands that start with `!`. Expect none for commands that Claude runs. +* **One-time codes with `MaxSessions 1`**: if every login prompts you, as with one-time codes, `!` commands fail. Run those commands in a terminal tab instead, which prompts in its own pane. * **Install folder**: Desktop installs a helper program and Claude Code under `~/.claude/remote/` in your home directory. It runs them from there, so that folder can't be on a file system mounted `noexec`. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine). * **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do * **Network**: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the [network access that Claude Code requires](https://code.claude.com/docs/en/network-config.md#network-access-requirements). If the machine can't download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code's other requests still go out from the remote machine. On a Linux remote machine, if those requests need a proxy, [set it for SSH sessions](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions). @@ -993,7 +998,7 @@ A Linux or macOS remote machine needs a supported processor, an SSH server with If a Linux remote machine reaches the internet through a proxy or needs a CA certificate, add the [proxy and CA variables](https://code.claude.com/docs/en/network-config.md) under `env` in `~/.claude/settings.json` there. Add them even if you already export them in `~/.profile`, `~/.bash_profile`, `~/.zprofile`, or `~/.zshrc` on that machine. -An SSH session doesn't get them from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help. +In an SSH session, Claude Code doesn't get the variables from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help. **1. Add the variables** @@ -1028,19 +1033,42 @@ If the list has the variable, change it in the file that sets it, such as `~/.zs Restart the remote machine, or quit Desktop and end the helper's processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude's work. -#### Use your SSH configuration on macOS and Linux +#### Use your SSH configuration -On macOS and Linux, Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. Enter a `Host` name from that file in the **SSH host** field to use settings from its entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`. +You can use your SSH configuration on macOS, Linux, and Windows when Desktop connects through the OpenSSH client on your computer: + +* **macOS and Linux**: Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. +* **Windows**: when Desktop connects through the OpenSSH client, it uses your `%USERPROFILE%\.ssh\config`. If you use a Claude account rather than a third-party provider, connecting through the OpenSSH client requires all of these: + + * Claude Desktop v2.2553.0 or later. To find your version, see [Check your version](#check-your-version). + * Microsoft's OpenSSH 9.4 or later + * Desktop installed with the download buttons at the top of this page, because Desktop from the Microsoft Store doesn't connect through the OpenSSH client + + If you can't meet these requirements, or you use a third-party provider, see [Connect on Windows without the OpenSSH client](#connect-on-windows-without-the-openssh-client). + +With the OpenSSH client, enter a `Host` name from your configuration file in the **SSH host** field. Desktop then uses settings from that `Host` entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`. Before you add the connection, check the client and the entry in a terminal on your computer: -* **Client version**: run `ssh -V`. The client has to be OpenSSH 7.6 or later. -* **Entry**: run `ssh` with the `Host` name, such as `ssh devbox`. If that fails, fix the entry first. +* **Client version on macOS and Linux**: run `ssh -V`. The client has to be OpenSSH 7.6 or later. +* **Client version on Windows**: Desktop tries the `ssh` on your `PATH` first, so run `ssh -V`. The client passes if the output shows `OpenSSH_for_Windows_` and 9.4 or later. If it doesn't pass, check the two folders that Desktop tries next: run `.\ssh.exe -V` in `C:\Windows\System32\OpenSSH`, then in `C:\Program Files\OpenSSH`. +* **No client passes on Windows**: add the **OpenSSH Client** optional feature in Windows and install pending Windows updates, or install [Microsoft's newer build](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Then quit and reopen Desktop. To see whether Desktop found a usable OpenSSH client, look in [`ssh.log`](#get-desktops-logs-for-an-ssh-problem) for `Windows OpenSSH client:` and a version, or for `no usable Windows OpenSSH client`. +* **Entry**: on Windows, use the client that passed the version check. Run `ssh` with the `Host` name, such as `ssh devbox`. If that fails, fix the entry first. You can leave the **SSH port** and **SSH key (optional)** fields empty. If you fill one in, Desktop uses it with the entry: * **SSH port**: a value here overrides the entry's `Port` -* **SSH key (optional)**: Desktop offers the key file you pick in addition to the entry's `IdentityFile` and the keys in your SSH agent +* **SSH key (optional)**: with the OpenSSH client, Desktop offers the key file you pick in addition to the entry's `IdentityFile` and the keys in your SSH agent. On Windows, pick a key in OpenSSH format, because `ssh` doesn't read a PuTTY `.ppk` file. + +##### Connect on Windows without the OpenSSH client + +On Windows, you connect through Desktop's built-in SSH client if your computer doesn't meet [the requirements for the OpenSSH client](#use-your-ssh-configuration). With a third-party provider, you connect through the built-in client by default, and your administrator can change that. For the setting, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). + +With the built-in client, you can still enter a `Host` name from your SSH configuration in the **SSH host** field if your `PATH` has an `ssh` command, with these limits: + +* **Settings from the entry**: Desktop takes `HostName`, `User`, `Port`, and `IdentityFile`. It also takes `ProxyCommand` if an `sh` shell is on your `PATH`. +* **SSH key (optional)**: leave this field empty to keep the entry's `IdentityFile`, because a key file that you pick here replaces the `IdentityFile` +* **`CertificateFile` and `ProxyJump`**: Desktop ignores `CertificateFile`, and the connection fails if the entry sets `ProxyJump`. To use either setting, [connect through the OpenSSH client](#use-your-ssh-configuration). ##### Reach a machine behind a jump host @@ -1095,7 +1123,7 @@ Then enter `devbox-container` in the **SSH host** field. ##### Use variables from your shell in a `ProxyCommand` -To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit. +On macOS and Linux, to use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`. Then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit. This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer. @@ -1103,7 +1131,7 @@ This requires Claude Desktop v2.37337.0 or later and an `env` command that accep > > If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables. -##### Use AWS credentials in a `ProxyCommand` +##### Use AWS credentials in a `ProxyCommand` on macOS and Linux If you set temporary AWS credentials in a shell startup file, a `ProxyCommand` that runs the AWS CLI can connect in a terminal and fail in Desktop. When your shell exports `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN`, or `AWS_CREDENTIAL_EXPIRATION`, `ssh` and your `ProxyCommand` in Desktop don't get the shell's AWS credentials, `AWS_REGION`, or `AWS_PROFILE`. @@ -1242,8 +1270,9 @@ When you come back and the task isn't done, check for word that Desktop can't re ##### Prepare a long task -* **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. On macOS with a Claude account, by default the restart can go ahead anyway once the update has waited 72 hours. -* **Don't quit on Windows, or before v2.42304.0 with a third-party provider**: after a quit there you lose the running task, so leave Desktop open during the task. In any other case, see [what you get back](#reopen-a-session-after-you-quit-desktop) before you quit. +* **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. By default, once the update has waited 72 hours, the restart can go ahead during the task if Desktop can [rejoin the task afterward](#reopen-a-session-after-you-quit-desktop). +* **Check before you quit**: you don't always get the running task back after a quit or restart, for example after some Desktop updates. For the cases, see [Reopen a session after you quit Desktop](#reopen-a-session-after-you-quit-desktop). +* **On an older version, leave Desktop open**: on Windows with Claude Desktop before v3.1623.0, you don't get the running task back after Desktop quits or restarts. The same is true with a third-party provider on macOS or Linux before v2.42304.0. In both cases, leave Desktop open during the task. To find your version, see [Check your version](#check-your-version). * **Reduce requests**: choose a permission mode, rules, or hooks that [make the task wait for you less often](#handle-requests-that-arrive-while-you-are-away) * **Check the jump host**: if your jump host asks for a sign-in, for example a push to a phone, switch to a login that works without a prompt. Otherwise Desktop can send another push each time it tries to reconnect. * **Test the remote machine**: start a short task, quit Desktop while the task is still running, and open the session again well after the task should be done. If the task isn't finished and the session shows no authentication error, check the remote machine for [what can end a task](#limits-while-desktop-is-disconnected). @@ -1320,11 +1349,11 @@ If Desktop hasn't reconnected when you come back, send a message in the session. After you quit Desktop, the task keeps running on the remote machine, but it stops when the session opens again unless Desktop can rejoin its process. While Desktop is closed, the task runs until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected). -* **Desktop on Windows**: you don't get the running task back, because Desktop never rejoins after a quit. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts. -* **Third-party provider, task from an earlier version**: if you started the task in a Desktop version before v2.42304.0, you don't get it back on macOS or Linux either. Start Desktop again only when you expect the task to be done. -* **Any other task, with Desktop on macOS or Linux**: start Desktop and open the session, and the task goes on if Desktop rejoins. It can't always rejoin, for example after some Desktop updates, so [update before a long task](#prepare-a-long-task). +* **Desktop on Windows, task started in a version before v3.1623.0**: you don't get the task back, even if Desktop has updated since. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts, and the task stops when the session opens. If you don't know which version you started the task in, also wait until you expect it to be done. +* **Third-party provider on macOS or Linux, task started in a version before v2.42304.0**: you don't get the task back. Start Desktop again only when you expect the task to be done. +* **Any other task**: start Desktop and open the session, and the task goes on if Desktop rejoins. It can't always rejoin, for example after some Desktop updates, so [update before a long task](#prepare-a-long-task). -When Desktop can't rejoin, you also lose any approval or question that was waiting for you. If the task doesn't continue on its own, send a message, and Claude continues from the conversation's saved history. +When the task stops, the session can show `Restarting Claude Code on …` while Desktop starts a new process. You also lose any approval or question that was waiting for you. If Claude doesn't continue on its own, send a message, and Claude continues from the conversation's saved history. For third-party deployments, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). @@ -1411,6 +1440,8 @@ Programs that Claude Code starts, such as shell commands and MCP servers, start To find out who connected to a remote machine, read the SSH server's log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session. +If the server sets `MaxSessions 1`, expect at least two entries each time Desktop connects or reconnects. Expect at least one more for each terminal tab, and for each Desktop session in which you run commands that start with `!`. + You won't find Desktop's SSH connections in Claude Code's [metrics and events](https://code.claude.com/docs/en/monitoring-usage.md#available-metrics-and-events). To find out from them which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](https://code.claude.com/docs/en/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). For Desktop's own record of its connections, see [Get Desktop's logs for an SSH problem](#get-desktops-logs-for-an-ssh-problem). #### Connections that close before login @@ -2112,7 +2143,7 @@ Find the card's title, or the code that ends the error message, in this table, t | - | - | - | | `'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | Turn on SFTP in the server's `sshd_config`, as described under [remote machine requirements](#remote-machine-requirements-for-ssh-sessions) | | `SFTP doesn't start on ` | `[SFTP_NOT_STARTED]` | Connect to the same host with `sftp` in a terminal on your computer to see what stops it, then check the settings and files that Desktop's message names | -| ` allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Raise `MaxSessions` in the server's `sshd_config`, for example to OpenSSH's default of 10 | +| ` allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Update to Claude Desktop v3.1623.0 or later, or raise `MaxSessions` in the server's `sshd_config`, for example to OpenSSH's default of 10 | | ` is out of disk space` | `[ENOSPC]` or `[EDQUOT]` | Free space or quota on the remote machine, in your home directory or `/tmp` | | `Free up disk space on this computer` | `[ENOSPC]` or `[EDQUOT]`, in a message that starts with `Couldn't prepare the deploy locally` | Free space on your computer | | `Claude Code won't start on ` | `[CLI_UNRESPONSIVE]` | Wait a minute, then try again. If it keeps failing, run the command that the message names on the remote machine to see whether Claude Code answers there. | diff --git a/content/en/docs/claude-code/desktop.md b/content/en/docs/claude-code/desktop.md index c4b73a477d..07756492bf 100644 --- a/content/en/docs/claude-code/desktop.md +++ b/content/en/docs/claude-code/desktop.md @@ -984,7 +984,12 @@ A Linux or macOS remote machine needs a supported processor, an SSH server with * **System**: an x86\_64 or arm64 processor. The machine also has to meet Claude Code's [system requirements](https://code.claude.com/docs/en/setup.md#system-requirements). On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run `ldd --version` there. On a musl-based distribution such as Alpine Linux, also install the [packages that Claude Code needs](https://code.claude.com/docs/en/setup.md#alpine-linux-and-musl-based-distributions). * **SFTP**: the SSH server has to offer the SFTP subsystem, which a `Subsystem sftp` line in its `sshd_config` turns on. To check, connect to the same host and port with `sftp` in a terminal on your computer. A working server shows the `sftp>` prompt. -* **Sessions per connection**: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server's `sshd_config` sets `MaxSessions 1`, raise it, for example to OpenSSH's default of 10. +* **`MaxSessions 1` on the server**: to connect to a server whose `sshd_config` sets `MaxSessions 1`, do one of these: + * **Your computer runs macOS or Linux**: update to Claude Desktop v3.1623.0 or later + * **Your computer runs Windows**: make sure that Desktop [connects through the OpenSSH client](#use-your-ssh-configuration), because Desktop's built-in SSH client can't connect to that server + * **You can change the server**: raise `MaxSessions`, for example to OpenSSH's default of 10 +* **Logins with `MaxSessions 1`**: use a login that works without a prompt, such as a key that your SSH agent holds. Desktop logs in at least twice each time it connects or reconnects. Expect at least one more login for each [terminal](#run-commands-in-the-terminal) tab, and for each Desktop session in which you run commands that start with `!`. Expect none for commands that Claude runs. +* **One-time codes with `MaxSessions 1`**: if every login prompts you, as with one-time codes, `!` commands fail. Run those commands in a terminal tab instead, which prompts in its own pane. * **Install folder**: Desktop installs a helper program and Claude Code under `~/.claude/remote/` in your home directory. It runs them from there, so that folder can't be on a file system mounted `noexec`. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see [Files and processes on the remote machine](#files-and-processes-on-the-remote-machine). * **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do * **Network**: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the [network access that Claude Code requires](https://code.claude.com/docs/en/network-config.md#network-access-requirements). If the machine can't download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code's other requests still go out from the remote machine. On a Linux remote machine, if those requests need a proxy, [set it for SSH sessions](#set-a-proxy-or-a-ca-certificate-for-ssh-sessions). @@ -993,7 +998,7 @@ A Linux or macOS remote machine needs a supported processor, an SSH server with If a Linux remote machine reaches the internet through a proxy or needs a CA certificate, add the [proxy and CA variables](https://code.claude.com/docs/en/network-config.md) under `env` in `~/.claude/settings.json` there. Add them even if you already export them in `~/.profile`, `~/.bash_profile`, `~/.zprofile`, or `~/.zshrc` on that machine. -An SSH session doesn't get them from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help. +In an SSH session, Claude Code doesn't get the variables from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help. **1. Add the variables** @@ -1028,19 +1033,42 @@ If the list has the variable, change it in the file that sets it, such as `~/.zs Restart the remote machine, or quit Desktop and end the helper's processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude's work. -#### Use your SSH configuration on macOS and Linux +#### Use your SSH configuration -On macOS and Linux, Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. Enter a `Host` name from that file in the **SSH host** field to use settings from its entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`. +You can use your SSH configuration on macOS, Linux, and Windows when Desktop connects through the OpenSSH client on your computer: + +* **macOS and Linux**: Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. +* **Windows**: when Desktop connects through the OpenSSH client, it uses your `%USERPROFILE%\.ssh\config`. If you use a Claude account rather than a third-party provider, connecting through the OpenSSH client requires all of these: + + * Claude Desktop v2.2553.0 or later. To find your version, see [Check your version](#check-your-version). + * Microsoft's OpenSSH 9.4 or later + * Desktop installed with the download buttons at the top of this page, because Desktop from the Microsoft Store doesn't connect through the OpenSSH client + + If you can't meet these requirements, or you use a third-party provider, see [Connect on Windows without the OpenSSH client](#connect-on-windows-without-the-openssh-client). + +With the OpenSSH client, enter a `Host` name from your configuration file in the **SSH host** field. Desktop then uses settings from that `Host` entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`. Before you add the connection, check the client and the entry in a terminal on your computer: -* **Client version**: run `ssh -V`. The client has to be OpenSSH 7.6 or later. -* **Entry**: run `ssh` with the `Host` name, such as `ssh devbox`. If that fails, fix the entry first. +* **Client version on macOS and Linux**: run `ssh -V`. The client has to be OpenSSH 7.6 or later. +* **Client version on Windows**: Desktop tries the `ssh` on your `PATH` first, so run `ssh -V`. The client passes if the output shows `OpenSSH_for_Windows_` and 9.4 or later. If it doesn't pass, check the two folders that Desktop tries next: run `.\ssh.exe -V` in `C:\Windows\System32\OpenSSH`, then in `C:\Program Files\OpenSSH`. +* **No client passes on Windows**: add the **OpenSSH Client** optional feature in Windows and install pending Windows updates, or install [Microsoft's newer build](https://learn.microsoft.com/en-us/troubleshoot/windows-server/system-management-components/upgrade-in-box-openssh-to-latest-openssh-release). Then quit and reopen Desktop. To see whether Desktop found a usable OpenSSH client, look in [`ssh.log`](#get-desktops-logs-for-an-ssh-problem) for `Windows OpenSSH client:` and a version, or for `no usable Windows OpenSSH client`. +* **Entry**: on Windows, use the client that passed the version check. Run `ssh` with the `Host` name, such as `ssh devbox`. If that fails, fix the entry first. You can leave the **SSH port** and **SSH key (optional)** fields empty. If you fill one in, Desktop uses it with the entry: * **SSH port**: a value here overrides the entry's `Port` -* **SSH key (optional)**: Desktop offers the key file you pick in addition to the entry's `IdentityFile` and the keys in your SSH agent +* **SSH key (optional)**: with the OpenSSH client, Desktop offers the key file you pick in addition to the entry's `IdentityFile` and the keys in your SSH agent. On Windows, pick a key in OpenSSH format, because `ssh` doesn't read a PuTTY `.ppk` file. + +##### Connect on Windows without the OpenSSH client + +On Windows, you connect through Desktop's built-in SSH client if your computer doesn't meet [the requirements for the OpenSSH client](#use-your-ssh-configuration). With a third-party provider, you connect through the built-in client by default, and your administrator can change that. For the setting, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). + +With the built-in client, you can still enter a `Host` name from your SSH configuration in the **SSH host** field if your `PATH` has an `ssh` command, with these limits: + +* **Settings from the entry**: Desktop takes `HostName`, `User`, `Port`, and `IdentityFile`. It also takes `ProxyCommand` if an `sh` shell is on your `PATH`. +* **SSH key (optional)**: leave this field empty to keep the entry's `IdentityFile`, because a key file that you pick here replaces the `IdentityFile` +* **`CertificateFile` and `ProxyJump`**: Desktop ignores `CertificateFile`, and the connection fails if the entry sets `ProxyJump`. To use either setting, [connect through the OpenSSH client](#use-your-ssh-configuration). ##### Reach a machine behind a jump host @@ -1095,7 +1123,7 @@ Then enter `devbox-container` in the **SSH host** field. ##### Use variables from your shell in a `ProxyCommand` -To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit. +On macOS and Linux, to use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`. Then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit. This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer. @@ -1103,7 +1131,7 @@ This requires Claude Desktop v2.37337.0 or later and an `env` command that accep > > If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables. -##### Use AWS credentials in a `ProxyCommand` +##### Use AWS credentials in a `ProxyCommand` on macOS and Linux If you set temporary AWS credentials in a shell startup file, a `ProxyCommand` that runs the AWS CLI can connect in a terminal and fail in Desktop. When your shell exports `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN`, or `AWS_CREDENTIAL_EXPIRATION`, `ssh` and your `ProxyCommand` in Desktop don't get the shell's AWS credentials, `AWS_REGION`, or `AWS_PROFILE`. @@ -1242,8 +1270,9 @@ When you come back and the task isn't done, check for word that Desktop can't re ##### Prepare a long task -* **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. On macOS with a Claude account, by default the restart can go ahead anyway once the update has waited 72 hours. -* **Don't quit on Windows, or before v2.42304.0 with a third-party provider**: after a quit there you lose the running task, so leave Desktop open during the task. In any other case, see [what you get back](#reopen-a-session-after-you-quit-desktop) before you quit. +* **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. By default, once the update has waited 72 hours, the restart can go ahead during the task if Desktop can [rejoin the task afterward](#reopen-a-session-after-you-quit-desktop). +* **Check before you quit**: you don't always get the running task back after a quit or restart, for example after some Desktop updates. For the cases, see [Reopen a session after you quit Desktop](#reopen-a-session-after-you-quit-desktop). +* **On an older version, leave Desktop open**: on Windows with Claude Desktop before v3.1623.0, you don't get the running task back after Desktop quits or restarts. The same is true with a third-party provider on macOS or Linux before v2.42304.0. In both cases, leave Desktop open during the task. To find your version, see [Check your version](#check-your-version). * **Reduce requests**: choose a permission mode, rules, or hooks that [make the task wait for you less often](#handle-requests-that-arrive-while-you-are-away) * **Check the jump host**: if your jump host asks for a sign-in, for example a push to a phone, switch to a login that works without a prompt. Otherwise Desktop can send another push each time it tries to reconnect. * **Test the remote machine**: start a short task, quit Desktop while the task is still running, and open the session again well after the task should be done. If the task isn't finished and the session shows no authentication error, check the remote machine for [what can end a task](#limits-while-desktop-is-disconnected). @@ -1320,11 +1349,11 @@ If Desktop hasn't reconnected when you come back, send a message in the session. After you quit Desktop, the task keeps running on the remote machine, but it stops when the session opens again unless Desktop can rejoin its process. While Desktop is closed, the task runs until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected). -* **Desktop on Windows**: you don't get the running task back, because Desktop never rejoins after a quit. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts. -* **Third-party provider, task from an earlier version**: if you started the task in a Desktop version before v2.42304.0, you don't get it back on macOS or Linux either. Start Desktop again only when you expect the task to be done. -* **Any other task, with Desktop on macOS or Linux**: start Desktop and open the session, and the task goes on if Desktop rejoins. It can't always rejoin, for example after some Desktop updates, so [update before a long task](#prepare-a-long-task). +* **Desktop on Windows, task started in a version before v3.1623.0**: you don't get the task back, even if Desktop has updated since. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts, and the task stops when the session opens. If you don't know which version you started the task in, also wait until you expect it to be done. +* **Third-party provider on macOS or Linux, task started in a version before v2.42304.0**: you don't get the task back. Start Desktop again only when you expect the task to be done. +* **Any other task**: start Desktop and open the session, and the task goes on if Desktop rejoins. It can't always rejoin, for example after some Desktop updates, so [update before a long task](#prepare-a-long-task). -When Desktop can't rejoin, you also lose any approval or question that was waiting for you. If the task doesn't continue on its own, send a message, and Claude continues from the conversation's saved history. +When the task stops, the session can show `Restarting Claude Code on …` while Desktop starts a new process. You also lose any approval or question that was waiting for you. If Claude doesn't continue on its own, send a message, and Claude continues from the conversation's saved history. For third-party deployments, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). @@ -1411,6 +1440,8 @@ Programs that Claude Code starts, such as shell commands and MCP servers, start To find out who connected to a remote machine, read the SSH server's log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session. +If the server sets `MaxSessions 1`, expect at least two entries each time Desktop connects or reconnects. Expect at least one more for each terminal tab, and for each Desktop session in which you run commands that start with `!`. + You won't find Desktop's SSH connections in Claude Code's [metrics and events](https://code.claude.com/docs/en/monitoring-usage.md#available-metrics-and-events). To find out from them which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](https://code.claude.com/docs/en/monitoring-usage.md#attribute-telemetry-to-desktop-ssh-sessions). For Desktop's own record of its connections, see [Get Desktop's logs for an SSH problem](#get-desktops-logs-for-an-ssh-problem). #### Connections that close before login @@ -2112,7 +2143,7 @@ Find the card's title, or the code that ends the error message, in this table, t | - | - | - | | `'s SSH server has SFTP turned off` | `[SFTP_UNAVAILABLE]` | Turn on SFTP in the server's `sshd_config`, as described under [remote machine requirements](#remote-machine-requirements-for-ssh-sessions) | | `SFTP doesn't start on ` | `[SFTP_NOT_STARTED]` | Connect to the same host with `sftp` in a terminal on your computer to see what stops it, then check the settings and files that Desktop's message names | -| ` allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Raise `MaxSessions` in the server's `sshd_config`, for example to OpenSSH's default of 10 | +| ` allows too few SSH sessions per connection` | `[SESSION_LIMIT]` | Update to Claude Desktop v3.1623.0 or later, or raise `MaxSessions` in the server's `sshd_config`, for example to OpenSSH's default of 10 | | ` is out of disk space` | `[ENOSPC]` or `[EDQUOT]` | Free space or quota on the remote machine, in your home directory or `/tmp` | | `Free up disk space on this computer` | `[ENOSPC]` or `[EDQUOT]`, in a message that starts with `Couldn't prepare the deploy locally` | Free space on your computer | | `Claude Code won't start on ` | `[CLI_UNRESPONSIVE]` | Wait a minute, then try again. If it keeps failing, run the command that the message names on the remote machine to see whether Claude Code answers there. | diff --git a/content/en/docs/claude-code/errors.md b/content/en/docs/claude-code/errors.md index c3d513af5d..fda102fdf9 100644 --- a/content/en/docs/claude-code/errors.md +++ b/content/en/docs/claude-code/errors.md @@ -327,6 +327,8 @@ Match the message you see to a section below. | `Cannot read this as an image: is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) | | `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) | | `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Tool errors](#memory-index-is-over-its-read-limit) | +| `Sandbox is required but failed to initialize: ` | [Sandboxing troubleshooting](https://code.claude.com/docs/en/sandboxing.md#commands-refused-with-sandbox-is-required) | +| `Sandbox is required (sandbox.failIfUnavailable) and stopped being available in this session: ` | [Sandboxing troubleshooting](https://code.claude.com/docs/en/sandboxing.md#commands-refused-with-sandbox-is-required) | | `pkill: refusing to run` | [Tool errors](#pkill-pattern-matches-the-claude-code-process) | | `Failed to write to 's inbox — nothing was sent` | [Tool errors](#failed-to-write-to-a-teammate-inbox) | | `Failed to write the plan approval request to the lead's inbox — plan not submitted` | [Tool errors](#failed-to-write-to-a-teammate-inbox) | diff --git a/content/en/docs/claude-code/features-overview.md b/content/en/docs/claude-code/features-overview.md index f983224e40..16587433ff 100644 --- a/content/en/docs/claude-code/features-overview.md +++ b/content/en/docs/claude-code/features-overview.md @@ -262,7 +262,7 @@ Skills are extra capabilities in Claude's toolkit. They can be reference materia **Context cost:** Low until used. User-only skills have zero cost until invoked. -**In subagents:** Skills work differently in subagents. Instead of on-demand loading, skills listed in the subagent's `skills` field are fully preloaded into its context at launch. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool. +**In subagents:** The full content of skills listed in a subagent's `skills` field [loads into its context at launch](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents), rather than on demand. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool. > [!TIP] > diff --git a/content/en/docs/claude-code/glossary.md b/content/en/docs/claude-code/glossary.md index a8fdff95d4..1bdf764ccf 100644 --- a/content/en/docs/claude-code/glossary.md +++ b/content/en/docs/claude-code/glossary.md @@ -120,9 +120,9 @@ Learn more: [Commands](https://code.claude.com/docs/en/commands.md) · [Skills]( ### Compaction -Automatic summarization of your conversation when the [context window](#context-window) approaches its limit. Older tool outputs are cleared first, then the conversation is summarized. Project-root CLAUDE.md and auto memory survive compaction and reload from disk; instructions given only in conversation may be lost. Run `/compact` to trigger manually, optionally with a focus like `/compact focus on the API changes`. +Automatic summarization of your conversation when the [context window](#context-window) approaches its limit. Project-root CLAUDE.md and auto memory survive compaction, but instructions given only in conversation may not. Run `/compact` to trigger manually, optionally with a focus like `/compact focus on the API changes`. -Learn more: [What survives compaction](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up) +Learn more: [What survives compaction](https://code.claude.com/docs/en/context-window.md#what-survives-compaction) · [When context fills up](https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up) · [When Claude Code compacts a conversation you leave idle](https://code.claude.com/docs/en/settings-reference.md#idlecompaction) ### Connector diff --git a/content/en/docs/claude-code/hooks.md b/content/en/docs/claude-code/hooks.md index 6f598c533e..52e2d3e4a0 100644 --- a/content/en/docs/claude-code/hooks.md +++ b/content/en/docs/claude-code/hooks.md @@ -1747,7 +1747,7 @@ To run a hook when a specific file changes on disk, whatever wrote it, use [File Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, ask, or defer the tool call. -An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md) on `PreToolUse` that exceeds its timeout blocks the tool call, and Claude receives an error result naming the timeout. +An [Agent SDK callback hook](https://code.claude.com/docs/en/agent-sdk/hooks.md#hook-timeout) on `PreToolUse` that exceeds its timeout blocks the tool call. #### PreToolUse input diff --git a/content/en/docs/claude-code/how-claude-code-works.md b/content/en/docs/claude-code/how-claude-code-works.md index 28733d4c8e..2a8a0538a9 100644 --- a/content/en/docs/claude-code/how-claude-code-works.md +++ b/content/en/docs/claude-code/how-claude-code-works.md @@ -131,7 +131,7 @@ To change or remove the attribution lines, set [`attribution`](https://code.clau #### When context fills up -Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history. +Claude Code manages context automatically as you approach the limit. It compacts the conversation into a summary. The summary keeps your requests and key code snippets, but detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history. To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`). diff --git a/content/en/docs/claude-code/monitoring-usage.md b/content/en/docs/claude-code/monitoring-usage.md index 292f997fc3..0b721f1fce 100644 --- a/content/en/docs/claude-code/monitoring-usage.md +++ b/content/en/docs/claude-code/monitoring-usage.md @@ -470,7 +470,7 @@ When nothing else sets the variable, `host.name` arrives in the resource block, If the name doesn't arrive, check for one of these causes: * **You set it on the computer that runs Desktop**: Desktop doesn't pass a value you set there to the SSH session -* **You exported it in a login file**: only login shells read a file such as `/etc/profile`. A value you `export` there reaches Claude Code that you start from a login shell. It doesn't reach a Desktop SSH session, because Desktop doesn't start Claude Code through a login shell. +* **You exported it in `/etc/profile` or another file that only login shells read**: the name arrives when you run `claude` from a login shell, but not in a Desktop SSH session. Desktop doesn't start Claude Code through a login shell. Set the variable under `env` in the [managed settings file](https://code.claude.com/docs/en/desktop.md#managed-settings) on the remote machine instead. * **A value has a space inside it**: Claude Code then copies none of the keys onto events or datapoints and reports no error. [Take the space out of the value](#multi-team-organization-support). * **Something else already sets the variable**: in a session that the desktop app starts, a variable already set in the launch environment [takes precedence over settings files](https://code.claude.com/docs/en/settings-reference.md#how-env-values-interact-with-your-shell). The [debug log](https://code.claude.com/docs/en/debug-your-config.md) names each ignored variable. When a third-party Desktop deployment [names an OTLP endpoint](#how-managed-settings-lock-the-otlp-destination) in the environment it provides, that environment carries Desktop's own `OTEL_RESOURCE_ATTRIBUTES`. diff --git a/content/en/docs/claude-code/plugins-reference.md b/content/en/docs/claude-code/plugins-reference.md index 4e6c180f0b..3a789e3b6e 100644 --- a/content/en/docs/claude-code/plugins-reference.md +++ b/content/en/docs/claude-code/plugins-reference.md @@ -606,7 +606,7 @@ This shell-form hook runs a script bundled with the plugin: } ``` -On Windows, the substituted paths use forward slashes so a shell doesn't read backslashes as escapes. +On Windows, most substituted paths use forward slashes, as in `C:/Users/you/...`. They keep their native backslashes in an [exec-form hook](https://code.claude.com/docs/en/hooks.md#exec-form-and-shell-form) and in a hook that runs through PowerShell, which is the default shell on Windows when Git Bash isn't installed. ## Standard layout diff --git a/content/en/docs/claude-code/plugins/components.md b/content/en/docs/claude-code/plugins/components.md index e3ed70a4b9..8a603fc3b2 100644 --- a/content/en/docs/claude-code/plugins/components.md +++ b/content/en/docs/claude-code/plugins/components.md @@ -648,7 +648,7 @@ You don't know where your plugin will be installed, so refer to its files and da In the data directory path, `` is the plugin identifier with every character other than letters, digits, `_`, and `-` replaced by `-`, so `my-plugin@my-marketplace` becomes `my-plugin-my-marketplace`. -On Windows, the substituted paths use forward slashes so a shell doesn't read backslashes as escapes. +On Windows, most substituted paths use forward slashes, as in `C:/Users/you/...`. They keep their native backslashes in an [exec-form hook](https://code.claude.com/docs/en/hooks.md#exec-form-and-shell-form) and in a hook that runs through PowerShell, which is the default shell on Windows when Git Bash isn't installed. ### Install dependencies into the data directory diff --git a/content/en/docs/claude-code/plugins/loading.md b/content/en/docs/claude-code/plugins/loading.md index 06b9773595..050c152911 100644 --- a/content/en/docs/claude-code/plugins/loading.md +++ b/content/en/docs/claude-code/plugins/loading.md @@ -41,7 +41,7 @@ Plugins load at session start from `installed_plugins.json` and the cache withou * **A marketplace that settings declare but `known_marketplaces.json` lacks**: Claude Code clones it, then reloads plugins and downloads enabled plugins that aren't cached yet * **A declared marketplace whose source changed in settings**: Claude Code re-fetches it from the new source and shows `Plugins changed. Run /reload-plugins to activate.` -An enabled plugin that neither path fetched and that has no usable cache directory shows `Plugin "" not cached at ` in the `/plugin` **Errors** tab, and `claude plugin list` adds `— run /plugin to refresh` to the same line. For the fix, see [`Plugin "" not cached at `](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-cached-at). +An enabled plugin that neither path fetched and that has no usable cache directory shows `Plugin "" not cached at ` in the `/plugin` **Errors** tab. For the fix, see [`Plugin "" not cached at `](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-cached-at). ## Find where a plugin came from diff --git a/content/en/docs/claude-code/plugins/manifest-reference.md b/content/en/docs/claude-code/plugins/manifest-reference.md index 4e6c180f0b..3a789e3b6e 100644 --- a/content/en/docs/claude-code/plugins/manifest-reference.md +++ b/content/en/docs/claude-code/plugins/manifest-reference.md @@ -606,7 +606,7 @@ This shell-form hook runs a script bundled with the plugin: } ``` -On Windows, the substituted paths use forward slashes so a shell doesn't read backslashes as escapes. +On Windows, most substituted paths use forward slashes, as in `C:/Users/you/...`. They keep their native backslashes in an [exec-form hook](https://code.claude.com/docs/en/hooks.md#exec-form-and-shell-form) and in a hook that runs through PowerShell, which is the default shell on Windows when Git Bash isn't installed. ## Standard layout diff --git a/content/en/docs/claude-code/plugins/mods/api.md b/content/en/docs/claude-code/plugins/mods/api.md index 9110f22ce4..de64f6dbd6 100644 --- a/content/en/docs/claude-code/plugins/mods/api.md +++ b/content/en/docs/claude-code/plugins/mods/api.md @@ -313,9 +313,9 @@ For a call that rejects, such as `$.command.run`, catch the error and test its m #### What refused calls return -In the results, `` stands for `the session was stopped and nobody has sent input since`: +In the results, `` stands for the reason the call was refused. After an interruption, that's `the session was stopped and nobody has sent input since`. For other reasons, see [Calls refused in `claude -p` runs and Agent SDK sessions](#calls-refused-in-non-interactive-runs). -| Some refused calls | Result until the user's next input | +| Some refused calls | Result | | :- | :- | | `$.prompt.submit` | Resolves with `{ drop: '' }` and queues no prompt | | `$.command.run` | Rejects with an error whose message ends with `` | @@ -324,7 +324,7 @@ In the results, `` stands for `the session was stopped and nobody has se | `$.session.send` to an [agent team](https://code.claude.com/docs/en/agent-teams.md) teammate | Resolves with `{ isDelivered: false, reason: 'Teammate "" was not messaged: .' }`, where `` is the teammate's name | | [`$.tool.call`](https://code.claude.com/docs/en/plugins/mods/reference#mods-api-methods) of Bash with `run_in_background: true`, Monitor, or CronCreate | Resolves with `{ deny: ' was not run: it starts background work, a schedule or a goal, and ' }`, where `` is the tool's name | -Along with these `$.session.send` and `$.tool.call` results, the user can see the [`Stopped:` toast](https://code.claude.com/docs/en/plugins/mods/troubleshoot#stopped-type-a-message-to-continue). +When one of these `$.session.send` or `$.tool.call` calls is refused after an interruption in an interactive session, the user can see the [`Stopped:` toast](https://code.claude.com/docs/en/plugins/mods/troubleshoot#stopped-type-a-message-to-continue). #### Work your mod started before the interruption @@ -341,6 +341,31 @@ After the user stops a running turn, for example with Esc, some work your mod ha When a scheduled job comes due or a monitor raises an event before the user's next input, the user can see the [`Stopped:` toast](https://code.claude.com/docs/en/plugins/mods/troubleshoot#stopped-type-a-message-to-continue). +### Calls refused in `claude -p` runs and Agent SDK sessions + +In a `claude -p` run or an [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) session, a result such as `{ drop: 'the run reached its --max-turns limit' }` means the run refused your mod's call. + +A refused `$.prompt.submit` resolves with `{ drop: '' }`. Other refused calls, such as `$.command.run` and `$.agent.spawn`, give the results shown in [What refused calls return](#what-refused-calls-return) with the reason in place of ``. Find your `` below for what to do about it: + +* **`the run reached its --max-turns limit`**: turns from your mod's prompts and from subagents it spawns count toward [`--max-turns`](https://code.claude.com/docs/en/cli-reference#cli-flags) or the Agent SDK's [turn limit](https://code.claude.com/docs/en/agent-sdk/configuration.md#limit-turns-and-spend). For more turns, start the run with a higher limit. If you can't, have your mod stop making the refused call. If the run takes another prompt from the user or the SDK application, the turn count resets and the run accepts calls again. +* **`the run is past its --max-budget-usd limit`**: start the run with a higher `--max-budget-usd`, or raise the Agent SDK's [spend limit](https://code.claude.com/docs/en/agent-sdk/configuration.md#limit-turns-and-spend). If you can't, have your mod stop making the refused call. The limit applies to the run's total cost so far. That total keeps adding up when the run takes another prompt, so a retry returns the same reason. +* **`the host has ended its input`**: for example, the SDK application ended its [streaming input](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md), or stdin closed on a run started with [`--input-format stream-json`](https://code.claude.com/docs/en/cli-reference#cli-flags). The run is ending and takes no more input, so a retry returns the same reason. Have your mod stop making the refused call. If you start the run yourself, next time keep that input open until your mod has no more calls to make. +* **`the session was stopped and nobody has sent input since`**: the run was [interrupted](#calls-and-background-work-after-the-user-interrupts-a-turn), for example with the Agent SDK's [`interrupt()`](https://code.claude.com/docs/en/agent-sdk/typescript#query-object). To make the call again after the next message from the user or the SDK application, follow [Retry a refused or dropped call](#retry-a-refused-or-dropped-call). + +### A `claude -p` run with your mod never exits + +If your mod submits a prompt at the end of every turn, each prompt starts another turn. Without [`--max-turns`](https://code.claude.com/docs/en/cli-reference#cli-flags) or `--max-budget-usd`, a `claude -p` run that loads the mod goes on until you stop it yourself. + +To make the run end on its own, add either flag to the command in your shell. If other people start the run, have your mod stop submitting prompts once its work is done. This command adds `--max-turns`: + +```bash theme={null} +claude -p "find the TODOs" --max-turns 5 +``` + +Once the run reaches that limit, the mod's next prompt is [refused](#calls-refused-in-non-interactive-runs) instead of starting a turn, and the run ends. + +If the run still goes past the limit, run `claude --version` in your shell, and [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code) if yours is earlier than v2.1.304. The mod's prompts are refused at the limit from v2.1.299. If your mod spawns subagents, their turns count toward `--max-turns` from v2.1.304. + ## Send and receive messages between sessions A mod can send a plain-text message to another of your sessions, to one of this session's subagents, or to a teammate in its [agent team](https://code.claude.com/docs/en/agent-teams.md). It can also observe the messages that arrive and leave. @@ -390,7 +415,7 @@ A mod reaches the file system, processes, and the network through the mods API, | `$.http` | `fetch(url, init)` over `http` or `https`. It resolves to `{ status, ok, headers, text }` once the body is read. | | `$.store` | A JSON key-value store of your plugin's own, kept between sessions | | `$.env` | `get` and `set` environment variables. Write the name as a string literal. | -| `$.settings` | `read` what the settings files and managed policy hold | +| `$.settings` | `read()` resolves to all settings, merged into one object. With `{ source }` or `{ key }`, it resolves to [one source's settings or one key's value](#read-one-source-or-one-key) instead. | | `$.session` | `messages()` returns the transcript as a list of `{ role, text, toolUses }`. Also the working directory, model, and more. [`usage()`](https://code.claude.com/docs/en/plugins/mods/reference#mods-api-methods) returns context window use and plan limits. | | `$.mcp` | `call` a tool on a connected MCP server | @@ -408,6 +433,27 @@ A mod can refuse your `$.process.spawn` call after the command has produced outp * **`$.process.spawn started, and a plugin withheld its result:`**: the refusing mod hadn't read the command's output to the end. Claude Code stops the command if it's still running. * **`$.process.spawn ran, and a plugin withheld its result:`**: the refusing mod had read the command's output to the end, so the command had exited +### Read all settings, one source, or one key + +`$.settings.read()` resolves to one object that holds the settings from all sources in use, merged by [precedence](https://code.claude.com/docs/en/settings.md#settings-precedence). Pass `{ source }` to read one source instead, `{ key }` to read one key, or both: + +| Call | Resolves to | +| :- | :- | +| `$.settings.read()` | The merged settings as one object. Its top-level keys are those of a `settings.json` file, such as `permissions` and `hooks`. | +| `$.settings.read({ source: 'policy' })` | That one source's settings as one object, or `{}` when that source holds no settings | +| `$.settings.read({ key: 'spinnerTipsEnabled' })` | That key's value in the merged settings, or `undefined` when the key isn't set | +| `$.settings.read({ key: 'spinnerTipsEnabled', source: 'user' })` | That key's value in that one source, or `undefined` when that source doesn't set it | + +For `source`, pass the name of the one settings source to read: + +* **`user`**: `~/.claude/settings.json` +* **`project`**: `.claude/settings.json` +* **`local`**: `.claude/settings.local.json` +* **`flag`**: what you pass with `--settings`, and the SDK's inline settings +* **`policy`**: [managed settings](https://code.claude.com/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) + +For `key`, pass the exact name of one top-level key, not a dotted path into a nested object. The `key` argument requires Claude Code v2.1.304 or later. + ## Next steps * [React to events](https://code.claude.com/docs/en/plugins/mods/events.md): hook tool calls, prompts, and turns diff --git a/content/en/docs/claude-code/plugins/mods/create.md b/content/en/docs/claude-code/plugins/mods/create.md index 7aa10d4dab..ee13d66b38 100644 --- a/content/en/docs/claude-code/plugins/mods/create.md +++ b/content/en/docs/claude-code/plugins/mods/create.md @@ -48,6 +48,8 @@ Run `/plugin` at the Claude Code prompt and press Tab until the **Installed** ta Use what you asked for. For the example prompt, the current branch name appears above the prompt box. If the mod doesn't do what you wanted, tell Claude what to change. The mod reloads at the end of each turn that changes its files, so you can try the change as soon as Claude finishes. +If a transcript line that starts with the mod's name says the [change didn't load](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#this-mods-change-didnt-load), paste that line into your next message when you ask Claude for a fix. Claude doesn't see the line unless you paste it. + ### Use the mod in other sessions A mod Claude wrote loads only in the session that made it, and Claude Code deletes that session's mods folder once it's older than [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays). To keep the mod, copy its directory out of the mods folder to a place of your own, such as `~/mods/git-branch`. Then choose how to load it: diff --git a/content/en/docs/claude-code/plugins/mods/events.md b/content/en/docs/claude-code/plugins/mods/events.md index b816c1d058..9415ac0347 100644 --- a/content/en/docs/claude-code/plugins/mods/events.md +++ b/content/en/docs/claude-code/plugins/mods/events.md @@ -93,7 +93,7 @@ Register each event once per matcher. If you call `on` twice for `session.start` ## Hook what Claude is doing -Handle these events to see or change a tool call, a prompt, or a turn as it happens. For every event and what a hook can return, see the [events reference](https://code.claude.com/docs/en/plugins/mods/reference.md#events). +Handle these events to see or change a tool call, a prompt, a turn, or a settings read as it happens. For every event and what a hook can return, see the [events reference](https://code.claude.com/docs/en/plugins/mods/reference.md#events). ### Guard or change a tool call @@ -115,6 +115,8 @@ on('tool.call', { tool: 'Bash' }, async ($, e, next) => { When Claude tries `git push --force`, the command doesn't run and no permission prompt appears, because the hook never calls `next`. Claude reads the `deny` text as the tool's result, so write it as an instruction Claude can act on. Every other Bash command runs as it would without the mod. +If this hook throws or times out, Claude Code skips it and the command goes on as it would without the mod. To refuse the command instead, [add a `.catch` handler](#handle-a-hook-that-fails) to the hook. + To act after a tool has run, `await next(e)`, do your work, and return what `next` gave you. This hook logs each `.mdx` file Claude changes, with [`$.ui.log`](https://code.claude.com/docs/en/plugins/mods/api#show-something-without-starting-a-turn), which adds a dim line to the transcript that Claude doesn't read: ```javascript theme={null} @@ -177,7 +179,9 @@ When Claude tries a command such as `rm -rf build`, the question appears with th * **The user types an answer**: `$.ui.ask` resolves to the typed text. The hook compares it with `Run it`, so any other text refuses the command. * **Nobody answers**: `$.ui.ask` rejects when the user dismisses the question or picks **Chat about this**, and in a `claude -p` run, so the `catch` block leaves the answer at `Refuse` -Keep the wait inside a mods API call such as `$.ui.ask`, because that time doesn't count against the hook's [time limit](https://code.claude.com/docs/en/plugins/mods/reference.md#limits). Time spent awaiting a promise of your own does count. Claude Code skips a hook that times out, so the held command would run. +Keep the wait inside a mods API call such as `$.ui.ask`, because that time doesn't count against the hook's [time limit](https://code.claude.com/docs/en/plugins/mods/reference.md#limits). Time spent awaiting a promise of your own does count. + +Claude Code skips a hook that times out, so the held command would run. To refuse it instead, chain [a `.catch` handler](#handle-a-hook-that-fails) onto the registration that `on` returns. That handler is separate from the `catch` block inside the hook. #### Approve or refuse a tool call before the user is asked @@ -207,6 +211,7 @@ The hook denies `git push` on `main` and passes every other call through: * **On `main`**: the hook returns `deny`, even when a rule allows `git push` * **On another branch, and for other commands**: the call gets the decision it would get without the mod +* **The hook throws or times out**: the call also gets the decision it would get without the mod. To refuse the call instead, [add a `.catch` handler](#handle-a-hook-that-fails) that returns `{ decision: 'deny', reason: 'the reason' }`. The hook matches the text of the command, so treat it as a reminder for Claude. To block pushes to `main` for everyone, protect the branch on your Git host. @@ -269,7 +274,10 @@ on('prompt.submit', async ($, e, next) => { When you send a prompt such as `open a PR for this change`, your message looks the same in the transcript, and Claude also reads a line such as `Current branch: feature/auth` after it. A prompt that doesn't mention a pull request goes through unchanged, and `git` doesn't run. -To stop a prompt, return `{ drop: 'the reason' }` without calling `next`. The text goes back into the user's prompt input, and they see `Prompt dropped by a hook:` followed by your reason, so address the reason to them. If your hook returns a `drop` after its `next(e)` call let the prompt through, the turn still runs, and the hook [fails](#handle-a-hook-that-fails) with a message that includes `a drop after its next() was answered`. +To stop a prompt, return `{ drop: 'the reason' }` without calling `next`. The text goes back into the user's prompt input, and they see `Prompt dropped by a hook:` followed by your reason, so address the reason to them. The prompt still goes through in these cases: + +* **Your hook returns a `drop` after its `next(e)` call let the prompt through**: the turn still runs, and the hook [fails](#handle-a-hook-that-fails) with a message that includes `a drop after its next() was answered` +* **Your hook throws or times out**: Claude Code skips it and sends the prompt. [Add a `.catch` handler](#handle-a-hook-that-fails) so that a failure doesn't send a prompt the hook would have stopped. [Other events](https://code.claude.com/docs/en/plugins/mods/reference.md#prompts-and-what-claude-reads) cover the rest of what Claude reads: `prompt.section` for each section of the system prompt, `prompt.context` for the context sent with the first message, and `skill.prompt` for a skill's text. Text from these hooks that changes between requests [invalidates the prompt cache](https://code.claude.com/docs/en/prompt-caching.md). In a `skill.prompt` hook, you can also read [which plugin or file the skill came from](https://code.claude.com/docs/en/plugins/mods/reference.md#skill-prompt-fields). @@ -305,6 +313,68 @@ Claude's response streams to the screen as it does without the mod. After each r To see the tool calls that the API ran itself during the request, such as calls to the [advisor tool](https://code.claude.com/docs/en/advisor.md), read `result.serverToolUses`. Claude Code doesn't run these calls, so no `tool.call` or `tool.check` hook fires for them. The field is absent when the response has no such calls, and it requires Claude Code v2.1.290 or later. +### Change or refuse a settings read + +A `settings.read` hook runs on a mod's read and on Claude Code's own read: + +* **A mod's read**: a mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#read-one-source-or-one-key). +* **Claude Code's own read**: Claude Code builds the session's merged settings. This read repeats when settings or the loaded plugins change. + +Before you rely on either read, check the guard and your version: + +* **The built-in guard**: with managed settings, or with a Team or Enterprise [`/login`](https://code.claude.com/docs/en/authentication#authentication-precedence) as the session's credential, the [built-in guard](https://code.claude.com/docs/en/plugins/mods/admin.md#know-what-happens-by-default) can skip this hook in a mod you install or load with `--plugin-dir`. To check, search the [debug log](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#read-the-debug-log) for `settings.read bypassed by cc-plugin-sec-default`. If a line with that text names your mod, ask your organization's administrator to [install the mod as one of the organization's mods](https://code.claude.com/docs/en/plugins/mods/admin.md#install-your-organizations-mods). +* **The version**: the event firing on Claude Code's own read, and the `e.layers` field, require Claude Code v2.1.304 or later. + +#### What a `settings.read` hook receives + +| Field | Type | What it holds | +| :- | :- | :- | +| `e.layers` | array | One `{ source, settings }` object for each source in use that holds settings, lowest [precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) first: `plugin`, `user`, `project`, `local`, `flag`, `policy`. Empty in `claude plugin test`. | +| `e.source` | string | The one source a mod asked for, as in `$.settings.read({ source: 'policy' })`. `e.layers` then holds that layer alone. Absent on Claude Code's own read and on any other read of the merged settings. | + +In `e.layers`, `plugin` holds settings that enabled plugins supply, and is a layer name only, not a `source` you can pass to `$.settings.read`. `flag` holds the settings passed with `--settings`, and `policy` holds managed settings. + +#### Tell Claude Code's own read from a mod's read + +On [Claude Code's own read](#settings-read-hook), [`next.origin`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function) is `{ plugin: 'engine', tier: 'core' }`, and on a mod's read `next.origin.plugin` is the calling mod's name. + +#### What a `settings.read` hook can return + +Your hook can return [`next(e)`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function)'s result unchanged, a `{ value }` of its own, or `{ deny: reason }`. On [Claude Code's own read](#settings-read-hook) and a mod's read, a `{ value }` replaces what the read gives and `{ deny: reason }` refuses the read: + +| Return | On Claude Code's own read | On a mod's read | +| :- | :- | :- | +| `{ value }` | For each key you change, what you return replaces that key's whole value in the session's merged settings, if it [fits the key's schema](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-refused) | That mod's call resolves to your `value`, or to the `key` it asked for taken from your `value`, so return a whole object and not an array | +| `{ deny: reason }` | The session keeps the settings as they were merged before any hook answered, and the [debug log records your `reason`](https://code.claude.com/docs/en/plugins/mods/troubleshoot#settings-read-refused) | That mod's call rejects with `: $.settings.read: ` | + +On Claude Code's own read, build your `{ value }` from [`next(e)`'s `value`](#settings-read-next), since a key you leave out is unset. Where Claude Code reads a key such as `env` from each source separately, changing it in your `value` [has no effect](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-no-effect). + +#### What `next(e)` gives a `settings.read` hook + +`next(e)` resolves to `{ value }` or to `{ deny }`: + +* **`{ value }`**: `value` is the merged settings, or one source's settings when [`e.source`](#settings-read-receives) is set. If a hook that [runs after yours](#the-order-mods-run-in) returned a `{ value }` of its own, you get that hook's `value` instead. +* **`{ deny }`**: a hook that runs after yours refused the read. Return that `{ deny }` unchanged. + +#### Change one setting from a `settings.read` hook + +First check [which mods get this event, and from which version](#settings-read-hook). + +To change one key, spread the `value` from [`next(e)`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function) and set that key, as this hook does with [`spinnerTipsEnabled`](https://code.claude.com/docs/en/settings-reference#spinnertipsenabled). The hook doesn't check [`next.origin`](#settings-read-origin), so the hook changes the key on [Claude Code's own read](#settings-read-hook) and on a mod's merged read alike: + +```javascript theme={null} +on('settings.read', async ($, e, next) => { + const read = await next(e) + // Pass through a read of one source, so that only the merged settings change. + // Pass through a { deny } from a later hook too: it has no value. + if (e.source || !read.value) return read + // Keep every other key and change this one + return { value: { ...read.value, spinnerTipsEnabled: false } } +}) +``` + +On Claude Code's own read, if your hook returns a value outside the key's schema, such as a string, that key alone keeps the value merged before any hook answered. The debug log then says [`the answer for is no value the key can hold`](https://code.claude.com/docs/en/plugins/mods/troubleshoot#settings-read-key-refused). If your value fits and the key still doesn't change, see [why a returned key has no effect](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-no-effect). + ### Handle the settings hook events Settings hooks are the command, HTTP, prompt, and agent hooks you configure in settings files. Each [settings hook event](https://code.claude.com/docs/en/hooks.md#hook-events), such as `Stop`, `SessionEnd`, or `PostToolUse`, is also an event named `classic.` followed by the settings hook event's name, such as `classic.Stop`. `e` is the JSON a settings hook receives on stdin, including `transcript_path`. diff --git a/content/en/docs/claude-code/plugins/mods/interface.md b/content/en/docs/claude-code/plugins/mods/interface.md index 5656789b0f..d798ed436e 100644 --- a/content/en/docs/claude-code/plugins/mods/interface.md +++ b/content/en/docs/claude-code/plugins/mods/interface.md @@ -508,7 +508,16 @@ When the user presses a button, types into a field, or picks from a list your mo * **`Input`**: takes `onSubmit(value)` and `onInput(value)` * **`Select`**: takes `onSelect(value)` with its choices in `options`, a list of at least one choice with unique values, such as `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]` -A test presses or types into a control by its `key`, so give each control one. Each use of a control also fires [`ui.press`, `ui.input`, or `ui.select`](https://code.claude.com/docs/en/plugins/mods/reference#interface) with the `key` in `e.element`, and another mod can handle those events. Its hook runs before your callback, so it sees what the user types into your `Input` and can change it or answer in place of your callback. The mods API has no method that presses another mod's button. +### Which controls need a `key` + +Give every `Input` and `Select` a `key` prop, such as `key: 'size'`. A `Button` can go without a `key` when it has a `label` prop or a single string child. Its key is then the `label` value or that string. + +Tests and other mods identify a control by its key: + +* **Tests**: a [test](https://code.claude.com/docs/en/plugins/mods/test.md#test-a-drawing) presses or types into a control by its key. +* **Other mods**: Claude Code fires [`ui.press`, `ui.input`, or `ui.select`](https://code.claude.com/docs/en/plugins/mods/reference#interface) with the control's key in `e.element` before it runs the control's callback. Another mod's hook for that event sees what the user typed into your `Input` and can change that text or keep your callback from running. The mods API gives that mod no method to press your buttons. + +If a message says `needs a key` or `is drawn twice`, [find the cause by that message](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#needs-a-key). ### Keyboard focus and hotkeys diff --git a/content/en/docs/claude-code/plugins/mods/reference.md b/content/en/docs/claude-code/plugins/mods/reference.md index 7d6ee784f2..b86fbac802 100644 --- a/content/en/docs/claude-code/plugins/mods/reference.md +++ b/content/en/docs/claude-code/plugins/mods/reference.md @@ -21,7 +21,7 @@ A mod is a plugin directory with these files: | `.claude-plugin/plugin.json` | Yes | The plugin [manifest](https://code.claude.com/docs/en/plugins/manifest-reference.md). Mods add no required fields. | | `hooks/hooks.json` | Yes | `modules`: an array with one path, relative to this file, to the hooks module, as in `"modules": ["./register.js"]`. Can also hold [settings hooks](https://code.claude.com/docs/en/hooks.md) under `hooks`. | | The hooks module, such as [`hooks/register.js`](https://code.claude.com/docs/en/plugins/mods/create#write-a-mod-yourself) | Yes | The mod's entry point. Exports `register(on, options)`. Named `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, or `.tsx`. An ES module. | -| [`types/index.d.ts`](https://code.claude.com/docs/en/plugins/mods/interface#declare-the-values), named by `types` in the manifest | When the mod uses `$.state` or adds a namespace to the mods API | Declares `PluginState` values and any namespace the mod adds | +| [`types/index.d.ts`](https://code.claude.com/docs/en/plugins/mods/interface#declare-the-values), unless `types` in the manifest names another path | When the mod uses `$.state` or adds a namespace to the mods API | Declares `PluginState` values and any namespace the mod adds. To leave `types` out of the manifest, you need v2.1.299 or later. | | Files whose names end in `.test.ts` or `.test.tsx` | No | Tests that [`claude plugin test`](https://code.claude.com/docs/en/plugins/mods/test#write-a-test) runs | `register` receives `on` and `options`. `options` holds the values of the [`userConfig`](https://code.claude.com/docs/en/plugins/components#user-configuration) fields the manifest declares, with defaults filled in. @@ -110,7 +110,7 @@ On `skill.prompt`, `e.source`, `e.pluginName`, `e.path`, `e.frontmatter`, and `e ### Commands and configuration -Command and configuration events fire when a command runs or is listed, and when a `/config` row is shown or changed: +Command and configuration events fire when a command runs or is listed, when a `/config` row is shown or changed, and on a settings read: | Event | Fires when | A hook can return | | :- | :- | :- | @@ -118,6 +118,14 @@ Command and configuration events fire when a command runs or is listed, and when | `command.describe` | Once for each command, for the command list | `{ description, argumentHint, isHidden }` | | `config.set` | A `/config` row is about to change | `next({ ...e, value })` or `{ deny: reason }` | | `config.describe` | Once for each `/config` row | `{ label, description, isHidden }` | +| [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) | A mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network), or Claude Code builds the session's merged settings | `next(e)`, `{ value }`, or `{ deny: reason }` | + +#### `e.layers` and `e.source` on `settings.read` + +* **`e.layers`**: one `{ source, settings }` object for each source in use that holds settings, lowest [precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) first. See [What a `settings.read` hook receives](https://code.claude.com/docs/en/plugins/mods/events#settings-read-receives). +* **`e.source`**: the one source a mod asked for, as in `$.settings.read({ source: 'policy' })`. Absent on Claude Code's own read and on any other read of the merged settings + +On `settings.read`, the event firing on Claude Code's own read and the `e.layers` field require Claude Code v2.1.304 or later. For when the hook runs and what the hook can return, with an example, see [Change or refuse a settings read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook). ### Turns diff --git a/content/en/docs/claude-code/plugins/mods/troubleshoot.md b/content/en/docs/claude-code/plugins/mods/troubleshoot.md index 125b11e50e..2ea42511ad 100644 --- a/content/en/docs/claude-code/plugins/mods/troubleshoot.md +++ b/content/en/docs/claude-code/plugins/mods/troubleshoot.md @@ -168,6 +168,15 @@ There's nothing to fix. Before v2.1.292, the call ran a second time, so the prompt was submitted, the command run, or the subagent started twice. +### `This mod's change didn't load` or `the earlier version is no longer running` + +A change to a [mod Claude wrote in this session](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod) couldn't load. The transcript line starts with the mod's name and ends with the reason: + +* `This mod's change didn't load, so the earlier version is still running: .` +* `This mod didn't load, and the earlier version is no longer running: .` + +Claude doesn't see this line, so paste it into your next message when you ask Claude for a fix. + ### `$.agent.register refused: the hooks module that made the call is no longer loaded` The line starts with your mod's name, as in `first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)`, and the agent isn't registered. Your mod was reloaded or unloaded before the call. A reload loads a fresh copy of the hooks module, and this call came from code still running in the old copy, such as a hook that hadn't returned yet. @@ -225,6 +234,15 @@ The [tree](https://code.claude.com/docs/en/plugins/mods/interface.md#build-a-tre Read the reason on that line. Common causes are a prop the element doesn't take and an element the app doesn't have. +### `needs a key`, `is drawn twice`, or `key each once` + +An element in the tree your `ui.render` hook returns has no valid [`key`](https://code.claude.com/docs/en/plugins/mods/interface#which-controls-need-a-key), or two elements share one. Find the message you got: + +* **` needs a key` or `