Adopt Claude Code v2.1.83 → v2.1.122 features in the template

[scotthavird]

Problem

Claude Code shipped substantial new features in v2.1.83 → v2.1.122 (March 23 – April 28, 2026) that the template doesn't yet demonstrate or use. New extension points (PreCompact hook, updatedToolOutput, plugin bin/, themes), new settings (statusLine.refreshInterval, sandbox.network.deniedDomains, prUrlTemplate), and new affordances (alwaysLoad MCP, ${CLAUDE_EFFORT} skill interpolation, agent-level mcpServers and hooks frontmatter, auto mode, /ultrareview) are all relevant for a starter template that's meant to be a working reference of the tool.

A template that's a snapshot of the tool from 5 weeks ago is misleading: users who fork it think they're seeing best practices, but they're actually missing some of the most useful capabilities the tool has shipped. The cost is opportunity cost, not breakage — the template still works as-is — but the gap will keep growing if we don't update.

Solution

Audit the v2.1.83 → v2.1.122 changelog. Wire in every feature that's relevant for a template (i.e., something a forker would want demonstrated, not internal architecture changes or UI features). Specifically:

• New hooks: PreCompact (checkpoint before compaction), PostToolUse.updatedToolOutput (secret redaction).
• Hook payload field: use duration_ms in the existing session-cost hook for per-tool timing.
• MCP: alwaysLoad: true on filesystem and git so they skip tool-search deferral.
• Settings: statusLine.refreshInterval, sandbox.network.deniedDomains, prUrlTemplate.
• Plugin spec: bin/ executable + themes/ directory; bump plugin to v0.3.0.
• Skills: ship one that demonstrates ${CLAUDE_EFFORT} interpolation.
• Agents: demonstrate mcpServers: and hooks: frontmatter on an existing agent.
• CI: claude ultrareview mode in scripts/ci-review.sh.
• Env vars: document the new ones (ENABLE_PROMPT_CACHING_1H, CLAUDE_CODE_NO_FLICKER, CLAUDE_CODE_HIDE_CWD, CLAUDE_CODE_FORK_SUBAGENT, DISABLE_UPDATES, ANTHROPIC_BEDROCK_SERVICE_TIER).
• Permission modes: document auto and autoMode.allow/soft_deny/environment blocks.
• Docs: refresh CLAUDE.md, README.md, docs/hooks-cookbook.md, docs/permission-modes.md, docs/plugins.md, docs/integrations.md.
• Housekeeping: add .claude/scheduled_tasks.lock, .claude/checkpoints/, .claude/*.lock to .gitignore.

Architecture

graph TD
  subgraph New[v2.1.83 → v2.1.122 features added]
    H1[PreCompact hook]
    H2[updatedToolOutput hook]
    H3[duration_ms in payload]
    M1[MCP alwaysLoad]
    P1[plugin bin/]
    P2[plugin themes/]
    S1[statusLine.refreshInterval]
    S2[sandbox.network.deniedDomains]
    S3[prUrlTemplate]
    S4[auto permissionMode + autoMode]
    K1[skill CLAUDE_EFFORT]
    A1[agent mcpServers/hooks frontmatter]
    C1[claude ultrareview]
  end

  subgraph Touched[Files touched]
    T1[.claude/settings.json]
    T2[.mcp.json]
    T3[.claude-plugin/plugin.json]
    T4[.claude/themes/]
    T5[bin/]
    T6[scripts/hooks/*.sh]
    T7[CLAUDE.md / README.md / docs/]
  end

  H1 --> T1 & T6
  H2 --> T1 & T6
  H3 --> T6
  M1 --> T2
  P1 --> T3 & T5
  P2 --> T3 & T4
  S1 & S2 & S3 --> T1
  S4 --> T7
  K1 --> T7
  A1 --> T7
  C1 --> T6 & T7

Loading

Business Impact

• A fork of the template now demonstrates what current Claude Code can do, not what it could do six weeks ago.
• The new redact-secrets hook plus block-dangerous-bash form a layered safety net — secrets leaked into tool output never reach the model.
• PreCompact checkpointing means long sessions don't lose context silently.
• ${CLAUDE_EFFORT} skill demo shows how to scope work consistently across low/xhigh without writing two skills.
• alwaysLoad MCP keeps the most-used tools always available, skipping search deferral.

Acceptance Criteria

• PreCompact hook wired up with a working checkpoint script
• redact-secrets hook uses hookSpecificOutput.updatedToolOutput
• session-cost.sh reads per-tool duration_ms from logs
• .mcp.json declares alwaysLoad: true for filesystem and git
• .claude/themes/ ships at least one theme
• bin/ ships at least one executable
• .claude-plugin/plugin.json registers themes and bin components
• One skill demonstrates ${CLAUDE_EFFORT}
• One agent demonstrates mcpServers: and hooks: frontmatter
• scripts/ci-review.sh supports --ultrareview <target> mode
• settings.json includes statusLine.refreshInterval, sandbox.network.deniedDomains, prUrlTemplate
• settings.local.json.example documents new env vars and autoMode
• docs/permission-modes.md documents auto mode
• docs/hooks-cookbook.md covers all new hook events and the conditional if field
• docs/plugins.md notes bin/, themes/, monitors, claude plugin tag/prune
• docs/integrations.md notes /ultrareview and Routines
• .gitignore excludes Claude Code runtime state
• All JSON valid; all shell scripts pass bash -n
• All new hook scripts smoke-tested

Technical Notes

• Files affected: 17 files (new + modified)
• Dependencies: none
• Breaking changes: none. All additive. Existing forks pull this and the only behavior changes are: (a) new hooks fire on additional events, (b) MCP alwaysLoad accelerates tool availability, (c) statusline now refreshes every 5 seconds.

Agent Context

• change-type: feature
• risk-level: low
• test-coverage: JSON validation via jq, shell syntax via bash -n, smoke tests for redact-secrets, pre-compact, session-cost, and the bin/claude-template-info script.
• rollback-plan: git revert the squash-merge commit. All changes are additive; no removed functionality to restore.

Workflow Progress

graph LR
    A[Analyze] --> B[Issue] --> C[Branch] --> D[Implement] --> E[PR] --> F[Review] --> G[CI] --> H[Merge] --> I[Deploy] --> J[Shipped]
    classDef done fill:#22c55e,stroke:#16a34a,color:#fff
    classDef active fill:#eab308,stroke:#ca8a04,color:#fff
    classDef todo fill:#d1d5db,stroke:#9ca3af,color:#fff
    class A,B,C,D,E,F,G,H,I,J done

Loading