upstream: claude code updates 2026-03-18

docs/agent-teams.md

@@ -62,6 +62,30 @@ spawn multiple Task calls at once and they run in parallel automatically:
 
 ---
 
+
+
+### agent effort levels (v2.1.78+)
+
+agents can now declare effort levels in their frontmatter. this controls how thoroughly claude explores before declaring the task done:
+
+```markdown
+---
+effort: balanced
+maxTurns: 20
+disallowedTools: ["Bash(rm *)", "Write(/sensitive/)", "Edit(secrets.*)"]
+---
+
+your agent prompt here...
+```
+
+| effort | behavior |
+|---|---|
+| `minimal` | quick answer, one pass, move on |
+| `balanced` | default. explore alternatives, verify results |
+| `thorough` | exhaustive testing, multiple approaches, double-check everything |
+
+`maxTurns` caps the agent's conversation length. `disallowedTools` blocks specific tool calls (regex matching).
+
 ## the /batch command
 
 if you dont need a coordinator agent orchestrating things, `/batch` is the simpler path. describe multiple independent tasks and claude runs them in parallel worktrees. you review the diffs.

docs/cost-analysis.md

@@ -94,6 +94,12 @@ targeted reads can be 10-20x cheaper than exploratory ones.
 
 send haiku to explore, sonnet to implement. haiku reads 30 files for pennies. sonnet reads the 4 files that matter. see [subagent-patterns.md](./subagent-patterns.md) for the full pattern.
 
+
+
+### token limits and output capping
+
+v2.1.78 increased default max output tokens for opus 4.6 to 64k (previously lower). the hard upper bound for opus 4.6 and sonnet 4.6 is now 128k tokens. this lets longer generations complete without hitting the old ceiling, but large outputs still cost accordingly. use `maxTurns` in agent frontmatter to cap exploration rounds instead of relying on token limits.
+
 ### compact strategically
 
 `/compact` when context is bloated but you want to continue the session. good triggers:

docs/glossary.md

@@ -69,3 +69,6 @@ terms used across this repo and claude code docs.
 **UserPromptSubmit** -- hook event that fires when the user submits a prompt. useful for prompt classification, routing, or pre-processing.
 
 **worktree** -- a git feature that creates a separate working directory sharing the same repo history. claude code uses worktrees to let subagents work on code without conflicting with the main session's working directory.
+
+
+**effort level** -- agent configuration option controlling how thoroughly claude explores before finishing. options: minimal, balanced (default), thorough. set via `effort` frontmatter in agent definitions.

docs/guide.md

@@ -178,6 +178,12 @@ anything you can configure: permissions, hooks, model, theme, environment variab
 
 ---
 
+
+
+**plugin persistent data:**
+
+plugins can now store state that persists across updates via `${CLAUDE_PLUGIN_DATA}`. this is set by the plugin system and available to all hook scripts. useful for plugins that maintain metrics, config, or history.
+
 ### 6. your first real task
 
 heres a real workflow for fixing a bug. this is how most sessions go:

docs/hooks-guide.md

@@ -136,6 +136,50 @@ Instead of just using exit codes, you can `exit 0` and print a JSON object to st
 
 ## All Hook Events -- Complete Reference
 
+
+
+### StopFailure
+
+**When it fires:** When a turn ends due to an API error (rate limit, auth failure, network timeout, etc.).
+
+**Matcher:** Not supported (fires on every API error).
+
+**Use it for:** Logging failures, alerting on repeated rate limits, triggering retry logic, notifying on auth issues.
+
+**Input JSON:**
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
+  "cwd": "/Users/you/my-project",
+  "permission_mode": "default",
+  "hook_event_name": "StopFailure",
+  "error_type": "rate_limit_exceeded",
+  "error_message": "429 Too Many Requests",
+  "turn_count": 12
+}
+```
+
+**Key fields:**
+- `error_type` -- one of: `rate_limit_exceeded`, `auth_error`, `network_error`, `api_error`, `model_unavailable`
+- `error_message` -- the underlying error text
+- `turn_count` -- how many successful turns completed before this failure
+
+**Can block?** No. Hook runs after the error; session is already stopped.
+
+**Example use case:** count consecutive rate limits and alert when threshold is hit:
+
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+ERROR_TYPE=$(echo "$INPUT" | jq -r '.error_type')
+if [ "$ERROR_TYPE" = "rate_limit_exceeded" ]; then
+  COUNT=$(grep -c 'rate_limit_exceeded' ~/.claude/error-log.txt 2>/dev/null || echo 0)
+  echo "Rate limit hit (count: $((COUNT+1)))" >&2
+fi
+```
+
 ### SessionStart
 
 **When it fires:** When a session begins, resumes, or restarts after `/clear` or compaction.

docs/plugin-creation.md

@@ -49,6 +49,9 @@ every plugin needs exactly one `plugin.json` at its root. here is the full spec:
 | `license` | yes | SPDX identifier. `MIT` is the safe default. |
 | `hooks` | yes | Object mapping hook event names to arrays of hook handlers. Same structure as `settings.json` hooks. |
 | `keywords` | no | Array of strings for marketplace search. Keep it to 3-5 relevant terms. |
+| `agents` | no | Array of agent definitions with `effort`, `maxTurns`, and `disallowedTools` frontmatter support. |
+| `skills` | no | Array of skill definitions that plugin provides. |
+| `commands` | no | Array of custom command definitions. |
 
 ### hooks format
 
@@ -58,6 +61,30 @@ so `"command": "./hooks/my-hook.sh"` resolves to `<plugin-install-dir>/hooks/my-
 
 you can use any hook event: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`, etc. see the [hooks guide](./hooks-guide.md) for the full list.
 
+
+
+### persistent plugin state with ${CLAUDE_PLUGIN_DATA}
+
+v2.1.78 adds plugin persistent storage that survives plugin updates. use the `${CLAUDE_PLUGIN_DATA}` variable in your hook scripts to store and retrieve state:
+
+```bash
+#!/usr/bin/env bash
+SAVED_STATE="${CLAUDE_PLUGIN_DATA}/state.json"
+
+# read existing state
+if [ -f "$SAVED_STATE" ]; then
+  COUNTER=$(jq -r '.counter // 0' "$SAVED_STATE")
+else
+  COUNTER=0
+fi
+
+# increment and save
+COUNTER=$((COUNTER + 1))
+echo "{\"counter\": $COUNTER}" > "$SAVED_STATE"
+```
+
+when you run `/plugin uninstall`, claude prompts whether to delete the persistent data. this is useful for plugins that maintain history, config, or metrics across sessions.
+
 ### hooks with matchers
 
 ```json

docs/troubleshooting.md

@@ -20,6 +20,15 @@ common problems and fixes. organized by feature area.
 - check: `~/.claude/settings.json` for malformed JSON
 - validate: `python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"`
 
+
+
+### "Security: sandbox disabled" warning at startup
+
+- cause: sandbox is enabled in settings but dependencies are missing
+- fix: install required dependencies (check `/sandbox` Dependencies tab for OS-specific instructions)
+- or disable sandbox: set `sandbox.enabled: false` in settings if you don't need it
+- v2.1.78 now shows a visible warning instead of silently disabling sandbox
+
 ### context window fills up too fast
 
 - use the [handoff plugin](../plugins/handoff/) to save context before compaction