docs: add best practices for robust apiKeyHelper scripts

Add comprehensive guidance for writing reliable helper scripts that avoid
infinite retry loops when VPN or network-dependent credential helpers fail.

Includes:
- TTL configuration documentation (CLAUDE_CODE_API_KEY_HELPER_TTL_MS)
- Timeout best practices for network operations
- VPN-aware connectivity checks
- Local token caching patterns
- Troubleshooting guide for common issues

Addresses feedback from New Relic about apiKeyHelper retry loop behavior.

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.0.74
+
+- Added LSP (Language Server Protocol) tool for code intelligence features like go-to-definition, find references, and hover documentation
+- Added `/terminal-setup` support for Kitty, Alacritty, Zed, and Warp terminals
+- Added ctrl+t shortcut in `/theme` to toggle syntax highlighting on/off
+- Added syntax highlighting info to theme picker
+- Added guidance for macOS users when Alt shortcuts fail due to terminal configuration
+- Fixed skill `allowed-tools` not being applied to tools invoked by the skill
+- Fixed Opus 4.5 tip incorrectly showing when user was already using Opus
+- Fixed a potential crash when syntax highlighting isn't initialized correctly
+- Fixed visual bug in `/plugins discover` where list selection indicator showed while search box was focused
+- Fixed macOS keyboard shortcuts to display 'opt' instead of 'alt'
+- Improved `/context` command visualization with grouped skills and agents by source, slash commands, and sorted token count
+- [Windows] Fixed issue with improper rendering
+- [VSCode] Added gift tag pictogram for year-end promotion message
+
 ## 2.0.73
 
 - Added clickable `[Image #N]` links that open attached images in the default viewer

hook-selection-bug-issue.md

@@ -1,64 +0,0 @@
-# Bug Report: /hooks command always selects PreToolUse on first attempt
-
-## Summary
-
-When using the `/hooks` command to create a new hook, the hook type selector always selects `PreToolUse` on the first attempt, regardless of which option the user scrolls to and selects with Enter. The selection works correctly on subsequent attempts after pressing Escape.
-
-## Steps to Reproduce
-
-1. Open Claude Code
-2. Type `/hooks` to open the hooks management interface
-3. Navigate to create a new hook
-4. When the hook type selector appears (showing PreToolUse, PostToolUse, Stop, UserPromptSubmit, etc.), scroll down using arrow keys to select a different hook type (e.g., `PostToolUse`)
-5. Press Enter to confirm selection
-6. **Bug:** `PreToolUse` is selected instead of the highlighted option
-
-## Workaround
-
-1. Press Escape to cancel the selection
-2. Re-enter the hook type selector
-3. Scroll to desired hook type
-4. Press Enter
-5. **Result:** Correct hook type is now selected
-
-## Expected Behavior
-
-The hook type selector should select the option that is visually highlighted when the user presses Enter, on both first and subsequent attempts.
-
-## Root Cause Analysis
-
-This appears to be a **state synchronization issue** where:
-
-1. On first render of the hook type selector, the internal selected index is initialized to `0` (PreToolUse is the first item)
-2. The visual highlight updates correctly when scrolling with arrow keys (the user sees a different item highlighted)
-3. However, when pressing Enter, the handler reads from the internal state (which may still be `0`) rather than the current highlighted position
-4. After pressing Escape and re-opening the selector, the state is properly synchronized
-
-### Potential Code Areas
-
-Based on similar issues and the CHANGELOG history, the fix likely involves one of these patterns:
-
-1. **Initial state not synced**: The selection state may need to be initialized differently, or there's a race condition between render and state initialization
-
-2. **Event handler reading stale state**: The Enter key handler might be using a captured/stale reference to the selection index rather than the current value
-
-3. **Scroll handler not updating state**: The arrow key navigation might only be updating the visual highlight without updating the underlying state that Enter reads from
-
-### Similar Fixed Issues
-
-- **CHANGELOG v2.0.35**: "Fixed menu navigation getting stuck on items with empty string or other falsy values (e.g., in the `/hooks` menu)"
-- **CHANGELOG v0.2.69**: "Fixed UI glitches with improved Select component behavior"
-- **Issue #6674**: Hook Navigation Infinite Loop on Duplicate Entries (related Select component issue)
-
-## Environment
-
-- Reported on: Multiple environments
-- Claude Code Version: Current latest
-
-## Slack Thread Reference
-
-https://anthropic.slack.com/archives/C07VBSHV7EV/p1766159670734839?thread_ts=1766158844.979909&cid=C07VBSHV7EV
-
-## Labels
-
-`bug`, `hooks`, `ui`, `select-component`

plugins/plugin-dev/skills/mcp-integration/references/authentication.md

@@ -264,6 +264,139 @@ EOF
 - Time-based authentication
 - Dynamic tenant/workspace selection
 
+### TTL Configuration
+
+By default, dynamically generated API keys are cached for 5 minutes. Configure the TTL with:
+
+```bash
+export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000  # 5 minutes (default)
+```
+
+### Writing Robust Helper Scripts
+
+Helper scripts can cause issues if they hang or fail repeatedly. Follow these best practices to prevent infinite retry loops and connection hangs:
+
+**1. Always set timeouts on network operations:**
+```bash
+#!/bin/bash
+# get-token.sh - Robust token fetcher
+
+# Set a timeout for the entire script
+TIMEOUT_SECONDS=10
+
+# Use timeout for network calls
+TOKEN=$(timeout ${TIMEOUT_SECONDS}s curl -s --max-time ${TIMEOUT_SECONDS} \
+  "https://auth.example.com/token" 2>/dev/null)
+
+if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
+  # Exit with error - don't output invalid JSON
+  echo "Failed to fetch token" >&2
+  exit 1
+fi
+
+echo "{\"Authorization\": \"Bearer $TOKEN\"}"
+```
+
+**2. Handle VPN/network dependency failures:**
+```bash
+#!/bin/bash
+# get-headers.sh - VPN-aware token fetcher
+
+# Quick connectivity check before attempting auth
+if ! timeout 2s ping -c 1 vpn-dependent-service.internal >/dev/null 2>&1; then
+  echo "VPN not connected or service unreachable" >&2
+  exit 1
+fi
+
+# Proceed with token fetch (with timeout)
+TOKEN=$(timeout 10s get-token-from-vpn-service)
+
+if [ $? -ne 0 ] || [ -z "$TOKEN" ]; then
+  echo "Token fetch failed" >&2
+  exit 1
+fi
+
+echo "{\"Authorization\": \"Bearer $TOKEN\"}"
+```
+
+**3. Cache tokens locally to reduce network calls:**
+```bash
+#!/bin/bash
+# get-headers-cached.sh - Token fetcher with local caching
+
+CACHE_FILE="${HOME}/.cache/my-api-token"
+CACHE_MAX_AGE=240  # seconds (refresh before 5min TTL)
+
+# Check cache validity
+if [ -f "$CACHE_FILE" ]; then
+  CACHE_AGE=$(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE")))
+  if [ "$CACHE_AGE" -lt "$CACHE_MAX_AGE" ]; then
+    cat "$CACHE_FILE"
+    exit 0
+  fi
+fi
+
+# Fetch new token with timeout
+TOKEN=$(timeout 10s fetch-new-token 2>/dev/null)
+
+if [ -z "$TOKEN" ]; then
+  # If fetch fails, try to use expired cache as fallback
+  if [ -f "$CACHE_FILE" ]; then
+    echo "Warning: Using expired cached token" >&2
+    cat "$CACHE_FILE"
+    exit 0
+  fi
+  echo "Failed to fetch token and no cache available" >&2
+  exit 1
+fi
+
+# Update cache
+mkdir -p "$(dirname "$CACHE_FILE")"
+echo "{\"Authorization\": \"Bearer $TOKEN\"}" > "$CACHE_FILE"
+cat "$CACHE_FILE"
+```
+
+**4. Fail fast with clear error messages:**
+```bash
+#!/bin/bash
+set -e  # Exit on any error
+
+# Check prerequisites before attempting network calls
+if [ -z "$API_SECRET" ]; then
+  echo "API_SECRET environment variable not set" >&2
+  exit 1
+fi
+
+# Use short timeouts to fail fast
+TOKEN=$(timeout 5s curl -sf --max-time 5 \
+  -H "X-Secret: $API_SECRET" \
+  "https://auth.example.com/token") || {
+  echo "Token request failed or timed out" >&2
+  exit 1
+}
+
+echo "{\"Authorization\": \"Bearer $TOKEN\"}"
+```
+
+### Troubleshooting Helper Scripts
+
+**Infinite retry loop / hanging:**
+- Add timeouts to all network operations
+- Use `set -e` to exit on errors
+- Check VPN/network connectivity before making requests
+- Ensure script outputs valid JSON or exits with error code
+
+**Script takes too long:**
+- Use `timeout` command wrapper
+- Set `--max-time` on curl requests
+- Consider caching tokens locally
+- Reduce TTL if tokens refresh too slowly
+
+**VPN-dependent helpers failing:**
+- Add connectivity check at start of script
+- Implement graceful degradation with cached tokens
+- Log clear error messages to stderr
+
 ## Security Best Practices
 
 ### DO