Add files using upload-large-folder tool

.claude-plugin/marketplace.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "claude-code-plugins",
+  "version": "1.0.0",
+  "description": "Bundled plugins for Claude Code including Agent SDK development tools, PR review toolkit, and commit workflows",
+  "owner": {
+    "name": "Anthropic",
+    "email": "support@anthropic.com"
+  },
+  "plugins": [
+    {
+      "name": "agent-sdk-dev",
+      "description": "Development kit for working with the Claude Agent SDK",
+      "source": "./plugins/agent-sdk-dev",
+      "category": "development"
+    },
+    {
+      "name": "claude-opus-4-5-migration",
+      "description": "Migrate your code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5.",
+      "version": "1.0.0",
+      "author": {
+        "name": "William Hu",
+        "email": "whu@anthropic.com"
+      },
+      "source": "./plugins/claude-opus-4-5-migration",
+      "category": "development"
+    },
+    {
+      "name": "code-review",
+      "description": "Automated code review for pull requests using multiple specialized agents with confidence-based scoring to filter false positives",
+      "version": "1.0.0",
+      "author": {
+        "name": "Boris Cherny",
+        "email": "boris@anthropic.com"
+      },
+      "source": "./plugins/code-review",
+      "category": "productivity"
+    },
+    {
+      "name": "commit-commands",
+      "description": "Commands for git commit workflows including commit, push, and PR creation",
+      "version": "1.0.0",
+      "author": {
+        "name": "Anthropic",
+        "email": "support@anthropic.com"
+      },
+      "source": "./plugins/commit-commands",
+      "category": "productivity"
+    },
+    {
+      "name": "explanatory-output-style",
+      "description": "Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)",
+      "version": "1.0.0",
+      "author": {
+        "name": "Dickson Tsai",
+        "email": "dickson@anthropic.com"
+      },
+      "source": "./plugins/explanatory-output-style",
+      "category": "learning"
+    },
+    {
+      "name": "feature-dev",
+      "description": "Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review",
+      "version": "1.0.0",
+      "author": {
+        "name": "Siddharth Bidasaria",
+        "email": "sbidasaria@anthropic.com"
+      },
+      "source": "./plugins/feature-dev",
+      "category": "development"
+    },
+    {
+      "name": "frontend-design",
+      "description": "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.",
+      "version": "1.1.0",
+      "author": {
+        "name": "Prithvi Rajasekaran & Alexander Bricken",
+        "email": "prithvi@anthropic.com"
+      },
+      "source": "./plugins/frontend-design",
+      "category": "development"
+    },
+    {
+      "name": "hookify",
+      "description": "Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Daisy Hollman",
+        "email": "daisy@anthropic.com"
+      },
+      "source": "./plugins/hookify",
+      "category": "productivity"
+    },
+    {
+      "name": "learning-output-style",
+      "description": "Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style)",
+      "version": "1.0.0",
+      "author": {
+        "name": "Boris Cherny",
+        "email": "boris@anthropic.com"
+      },
+      "source": "./plugins/learning-output-style",
+      "category": "learning"
+    },
+    {
+      "name": "plugin-dev",
+      "description": "Comprehensive toolkit for developing Claude Code plugins. Includes 7 expert skills covering hooks, MCP integration, commands, agents, and best practices. AI-assisted plugin creation and validation.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Daisy Hollman",
+        "email": "daisy@anthropic.com"
+      },
+      "source": "./plugins/plugin-dev",
+      "category": "development"
+    },
+    {
+      "name": "pr-review-toolkit",
+      "description": "Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification",
+      "version": "1.0.0",
+      "author": {
+        "name": "Anthropic",
+        "email": "support@anthropic.com"
+      },
+      "source": "./plugins/pr-review-toolkit",
+      "category": "productivity"
+    },
+    {
+      "name": "ralph-wiggum",
+      "description": "Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Daisy Hollman",
+        "email": "daisy@anthropic.com"
+      },
+      "source": "./plugins/ralph-wiggum",
+      "category": "development"
+    },
+    {
+      "name": "security-guidance",
+      "description": "Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns",
+      "version": "1.0.0",
+      "author": {
+        "name": "David Dworken",
+        "email": "dworken@anthropic.com"
+      },
+      "source": "./plugins/security-guidance",
+      "category": "security"
+    }
+  ]
+}

.devcontainer/Dockerfile

@@ -0,0 +1,91 @@
+FROM node:20
+
+ARG TZ
+ENV TZ="$TZ"
+
+ARG CLAUDE_CODE_VERSION=latest
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  less \
+  git \
+  procps \
+  sudo \
+  fzf \
+  zsh \
+  man-db \
+  unzip \
+  gnupg2 \
+  gh \
+  iptables \
+  ipset \
+  iproute2 \
+  dnsutils \
+  aggregate \
+  jq \
+  nano \
+  vim \
+  && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Ensure default node user has access to /usr/local/share
+RUN mkdir -p /usr/local/share/npm-global && \
+  chown -R node:node /usr/local/share
+
+ARG USERNAME=node
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  && mkdir /commandhistory \
+  && touch /commandhistory/.bash_history \
+  && chown -R $USERNAME /commandhistory
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+# Create workspace and config directories and set permissions
+RUN mkdir -p /workspace /home/node/.claude && \
+  chown -R node:node /workspace /home/node/.claude
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) && \
+  wget "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  sudo dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" && \
+  rm "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# Set up non-root user
+USER node
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local/share/npm-global
+ENV PATH=$PATH:/usr/local/share/npm-global/bin
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" -- \
+  -p git \
+  -p fzf \
+  -a "source /usr/share/doc/fzf/examples/key-bindings.zsh" \
+  -a "source /usr/share/doc/fzf/examples/completion.zsh" \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -x
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
+
+
+# Copy and set up firewall script
+COPY init-firewall.sh /usr/local/bin/
+USER root
+RUN chmod +x /usr/local/bin/init-firewall.sh && \
+  echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-firewall && \
+  chmod 0440 /etc/sudoers.d/node-firewall
+USER node

.devcontainer/devcontainer.json

@@ -0,0 +1,57 @@
+{
+  "name": "Claude Code Sandbox",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Los_Angeles}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": [
+    "--cap-add=NET_ADMIN",
+    "--cap-add=NET_RAW"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "node",
+  "mounts": [
+    "source=claude-code-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/node/.claude",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace",
+  "postStartCommand": "sudo /usr/local/bin/init-firewall.sh",
+  "waitFor": "postStartCommand"
+}

.devcontainer/init-firewall.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# 1. Extract Docker DNS info BEFORE any flushing
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# 2. Selectively restore ONLY internal Docker DNS resolution
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+# Allow inbound SSH responses
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Fetch GitHub meta information and aggregate + add their IP ranges
+echo "Fetching GitHub IP ranges..."
+gh_ranges=$(curl -s https://api.github.com/meta)
+if [ -z "$gh_ranges" ]; then
+    echo "ERROR: Failed to fetch GitHub IP ranges"
+    exit 1
+fi
+
+if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then
+    echo "ERROR: GitHub API response missing required fields"
+    exit 1
+fi
+
+echo "Processing GitHub IPs..."
+while read -r cidr; do
+    if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then
+        echo "ERROR: Invalid CIDR range from GitHub meta: $cidr"
+        exit 1
+    fi
+    echo "Adding GitHub range $cidr"
+    ipset add allowed-domains "$cidr"
+done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)
+
+# Resolve and add other allowed domains
+for domain in \
+    "registry.npmjs.org" \
+    "api.anthropic.com" \
+    "sentry.io" \
+    "statsig.com" \
+    "marketplace.visualstudio.com" \
+    "vscode.blob.core.windows.net" \
+    "update.code.visualstudio.com"; do
+    echo "Resolving $domain..."
+    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+    
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip"
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+# Explicitly REJECT all other outbound traffic for immediate feedback
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Verify GitHub API access
+if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.github.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.github.com as expected"
+fi

.gitattributes

@@ -1,35 +1,2 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+*.sh text eol=lf

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "ms-vscode-remote.remote-containers",
+    "eamodio.gitlens"
+  ]
+}

LICENSE.md

@@ -0,0 +1 @@
+© Anthropic PBC. All rights reserved. Use is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms).

README.md

@@ -0,0 +1,84 @@
+---
+license: other
+license_name: anthropic-commercial-terms
+license_link: https://www.anthropic.com/legal/commercial-terms
+tags:
+  - agent
+  - coding-agent
+  - cli
+---
+
+> **This is a source mirror — partial, by necessity.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`anthropics/claude-code`](https://github.com/anthropics/claude-code) GitHub repository. Claude Code's core agent is closed-source and distributed as an npm package; this GitHub repo (and this mirror) contains only the public surrounding material — docs, examples, plugins, and scripts — not the agent engine itself. Licensed under Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), not an open-source license. File issues and contribute on GitHub, not here.
+
+# Claude Code
+
+![](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/@anthropic-ai/claude-code)
+
+[npm]: https://img.shields.io/npm/v/@anthropic-ai/claude-code.svg?style=flat-square
+
+Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows -- all through natural language commands. Use it in your terminal, IDE, or tag @claude on Github.
+
+**Learn more in the [official documentation](https://code.claude.com/docs/en/overview)**.
+
+<img src="./demo.gif" />
+
+## Get started
+> [!NOTE]
+> Installation via npm is deprecated. Use one of the recommended methods below.
+
+For more installation options, uninstall steps, and troubleshooting, see the [setup documentation](https://code.claude.com/docs/en/setup).
+
+1. Install Claude Code:
+
+    **MacOS/Linux (Recommended):**
+    ```bash
+    curl -fsSL https://claude.ai/install.sh | bash
+    ```
+
+    **Homebrew (MacOS/Linux):**
+    ```bash
+    brew install --cask claude-code
+    ```
+
+    **Windows (Recommended):**
+    ```powershell
+    irm https://claude.ai/install.ps1 | iex
+    ```
+
+    **WinGet (Windows):**
+    ```powershell
+    winget install Anthropic.ClaudeCode
+    ```
+
+    **NPM (Deprecated):**
+    ```bash
+    npm install -g @anthropic-ai/claude-code
+    ```
+
+2. Navigate to your project directory and run `claude`.
+
+## Plugins
+
+This repository includes several Claude Code plugins that extend functionality with custom commands and agents. See the [plugins directory](./plugins/README.md) for detailed documentation on available plugins.
+
+## Reporting Bugs
+
+We welcome your feedback. Use the `/bug` command to report issues directly within Claude Code, or file a [GitHub issue](https://github.com/anthropics/claude-code/issues).
+
+## Connect on Discord
+
+Join the [Claude Developers Discord](https://anthropic.com/discord) to connect with other developers using Claude Code. Get help, share feedback, and discuss your projects with the community.
+
+## Data collection, usage, and retention
+
+When you use Claude Code, we collect feedback, which includes usage data (such as code acceptance or rejections), associated conversation data, and user feedback submitted via the `/bug` command.
+
+### How we use your data
+
+See our [data usage policies](https://code.claude.com/docs/en/data-usage).
+
+### Privacy safeguards
+
+We have implemented several safeguards to protect your data, including limited retention periods for sensitive information, restricted access to user session data, and clear policies against using feedback for model training.
+
+For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+Thank you for helping us keep Claude Code secure!
+
+## Reporting Security Issues
+
+The security of our systems and user data is Anthropic's top priority. We appreciate the work of security researchers acting in good faith in identifying and reporting potential vulnerabilities.
+
+Our security program is managed on HackerOne and we ask that any validated vulnerability in this functionality be reported through their [submission form](https://hackerone.com/4f1f16ba-10d3-4d09-9ecc-c721aad90f24/embedded_submissions/new).
+
+## Anthropic Bug Bounty
+
+Our Bug Bounty Program Guidelines are defined on our [HackerOne program page](https://hackerone.com/anthropic).

Script/run_devcontainer_claude_code.ps1

@@ -0,0 +1,152 @@
+<#
+.SYNOPSIS
+    Automates the setup and connection to a DevContainer environment using either Docker or Podman on Windows.
+
+.DESCRIPTION
+    This script automates the process of initializing, starting, and connecting to a DevContainer
+    using either Docker or Podman as the container backend. It must be executed from the root
+    directory of your project and assumes the script is located in a 'Script' subdirectory.
+
+.PARAMETER Backend
+    Specifies the container backend to use. Valid values are 'docker' or 'podman'.
+
+.EXAMPLE
+    .\Script\run_devcontainer_claude_code.ps1 -Backend docker
+    Uses Docker as the container backend.
+
+.EXAMPLE
+    .\Script\run_devcontainer_claude_code.ps1 -Backend podman
+    Uses Podman as the container backend.
+
+.NOTES
+    Project Structure:
+    Project/
+    ├── .devcontainer/
+    └── Script/
+        └── run_devcontainer_claude_code.ps1
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory=$true)]
+    [ValidateSet('docker','podman')]
+    [string]$Backend
+)
+
+# Notify script start
+Write-Host "--- DevContainer Startup & Connection Script ---"
+Write-Host "Using backend: $($Backend)"
+
+# --- Prerequisite Check ---
+Write-Host "Checking for required commands..."
+try {
+    if (-not (Get-Command $Backend -ErrorAction SilentlyContinue)) {
+        throw "Required command '$($Backend)' not found."
+    }
+    Write-Host "- $($Backend) command found."
+    if (-not (Get-Command devcontainer -ErrorAction SilentlyContinue)) {
+        throw "Required command 'devcontainer' not found."
+    }
+    Write-Host "- devcontainer command found."
+}
+catch {
+    Write-Error "A required command is not installed or not in your PATH. $($_.Exception.Message)"
+    Write-Error "Please ensure both '$Backend' and 'devcontainer' are installed and accessible in your system's PATH."
+    exit 1
+}
+
+
+# --- Backend-Specific Initialization ---
+if ($Backend -eq 'podman') {
+    Write-Host "--- Podman Backend Initialization ---"
+
+    # --- Step 1a: Initialize Podman machine ---
+    Write-Host "Initializing Podman machine 'claudeVM'..."
+    try {
+        & podman machine init claudeVM
+        Write-Host "Podman machine 'claudeVM' initialized or already exists."
+    } catch {
+        Write-Error "Failed to initialize Podman machine: $($_.Exception.Message)"
+        exit 1 # Exit script on error
+    }
+
+    # --- Step 1b: Start Podman machine ---
+    Write-Host "Starting Podman machine 'claudeVM'..."
+    try {
+        & podman machine start claudeVM -q
+        Write-Host "Podman machine started or already running."
+    } catch {
+        Write-Error "Failed to start Podman machine: $($_.Exception.Message)"
+        exit 1
+    }
+
+    # --- Step 2: Set default connection ---
+    Write-Host "Setting default Podman connection to 'claudeVM'..."
+    try {
+        & podman system connection default claudeVM
+        Write-Host "Default connection set."
+    } catch {
+        Write-Warning "Failed to set default Podman connection (may be already set or machine issue): $($_.Exception.Message)"
+    }
+
+} elseif ($Backend -eq 'docker') {
+    Write-Host "--- Docker Backend Initialization ---"
+
+    # --- Step 1 & 2: Check Docker Desktop ---
+    Write-Host "Checking if Docker Desktop is running and docker command is available..."
+    try {
+        docker info | Out-Null
+        Write-Host "Docker Desktop (daemon) is running."
+    } catch {
+        Write-Error "Docker Desktop is not running or docker command not found."
+        Write-Error "Please ensure Docker Desktop is running."
+        exit 1
+    }
+}
+
+# --- Step 3: Bring up DevContainer ---
+Write-Host "Bringing up DevContainer in the current folder..."
+try {
+    $arguments = @('up', '--workspace-folder', '.')
+    if ($Backend -eq 'podman') {
+        $arguments += '--docker-path', 'podman'
+    }
+    & devcontainer @arguments
+    Write-Host "DevContainer startup process completed."
+} catch {
+    Write-Error "Failed to bring up DevContainer: $($_.Exception.Message)"
+    exit 1
+}
+
+# --- Step 4: Get DevContainer ID ---
+Write-Host "Finding the DevContainer ID..."
+$currentFolder = (Get-Location).Path
+
+try {
+    $containerId = (& $Backend ps --filter "label=devcontainer.local_folder=$currentFolder" --format '{{.ID}}').Trim()
+} catch {
+    $displayCommand = "$Backend ps --filter `"label=devcontainer.local_folder=$currentFolder`" --format '{{.ID}}'"
+    Write-Error "Failed to get container ID (Command: $displayCommand): $($_.Exception.Message)"
+    exit 1
+}
+
+if (-not $containerId) {
+    Write-Error "Could not find DevContainer ID for the current folder ('$currentFolder')."
+    Write-Error "Please check if 'devcontainer up' was successful and the container is running."
+    exit 1
+}
+Write-Host "Found container ID: $containerId"
+
+# --- Step 5 & 6: Execute command and enter interactive shell inside container ---
+Write-Host "Executing 'claude' command and then starting zsh session inside container $($containerId)..."
+try {
+    & $Backend exec -it $containerId zsh -c 'claude; exec zsh'
+    Write-Host "Interactive session ended."
+} catch {
+    $displayCommand = "$Backend exec -it $containerId zsh -c 'claude; exec zsh'"
+    Write-Error "Failed to execute command inside container (Command: $displayCommand): $($_.Exception.Message)"
+    exit 1
+}
+
+# Notify script completion
+Write-Host "--- Script completed ---"

mods/README.md

@@ -0,0 +1,116 @@
+# Mods
+
+A mod is a Claude Code plugin whose behaviour lives in a hooks module: one
+`register(on, options)` entry that hooks the engine's events as functions
+`($, e, next)`. These three ship inside Claude Code; this folder is their
+source, published as it is built into the binary.
+
+| Mod | What it does | Seated |
+| --- | --- | --- |
+| [`sec-default`](sec-default) | Keeps an organization's classic hooks, prompt content, managed settings and tool policy out of reach of the plugins a person installs; adds no policy of its own. | Outermost, on a machine with managed settings or for a Team or Enterprise organization, unless managed `prependPlugins` says otherwise |
+| [`diff`](diff) | `/diff`: the session's uncommitted changes in a pane beside the transcript, file by file with their hunks, refreshed as Claude edits files and runs commands. | Built in |
+| [`telemetry`](telemetry) | Adds `$.telemetry` (`log`, `mark`) in the `engine.create` fold so a plugin can record an event as a first-party analytics row; sends nothing wherever Claude Code's analytics are off. | Built in |
+
+Each folder is a complete plugin: `.claude-plugin/plugin.json`, a
+`hooks/hooks.json` naming the module, and TypeScript under `hooks/` typed
+against the declarations `/plugin-types` writes (`import type … from
+'claude-code'`), kept here in `types/`. To read one running from source:
+
+    claude --plugin-dir mods/diff
+
+## Testing
+
+A mod's tests are in its `tests/` folder, and run with
+
+    claude plugin test mods/diff
+
+A test gets the engine's own `$` and a plugin's `on`. Each call on `$` is one
+the engine makes, through every hook of the mod loaded as it ships. The hooks
+the test registers with `on` sit beneath the mod, where the rest of the world
+would be, and nothing is beneath them: a call they leave unanswered throws,
+naming its event.
+
+A test file is named for what it covers under `hooks/` (`register.test.ts`
+beside `hooks/register.ts`, `git.test.ts` beside `hooks/git/`), and holds its
+imports, the tier the mod loads in, and one `describe` titled with that name;
+what several tests share sits under `tests/fixtures/`, one export a file.
+
+```ts
+import { describe, expect, mock, test, tier } from 'claude-code/testing'
+
+tier('builtin')
+
+describe('register', () => {
+  test('outside a git repository /diff says so, opens nothing', async ($, on) => {
+    const opened: string[] = []
+    mock.clock(on)
+    on('session.start', ($, e) => ({ cwd: e.cwd }))
+    on('command.register', ($, e) => ({ value: { command: e.name } }))
+    on('process.run', () => ({
+      value: { exitCode: 128, stdout: '', stderr: 'fatal: not a git repository' },
+    }))
+    on('ui.open', ($, e, next) => {
+      opened.push(e.id)
+      return next(e)
+    })
+
+    await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })
+    const { text } = await $.command.run({
+      command: 'diff',
+      args: '',
+      origin: { kind: 'composer' },
+    })
+
+    expect(text).toContain("isn't in a git repository")
+    expect(opened).toEqual([])
+  })
+})
+```
+
+The kit's `mock` answers the world beneath the mod from memory, noun by noun,
+each member a plain function over `on` registering hooks where the test calls
+it: `mock.env(on, variables)` for `$.env`, `mock.store(on, entries)` for
+`$.store`, and `mock.clock(on)` for `$.clock`, whose `advance(ms)` resolves
+every wait the mod asked for (`$.clock.sleep`, `after`, `every`) as the clock
+crosses it. To see what a dispatch does before it answers, start it
+unawaited, `await clock.settle()`, then look: the clock stays where it was.
+`$.ui.press({ plugin, key })` presses a `Button` the test rendered, as a
+click in the terminal does.
+
+`tsc -p mods/tsconfig.json` typechecks every mod's hooks and tests against
+`types/` and each mod's own `types/` contract.
+
+## Composing mods: noun contracts
+
+A mod that adds a noun to `$` in the `engine.create` fold owns that noun's
+types, and keeps them in one place: its `types/index.d.ts`, a declaration
+file with no imports that exports the types the noun is made of, each named
+for the noun, and declares the noun on `EngineInterface` in `claude-code`
+(`telemetry/types/index.d.ts` exports `Telemetry`, `TelemetryLogEntry`,
+`TelemetryMarkEntry` and the rest, and declares `$.telemetry`).
+
+- The contract is the only declaration of the noun. The mod's own hooks
+  import its types from the folder (`import type { Telemetry } from
+  '../types'`), and the value its `engine.create` hook returns is checked
+  against `EngineInterface['telemetry']`, so the implementation cannot drift
+  from what callers read.
+- A mod that calls another's noun reads the same file and never copies it:
+  `mods/tsconfig.json` includes `*/types/**/*.d.ts`, so `$.telemetry.log(…)`
+  in `diff` types against `telemetry`'s contract as it stands, and a helper
+  that must name one of its types imports it from that folder by path.
+- A test of a mod that calls another's noun seats a provider for it, an inline
+  plugin whose `engine.create` hook adds the noun, and answers the calls the
+  way it answers the engine's: `on('telemetry.log', ($, e) => ({ value:
+  undefined }))` runs above the provider's own method, its `e` typed by the
+  contract. With no provider loaded the `$` build refuses the hook, naming the
+  noun nobody provides.
+
+A plugin outside this repository that depends on a mod's noun points its
+tsconfig `include` at that mod's `types/` folder for now; once the engine
+writes the contracts of the plugins a session has installed, `/plugin-types`
+will put them beside `claude-code.d.ts` and the include goes away.
+
+Early access: hooks modules load only where function hooks are enabled, and
+the API these mods are written against may change between releases without
+notice. They are not listed in this repository's marketplace; the copies that
+matter are the ones already in your Claude Code.

mods/diff/README.md

@@ -0,0 +1,91 @@
+# diff
+
+The diff pane as a plugin: `/diff` opens the session's uncommitted changes
+beside the transcript, one row per changed file and every file's hunks
+beneath, and closes it again; each toggle leaves `Diff panel shown` or
+`Diff panel hidden` in the transcript. The header, the file list and its
+toggles stay put while the wheel moves the hunks under them three rows a
+tick, or the list a file a tick while the wheel is over a list longer than
+its eight rows (the plugin answers the pane's `ui.scroll` itself); a row's
+click puts that file's hunks at the top; the list also scrolls under the
+built-in's list keys (`ctrl+up`/`ctrl+down`, `opt+up`/`opt+down`), and
+`ctrl+x b` moves the comparison base on, as the built-in's chord does: both
+through Buttons that declare the engine's own actions. The pane refreshes
+as Claude edits and runs shell commands, and while it is open it polls
+the repository's HEAD so a commit or checkout made elsewhere shows too.
+The first successful edit of a session opens the pane by itself where the
+layout docks it beside the transcript (the fullscreen layout, which each
+drawing's `viewport` says) and the terminal is wide enough (144 columns
+when the person never chose, 110 when they kept it open before; a person
+who closed it is left alone); where the surface does not say, nothing
+opens by itself.
+
+Under the fullscreen layout a terminal under 110 columns gets the
+built-in's line asking for a wider one and nothing opens. Without that
+layout (`CLAUDE_CODE_NO_FLICKER=0`, which `/diff` learns from the command's
+`presentation`) the pane opens inline at any width, focused and as tall
+as its content (the open's `rows`), in the built-in dialog's shape: the
+title, the count, five file rows at a time round the selected one (`❯`,
+where the focus ring starts; the plugin follows the ring's walk through
+`ui.focus` and re-centres the rows as the built-in does), the key hints;
+Enter shows that file's hunks alone,
+Escape backs out to the list and then closes, leaving `Diff dialog
+dismissed`; toasts are held while it is up. A file's ask button arms that
+file: its hunks ride the next prompt as context, once.
+
+The pane compares the working tree against HEAD, split at the session's
+start (the default), against HEAD plainly, or against the merge-base with
+the default branch; the base line under the header names a base other than
+the session's, and the choice is kept per repository in the plugin's store.
+A picker shows one earlier turn's edits instead of the working tree, read
+from the session's messages. Files that changed before the session started
+(by their timestamp, among the paths already dirty when the pane first
+read the repository), and noise (lockfiles, generated and test files), are
+listed apart and folded until asked for; a rename lists as git prints it.
+Outside a git repository `/diff` says so and does nothing else.
+
+Git runs when the built-in panel's would: nothing at the session's start;
+one `git rev-parse`, in the directory the session started in, when `/diff`
+or the first edit a pane has room to open on first needs the repository
+(an answer of no repository is kept too, until `/clear` or `/resume`
+forgets it); and the working tree is read only by a fetch for a pane that
+is open, after an edit that landed or a shell command that ran. The one
+read the built-in has no counterpart for is a `git status` at a pane's
+first fetch, which stands in for the change time the built-in dates a
+moved file by.
+
+`hooks/register.ts` is the module; everything under `hooks/` is its parts.
+
+## What it hooks
+
+| event | what the hook does |
+| --- | --- |
+| `session.start` | Binds the engine once and registers `/diff` (a session where another `/diff` is listed leaves the plugin idle); asks nothing of the repository, which `/diff` or the first edit pins when it comes. |
+| `ui.render` of `PromptHint` | Reads the terminal's width and whether its layout docks a pane, which decide whether the first edit opens the pane. |
+| `ui.render` of `Pane` | Draws the pane: docked, the header, base line, source picker, file list and toggles over the window of hunks; inline, the dialog. |
+| `command.run` of `diff` | Pins the repository when none is, opens or closes the pane (focused and closing on Escape without the fullscreen layout), says which, and remembers the choice. |
+| `ui.close` of the pane | Backs out of the dialog's detail view instead of closing; else remembers the person's close as `/diff`'s. |
+| `ui.scroll` of the pane | Docked, moves the hunks under the pinned header and list (three rows a wheel tick, a page a page key), or the list when the wheel is over it, and keeps the engine's window still. |
+| `ui.focus` in the pane | In the dialog's list, selects the file the ring lands on, re-centres the five rows on it, and lands the ring where that row now sits. |
+| `command.run` of `clear`, `resume` | Closes the pane and forgets the session's state, the pinned repository with it. |
+| `tool.call` of `Edit`, `Write`, `NotebookEdit` | After an edit that landed (not refused, not failed), refreshes an open pane; the session's first such edit opens it, pinning the repository then if the terminal has the room. |
+| `tool.call` of `Bash`, `PowerShell` | After a command that was not refused, failed and interrupted ones too, refreshes an open pane. |
+| `prompt.submit` | Adds the armed file's hunks to the prompt's context and disarms. |
+
+## What it calls on `$`
+
+`clock.after`, `clock.every`, `clock.now`, `command.register`, `fs.list`,
+`fs.read`, `fs.stat`, `process.run` (git, read-only), `session.messages`,
+`store.get`, `store.set`, `telemetry.log`, `telemetry.mark`, `ui.close`,
+`ui.invalidate`, `ui.log`, `ui.open`, `ui.resolve`, `ui.status`.
+
+`$.telemetry` is the telemetry plugin's noun; where it is absent the rows
+are dropped and nothing else changes.
+
+## Try it
+
+```sh
+claude --plugin-dir /path/to/diff
+```
+
+then `/diff` inside a git repository with a modified file.

mods/sec-default/README.md

@@ -0,0 +1,55 @@
+# sec-default
+
+The security default for organizations. Function hooks give every plugin a
+say on every event, in chain order, and the plugins a person installs sit
+in the user tier, beneath the organization's prepend tier and above its
+append tier. Some of what an organization sets today (its classic hooks,
+its managed CLAUDE.md and rules, its settings, its MCP allowlist) was never
+within a person's reach before function hooks; seated outermost, this
+plugin keeps exactly those out of the user tier's reach and adds no policy
+of its own. Everything else passes through untouched.
+
+It has three moves and nothing else: continue past the user tier
+(`next.to(e, "append")`), refuse a user-tier caller by name (`{ deny }`
+when `next.origin.tier` is `user`), or pass (`next(e)`). A subject's
+provenance is the event's pinned `e.provider`; policy is read through
+`$.settings.read({ source: "policy" })`, one read serving a burst; both
+fail closed, so an unreadable policy counts as a policy in force.
+
+`hooks/register.ts` is the module; `hooks/policy/` reads the managed
+settings it decides by.
+
+## The rows
+
+| event | from the outermost seat |
+| --- | --- |
+| `classic.*` | Continue past the user tier: the organization's settings hooks see the engine's input and their answer stands. |
+| `prompt.section`, `prompt.context`, `skill.prompt`, `attribution.text` | Continue past the user tier: managed CLAUDE.md, rules and policy skills reach the model as written. A person's plugins keep `prompt.submit` and its additive context. |
+| `settings.read` | Continue past the user tier: no user hook rewrites what any caller reads as settings, this plugin's own policy reads included. |
+| `tool.describe`, `command.describe`, `agent.offer`, `agent.spawn` | When the subject's pinned `e.provider.tier` is `prepend` or `append` (a policy-installed plugin, the managed folder, a policy MCP server), continue past the user tier; a subject provided by `user`, `builtin` or `core` passes. |
+| `tool.register` | A caller in `prepend` or `append` continues past the user tier. A `user`-tier caller is refused by name while managed settings hold `allowedMcpServers` (set at all, empty included); otherwise it passes. |
+| `tool.list` | The tools of the organization's managed MCP servers are listed as the organization's tiers listed them; every other tool as the user tier left it. With no policy to read, or a refusal from either listing, the organization's listing stands whole. |
+| everything else | Passes: `prompt.submit`, `turn.*`, `tool.call`, `tool.check`, `command.run`, `command.register`, `session.*`, `ui.*`, `fs.*`, `http.fetch`, `process.run`, `store.*`, `clock.*`, `model.*`, `mcp.call`, `audio.*`, `agent.list`, `engine.create`. |
+
+## What it hooks
+
+`classic.*`, `prompt.section`, `prompt.context`, `skill.prompt`,
+`attribution.text`, `settings.read`, `tool.describe`, `command.describe`,
+`agent.offer`, `agent.spawn`, `tool.register`, `tool.list`.
+
+## What it calls on `$`
+
+`settings.read`. It continues to the `append` tier with `next.to`, which
+only a plugin in a managed tier may do.
+
+## Where it is seated
+
+The CLI seats it first in the prepend tier wherever hooks modules load on a
+machine with managed settings or for a Team or Enterprise organization,
+unless managed settings define `prependPlugins`: then that list is the
+whole prepend tier, and the organization names `sec-default@builtin` in it
+at the position it wants, e.g. `"prependPlugins": ["acme-guard@acme-tools",
+"sec-default@builtin"]`, or leaves it out. It is a plugin folder like any
+other, but its one move that matters, `next.to`, is refused outside a
+managed tier, so loading it with `--plugin-dir` seats a plugin that can
+only pass.

mods/telemetry/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "telemetry",
+  "version": "0.1.0",
+  "description": "Plugin analytics: adds $.telemetry in the engine.create fold, so a plugin logs an event or marks a feature's use as one first-party row per call, sent with the session's own credential.",
+  "author": {
+    "name": "Anthropic"
+  },
+  "types": "./types/index.d.ts"
+}

mods/telemetry/README.md

@@ -0,0 +1,54 @@
+# telemetry
+
+Plugin analytics as a plugin: one `engine.create` step adds `$.telemetry` to
+the engine interface every plugin above it is handed, built over the
+`$.session` and `$.http` nouns beneath. `$.telemetry.log({ event, props })`
+sends one event as one first-party row, `tengu_plugin_<event>`;
+`$.telemetry.mark({ feature, kind, reason?, props? })` marks one use of a
+feature as the CLI's own feature events do, `tengu_feature_<kind>` with a
+`feature_name` and the mark's properties beside it. Each call is one POST to
+the event-logging ingest with the session's own credential
+(`$.session.authorize()`, resolved at each call), one attempt, nothing
+batched; a session with no first-party credential, or an ingest that
+refuses, rejects the caller's promise.
+
+It sends nothing wherever the CLI's own analytics are off: under
+`DISABLE_TELEMETRY`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
+`DO_NOT_TRACK`, on any third-party provider (Bedrock, Vertex, Foundry and
+kin), and on a deployment with its own OAuth URL. Each is read through
+`$.env` at every call, rows go one after another, and the credential is
+authorized afresh right before each POST, so a session that has since moved
+to a third-party provider or a cloud gateway sends nothing more. The row's
+`user_type` is `ant` when `USER_TYPE` says so, else `external`.
+
+Nothing free-form reaches a row. An event name and every property key is a
+snake_case token; a value is a finite number, a boolean, or a Choice (a
+string named together with the list it is chosen from), under `log` and
+`mark` alike; `mark` takes `ok`, `sad` or `bad`, with a `reason` required on
+the last two and refused on the first. An entry that breaks a rule is
+refused before anything is sent.
+
+`hooks/register.ts` is the module; `types/index.d.ts` is the noun's contract,
+the one declaration of `$.telemetry` that this mod's hooks, a mod calling the
+noun and a test answering it all read.
+
+## What it hooks
+
+`engine.create`: `{ ...await next(e), telemetry }`, so the noun is added and
+nothing beneath is replaced.
+
+## What it calls on `$`
+
+`session.authorize`, `session.id`, `session.model`, `http.fetch`, `env.get`
+(the switches above and `USER_TYPE`, by literal name), each on the
+interface the fold handed it.
+
+## Where it runs
+
+This plugin is seated by the CLI itself, on internal builds whose own
+analytics are on, and nowhere else: `session.authorize` exists only there,
+and the rows it writes join tables only the CLI's own events reach. It is
+not meant to be installed or loaded with `--plugin-dir`; the folder has a
+manifest so it reads like every other plugin, not so it can stand alone. A
+plugin that calls `$.telemetry` where this one is absent finds no such noun
+and should treat that as "no analytics here".

mods/telemetry/hooks/entries/batch-of.ts

@@ -0,0 +1,34 @@
+import type { Fields } from './fields'
+import type { RowSession } from './row-session'
+
+/**
+ * The first-party event batch for one entry, shaped as the CLI's own
+ * event exporter shapes its batches.
+ *
+ * The ClaudeCodeInternalEvent JSON, one event per batch; the properties ride
+ * as base64 JSON in `additional_metadata`, the field the exporter uses;
+ * `user_type` is what the environment's USER_TYPE says of the build.
+ *
+ * @param fields the entry as checked
+ * @param session the session's id and model, and the build's user type
+ * @returns the batch's JSON text, ready to send to the exporter
+ */
+export function batchOf(fields: Fields, session: RowSession) {
+  const metadata = JSON.stringify(fields.props)
+
+  return JSON.stringify({
+    events: [
+      {
+        event_type: 'ClaudeCodeInternalEvent',
+        event_data: {
+          event_name: fields.name,
+          client_timestamp: new Date().toISOString(),
+          session_id: session.sessionId,
+          model: session.model,
+          user_type: session.userType,
+          additional_metadata: btoa(metadata),
+        },
+      },
+    ],
+  })
+}

mods/telemetry/hooks/entries/checked-fields.ts

@@ -0,0 +1,30 @@
+import { checkedProps } from './checked-props'
+import type { Fields } from './fields'
+import { fieldsOf } from './fields-of'
+import { isRecord } from './is-record'
+import { refusal } from './refusal'
+import { TOKEN } from './token'
+
+/**
+ * The row's fields from one entry, or a refusal naming the first thing
+ * wrong: the entry's shape, the event, then each property in turn.
+ *
+ * Nothing is sent from an entry refused here: the row reaches the ingest as
+ * written, so this check is the gate between the argument and the wire.
+ *
+ * @param entry the event's name and properties as the caller passed them
+ * @returns the entry's checked event name and properties, as `Fields`
+ */
+export function checkedFields(entry: unknown): Fields {
+  if (!isRecord(entry)) {
+    throw refusal('takes one entry, { event, props? }')
+  }
+
+  const { event, props = {} } = entry
+
+  if (typeof event !== 'string' || !TOKEN.test(event)) {
+    throw refusal('takes an event name, a snake_case token')
+  }
+
+  return fieldsOf(event, checkedProps(props, 'log'))
+}

mods/telemetry/hooks/entries/checked-mark.ts

@@ -0,0 +1,55 @@
+import { checkedProps } from './checked-props'
+import type { Fields } from './fields'
+import { isMarkKind } from './is-mark-kind'
+import { isRecord } from './is-record'
+import { markFieldsOf } from './mark-fields-of'
+import { refusal } from './refusal'
+import { TOKEN } from './token'
+
+/**
+ * The row's fields from one mark, or a refusal naming the first thing
+ * wrong: the entry's shape, the feature, the kind, the reason, then props.
+ *
+ * Each property is checked in turn, as a log's are.
+ *
+ * @param entry the feature, kind, reason and properties as the caller passed
+ *   them
+ * @returns the mark's row fields once the entry passes every check
+ */
+export function checkedMark(entry: unknown): Fields {
+  if (!isRecord(entry)) {
+    throw refusal('takes one entry, { feature, kind, reason?, props? }', 'mark')
+  }
+
+  const { feature, kind, reason, props = {} } = entry
+
+  if (typeof feature !== 'string' || !TOKEN.test(feature)) {
+    throw refusal('takes a feature name, a snake_case token', 'mark')
+  }
+
+  if (!isMarkKind(kind)) {
+    throw refusal("kind: 'ok', 'sad' or 'bad'", 'mark')
+  }
+
+  if (kind === 'ok') {
+    if (reason !== undefined) {
+      throw refusal('reason: an ok mark carries none', 'mark')
+    }
+
+    return markFieldsOf({ kind, feature, props: checkedProps(props, 'mark') })
+  }
+
+  if (typeof reason !== 'string' || !TOKEN.test(reason)) {
+    throw refusal(
+      `reason: a ${kind} mark names why, a snake_case token`,
+      'mark',
+    )
+  }
+
+  return markFieldsOf({
+    kind,
+    feature,
+    reason,
+    props: checkedProps(props, 'mark'),
+  })
+}

mods/telemetry/hooks/entries/index.ts

@@ -0,0 +1,25 @@
+export * from './batch-of.js'
+export * from './checked-fields.js'
+export * from './checked-mark.js'
+export * from './checked-props'
+export * from './checked-value'
+export * from './choice-token'
+export * from './choices-limit'
+export * from './core-event-prefix'
+export * from './event-prefix'
+export * from './feature-prefix'
+export * from './fields'
+export * from './fields-of'
+export * from './ingest-url.js'
+export * from './is-mark-kind'
+export * from './is-record'
+export * from './mark'
+export * from './mark-fields-of'
+export * from './mark-kinds'
+export * from './method'
+export * from './prop-limit'
+export * from './refusal'
+export * from './row-session'
+export * from './token'
+
+export * as default from '.'

mods/telemetry/hooks/entries/ingest-url.ts

@@ -0,0 +1,9 @@
+/**
+ * The first-party event-logging ingest: the same address the CLI's own
+ * event exporter posts its batches to.
+ *
+ * No `$` reads the session's API base, so the production host is spelled
+ * here; a session on another base logs nothing, which the authorize gate
+ * already makes so.
+ */
+export const INGEST_URL = 'https://api.anthropic.com/api/event_logging/v2/batch'

mods/telemetry/hooks/environment/environment.ts

@@ -0,0 +1,20 @@
+/**
+ * What the plugin reads of the environment before each row: the
+ * build's user type and every switch that turns the CLI's analytics off.
+ *
+ * Each field is the variable's value as `$.env.get` answers it, undefined
+ * when unset; analytics-off/ decides what they mean together.
+ */
+export type Environment = {
+  readonly userType: string | undefined
+  readonly disableTelemetry: string | undefined
+  readonly disableNonessentialTraffic: string | undefined
+  readonly doNotTrack: string | undefined
+  readonly customOauthUrl: string | undefined
+  readonly useBedrock: string | undefined
+  readonly useVertex: string | undefined
+  readonly useFoundry: string | undefined
+  readonly useAnthropicAws: string | undefined
+  readonly useAnthropicGoogleCloud: string | undefined
+  readonly useMantle: string | undefined
+}

mods/telemetry/hooks/environment/index.ts

@@ -0,0 +1,3 @@
+export type * from './environment.js'
+
+export * as default from '.'

mods/telemetry/hooks/hooks.json

@@ -0,0 +1,4 @@
+{
+  "description": "Plugin analytics: an engine.create step adds $.telemetry (log, mark) over $.session, $.http and $.env beneath; sends nothing wherever the CLI's analytics are off",
+  "modules": ["./register.ts"]
+}

mods/telemetry/hooks/index.ts

@@ -0,0 +1,8 @@
+export * from './entries'
+export * from './environment'
+export * from './is-analytics-off'
+export * from './register.js'
+export * from './telemetry-deps'
+export * from './telemetry-of'
+
+export * as default from '.'

mods/telemetry/hooks/is-analytics-off/index.ts

@@ -0,0 +1,5 @@
+export * from './is-analytics-off.js'
+export * from './is-env-set'
+export * from './is-env-truthy'
+
+export * as default from '.'

mods/telemetry/hooks/is-analytics-off/is-analytics-off.ts

@@ -0,0 +1,34 @@
+import type { Environment } from '../environment'
+import { isEnvSet } from './is-env-set'
+import { isEnvTruthy } from './is-env-truthy'
+
+/**
+ * Whether the CLI's own analytics would be off here, read off the
+ * environment alone: then the plugin sends nothing either.
+ *
+ * Off when DISABLE_TELEMETRY or the nonessential-traffic switch is set at
+ * all or DO_NOT_TRACK is on, on any third-party provider (no first-party
+ * credential rides there), and on a deployment with its own OAuth URL.
+ *
+ * @param environment the variables as read once for the session
+ * @returns true when no row may be sent
+ */
+export function isAnalyticsOff(environment: Environment) {
+  const isPrivate =
+    isEnvSet(environment.disableTelemetry) ||
+    isEnvSet(environment.disableNonessentialTraffic) ||
+    isEnvTruthy(environment.doNotTrack)
+
+  const isThirdParty = [
+    environment.useBedrock,
+    environment.useVertex,
+    environment.useFoundry,
+    environment.useAnthropicAws,
+    environment.useAnthropicGoogleCloud,
+    environment.useMantle,
+  ].some(isEnvTruthy)
+
+  const isCustomDeployment = isEnvSet(environment.customOauthUrl?.trim())
+
+  return isPrivate || isThirdParty || isCustomDeployment
+}

mods/telemetry/hooks/is-analytics-off/is-env-set/is-env-set.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a variable is set to anything at all, as the CLI's privacy level
+ * reads DISABLE_TELEMETRY: any non-empty value counts, `0` included.
+ *
+ * @param value the variable as the environment holds it
+ * @returns true for a non-empty value
+ */
+export const isEnvSet = (value: string | undefined) =>
+  value !== undefined && value !== ''

mods/telemetry/hooks/is-analytics-off/is-env-truthy/index.ts

@@ -0,0 +1,3 @@
+export * from './is-env-truthy.js'
+
+export * as default from '.'

mods/telemetry/hooks/is-analytics-off/is-env-truthy/is-env-truthy.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a variable reads as on, as the CLI reads its boolean switches:
+ * `1`, `true`, `yes` or `on`, in any case, spaces around it ignored.
+ *
+ * @param value the variable as the environment holds it
+ * @returns true for one of the four spellings
+ */
+export const isEnvTruthy = (value: string | undefined) =>
+  ['1', 'true', 'yes', 'on'].includes((value ?? '').trim().toLowerCase())

mods/telemetry/hooks/register.ts

@@ -0,0 +1,44 @@
+import type { EngineInterface, On } from 'claude-code'
+
+import { telemetryOf } from './telemetry-of'
+
+/**
+ * Registers the plugin's one hook: its engine.create step adds
+ * `$.telemetry` over the nouns beneath, the plugin's own `$` as core built.
+ *
+ * `log` runs after the fold, reaching `$.session` and `$.http` through the
+ * nouns beneath; each is one call on them.
+ *
+ * @param on the engine's registrar
+ */
+export function register(on: On) {
+  on('engine.create', async ($, e, next) => {
+    const beneath = await next(e)
+
+    const telemetry: EngineInterface['telemetry'] = telemetryOf({
+      authorize: () => beneath.session.authorize(),
+      id: () => beneath.session.id(),
+      model: () => beneath.session.model(),
+      environment: async () => ({
+        userType: await beneath.env.get('USER_TYPE'),
+        disableTelemetry: await beneath.env.get('DISABLE_TELEMETRY'),
+        disableNonessentialTraffic: await beneath.env.get(
+          'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
+        ),
+        doNotTrack: await beneath.env.get('DO_NOT_TRACK'),
+        customOauthUrl: await beneath.env.get('CLAUDE_CODE_CUSTOM_OAUTH_URL'),
+        useBedrock: await beneath.env.get('CLAUDE_CODE_USE_BEDROCK'),
+        useVertex: await beneath.env.get('CLAUDE_CODE_USE_VERTEX'),
+        useFoundry: await beneath.env.get('CLAUDE_CODE_USE_FOUNDRY'),
+        useAnthropicAws: await beneath.env.get('CLAUDE_CODE_USE_ANTHROPIC_AWS'),
+        useAnthropicGoogleCloud: await beneath.env.get(
+          'CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD',
+        ),
+        useMantle: await beneath.env.get('CLAUDE_CODE_USE_MANTLE'),
+      }),
+      fetch: (url, init) => beneath.http.fetch(url, init),
+    })
+
+    return { ...beneath, telemetry }
+  })
+}

mods/telemetry/hooks/telemetry-deps/index.ts

@@ -0,0 +1,3 @@
+export type * from './telemetry-deps.js'
+
+export * as default from '.'

mods/telemetry/hooks/telemetry-deps/telemetry-deps.ts

@@ -0,0 +1,35 @@
+import type { HttpInit, HttpResponse, SessionAuthorization } from 'claude-code'
+
+import type { Environment } from '../environment'
+
+/**
+ * What `telemetryOf` reaches on the nouns beneath: the session's authorize
+ * and reads, and one fetch. Each is a call on the plugin's own `$`.
+ */
+export type TelemetryDeps = {
+  /**
+   * Resolves the session's held credential, or null.
+   */
+  authorize: () => Promise<SessionAuthorization>
+
+  /**
+   * The session's id, for the row.
+   */
+  id: () => Promise<string>
+
+  /**
+   * The session's model, for the row.
+   */
+  model: () => Promise<string>
+
+  /**
+   * Reads, at each call, what the row and the off switch need of the
+   * environment: the build's user type and every analytics-off variable.
+   */
+  environment: () => Promise<Environment>
+
+  /**
+   * Posts the batch to the ingest with the credential handle.
+   */
+  fetch: (url: string, init: HttpInit) => Promise<HttpResponse>
+}

mods/telemetry/hooks/telemetry-of/index.ts

@@ -0,0 +1,3 @@
+export * from './telemetry-of.js'
+
+export * as default from '.'

mods/telemetry/hooks/telemetry-of/telemetry-of.ts

@@ -0,0 +1,74 @@
+import type { Telemetry } from '../../types'
+import Entries from '../entries'
+import { isAnalyticsOff } from '../is-analytics-off'
+import type { TelemetryDeps } from '../telemetry-deps'
+
+/**
+ * Builds `$.telemetry`: `log` and `mark` check the entry, read the environment
+ * and authorize afresh, build the first-party row and POST it to the ingest.
+ *
+ * One POST per call, rows one after another, nothing kept between them: a
+ * session that has moved to a third-party provider or a gateway, or turned
+ * analytics off, sends nothing more; no credential or a refusal rejects.
+ *
+ * @param deps the calls on the nouns beneath
+ * @returns the `$.telemetry` interface, `log` and `mark`
+ */
+export function telemetryOf(deps: TelemetryDeps): Telemetry {
+  let queue: Promise<unknown> = Promise.resolve()
+
+  async function post(
+    fields: Entries.Fields,
+    method: Entries.Method,
+  ): Promise<void> {
+    const environment = await deps.environment()
+
+    if (isAnalyticsOff(environment)) {
+      return
+    }
+
+    const body = Entries.batchOf(fields, {
+      sessionId: await deps.id(),
+      model: await deps.model(),
+      userType: environment.userType === 'ant' ? 'ant' : 'external',
+    })
+
+    const auth = await deps.authorize()
+
+    if (!auth) {
+      throw Entries.refusal(
+        'this session has no first-party credential to authorize',
+        method,
+      )
+    }
+
+    const response = await deps.fetch(Entries.INGEST_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-service-name': 'claude-code',
+      },
+      auth: auth.handle,
+      body,
+    })
+
+    if (!response.ok) {
+      throw Entries.refusal(`the ingest answered ${response.status}`, method)
+    }
+  }
+
+  function queued(
+    fields: Entries.Fields,
+    method: Entries.Method,
+  ): Promise<void> {
+    const turn = queue.then(() => post(fields, method))
+    queue = turn.catch(() => undefined)
+
+    return turn
+  }
+
+  return {
+    log: async entry => queued(Entries.checkedFields(entry), 'log'),
+    mark: async entry => queued(Entries.checkedMark(entry), 'mark'),
+  }
+}

mods/telemetry/tests/register.test.ts

@@ -0,0 +1,369 @@
+import type { Args } from 'claude-code'
+import { describe, expect, mock, test, tier } from 'claude-code/testing'
+
+import Fixtures from './fixtures'
+
+tier('builtin')
+
+describe('register', () => {
+  test(
+    'a $.telemetry.log call from a plugin posts one first-party row',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, { USER_TYPE: 'ant' })
+
+      const posts = Fixtures.firstPartySession(on)
+
+      expect(
+        await $.command.run(Fixtures.record(Fixtures.surveyAnswer())),
+      ).toEqual({ text: 'sent' })
+
+      expect(
+        posts.map(post => [post.url, post.init?.method, post.init?.auth]),
+      ).toEqual([
+        [
+          'https://api.anthropic.com/api/event_logging/v2/batch',
+          'POST',
+          'the-handle',
+        ],
+      ])
+
+      expect(posts.map(Fixtures.rowOf)).toEqual([
+        {
+          event_type: 'ClaudeCodeInternalEvent',
+          hasTimestamp: true,
+          event_name: 'tengu_plugin_survey_answered',
+          session_id: 'the-session',
+          model: 'the-model',
+          user_type: 'ant',
+          metadata: { answer: 2, page: 'ready', seen: true },
+        },
+      ])
+    },
+  )
+
+  test(
+    'a row already named tengu_ is sent under its own name',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, {})
+
+      const posts = Fixtures.firstPartySession(on)
+
+      await $.command.run(
+        Fixtures.record({
+          ...Fixtures.surveyAnswer(),
+          event: 'tengu_repl_diff_panel_shown',
+        }),
+      )
+
+      expect(posts.map(Fixtures.batchOf)).toMatchObject([
+        {
+          events: [
+            {
+              event_data: {
+                event_name: 'tengu_repl_diff_panel_shown',
+                user_type: 'external',
+              },
+            },
+          ],
+        },
+      ])
+    },
+  )
+
+  test(
+    'nothing is sent where any switch has analytics off',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      let environment: Readonly<Record<string, string>> = {}
+
+      on('env.get', ($, e) => ({ value: environment[e.name] }))
+
+      const posts = Fixtures.firstPartySession(on)
+      const answers: (string | undefined)[] = []
+
+      for (const off of Fixtures.ANALYTICS_OFF_ENVIRONMENTS) {
+        environment = { USER_TYPE: 'ant', ...off }
+
+        answers.push(
+          (await $.command.run(Fixtures.record(Fixtures.surveyAnswer()))).text,
+        )
+      }
+
+      const withheld = posts.length
+
+      environment = { USER_TYPE: 'ant' }
+
+      await $.command.run(Fixtures.record(Fixtures.surveyAnswer()))
+
+      expect(answers).toEqual(
+        Fixtures.ANALYTICS_OFF_ENVIRONMENTS.map(() => 'sent'),
+      )
+
+      expect(withheld, 'nothing posted while any switch was off').toBe(0)
+      expect(posts, 'then one row once every switch is clear').toHaveLength(1)
+    },
+  )
+
+  test(
+    'a third-party provider the host manages sends nothing too',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, {
+        CLAUDE_CODE_USE_BEDROCK: '1',
+        CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST: '1',
+      })
+
+      const posts = Fixtures.firstPartySession(on)
+
+      const { text } = await $.command.run(
+        Fixtures.record(Fixtures.surveyAnswer()),
+      )
+
+      expect({ text, posts }).toEqual({ text: 'sent', posts: [] })
+    },
+  )
+
+  test(
+    'a $.telemetry.mark call posts the feature row by its own name',
+    { plugins: [Fixtures.marking] },
+    async ($, on) => {
+      mock.env(on, { USER_TYPE: 'ant' })
+
+      const posts = Fixtures.firstPartySession(on)
+      const answers: (string | undefined)[] = []
+
+      for (const entry of [
+        { feature: 'learn_page', kind: 'ok' },
+        { feature: 'learn_page', kind: 'sad', reason: 'blocked' },
+        { feature: 'suggest_learning', kind: 'bad', reason: 'api_error' },
+      ]) {
+        answers.push((await $.command.run(Fixtures.mark(entry))).text)
+      }
+
+      expect(answers).toEqual(['sent', 'sent', 'sent'])
+
+      expect(
+        posts.map(Fixtures.rowOf),
+        'the feature events by their own names, no plugin prefix',
+      ).toMatchObject([
+        {
+          event_name: 'tengu_feature_ok',
+          metadata: { feature_name: 'learn_page' },
+        },
+        {
+          event_name: 'tengu_feature_sad',
+          metadata: { feature_name: 'learn_page', error_code: 'blocked' },
+        },
+        {
+          event_name: 'tengu_feature_bad',
+          metadata: {
+            feature_name: 'suggest_learning',
+            error_code: 'api_error',
+          },
+        },
+      ])
+    },
+  )
+
+  test(
+    'a mark with a bad kind or a wrong reason is refused, nothing sent',
+    { plugins: [Fixtures.marking] },
+    async ($, on) => {
+      mock.env(on, { USER_TYPE: 'ant' })
+
+      const posts = Fixtures.firstPartySession(on)
+
+      const refusalFor = async (entry: unknown) =>
+        (await $.command.run(Fixtures.mark(entry))).text
+
+      expect(
+        await refusalFor({ feature: 'learn_page', kind: 'meh' }),
+      ).toEndWith("$.telemetry.mark: kind: 'ok', 'sad' or 'bad'")
+
+      expect(
+        await refusalFor({ feature: 'learn_page', kind: 'bad' }),
+      ).toEndWith(
+        '$.telemetry.mark: reason: a bad mark names why, a snake_case token',
+      )
+
+      expect(
+        await refusalFor({ feature: 'learn_page', kind: 'ok', reason: 'x' }),
+      ).toEndWith('$.telemetry.mark: reason: an ok mark carries none')
+
+      expect(await refusalFor({ feature: 'Learn Page', kind: 'ok' })).toEndWith(
+        '$.telemetry.mark: takes a feature name, a snake_case token',
+      )
+
+      expect(await refusalFor('x')).toEndWith(
+        '$.telemetry.mark: takes one entry, { feature, kind, reason?, props? }',
+      )
+
+      expect(posts).toEqual([])
+    },
+  )
+
+  test(
+    'a session with no first-party credential is refused, nothing sent',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, {})
+
+      const posts = Fixtures.firstPartySession(on, null)
+
+      const { text } = await $.command.run(
+        Fixtures.record(Fixtures.surveyAnswer()),
+      )
+
+      expect(text).toEndWith(
+        '$.telemetry.log: this session has no first-party credential to ' +
+          'authorize',
+      )
+
+      expect(posts).toEqual([])
+    },
+  )
+
+  test(
+    "the ingest's refusal rejects the caller's promise",
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, {})
+
+      const posts = Fixtures.firstPartySession(
+        on,
+        Fixtures.BEARER,
+        Fixtures.REFUSED,
+      )
+
+      const { text } = await $.command.run(
+        Fixtures.record(Fixtures.surveyAnswer()),
+      )
+
+      expect(text).toEndWith('$.telemetry.log: the ingest answered 500')
+      expect(posts).toHaveLength(1)
+    },
+  )
+
+  test(
+    'free text and a malformed entry are refused, nothing sent',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      mock.env(on, {})
+
+      const posts = Fixtures.firstPartySession(on)
+
+      const refusalFor = async (entry: unknown) =>
+        (
+          await $.command.run({
+            ...Fixtures.record(Fixtures.surveyAnswer()),
+            args: JSON.stringify(entry),
+          })
+        ).text
+
+      expect(
+        await refusalFor({ event: 'x', props: { note: 'hello world' } }),
+      ).toEndWith(
+        '$.telemetry.log: props.note: free text is refused; a string is a ' +
+          'Choice, { value, of: [...] }',
+      )
+
+      expect(
+        await refusalFor({
+          event: 'x',
+          props: { page: { value: 'elsewhere', of: ['ready', 'later'] } },
+        }),
+      ).toEndWith(
+        '$.telemetry.log: props.page.value: one of the members of `of`',
+      )
+
+      expect(await refusalFor({ event: 'Survey' })).toEndWith(
+        '$.telemetry.log: takes an event name, a snake_case token',
+      )
+
+      expect(
+        await refusalFor({ event: 'x', props: { 'a path': 1 } }),
+      ).toEndWith('$.telemetry.log: props: every key is a snake_case token')
+
+      expect(await refusalFor('x')).toEndWith(
+        '$.telemetry.log: takes one entry, { event, props? }',
+      )
+
+      expect(posts).toEqual([])
+    },
+  )
+
+  test(
+    'a number that is not finite is refused, nothing sent',
+    {
+      plugins: [
+        {
+          name: 'counting',
+          register(on) {
+            on('command.run', { command: 'count' }, $ =>
+              $.telemetry.log({ event: 'x', props: { n: Number.NaN } }).then(
+                () => ({ text: 'sent' }),
+                (error: unknown) => ({ text: String(error) }),
+              ),
+            )
+          },
+        },
+      ],
+    },
+    async ($, on) => {
+      mock.env(on, {})
+
+      const posts = Fixtures.firstPartySession(on)
+
+      const { text } = await $.command.run({
+        command: 'count',
+        args: '',
+        origin: { kind: 'composer' },
+        presentation: Fixtures.FULLSCREEN,
+      })
+
+      expect(text).toEndWith('$.telemetry.log: props.n: a number is finite')
+      expect(posts).toEqual([])
+    },
+  )
+
+  test(
+    'a failed authorize is not memoized; a retry sends',
+    { plugins: [Fixtures.recording] },
+    async ($, on) => {
+      const posts: Args<'http.fetch'>[] = []
+
+      let authorizations = 0
+
+      mock.env(on, {})
+      on('session.id', () => ({ value: 'the-session' }))
+      on('session.model', () => ({ value: 'the-model' }))
+
+      on('session.authorize', () => {
+        authorizations += 1
+
+        const isFirstAuthorization = authorizations === 1
+
+        return isFirstAuthorization
+          ? { deny: 'transient' }
+          : { value: Fixtures.BEARER }
+      })
+
+      on('http.fetch', ($, e) => {
+        posts.push(e)
+
+        return { value: Fixtures.ACCEPTED }
+      })
+
+      const first = await $.command.run(Fixtures.record({ event: 'x' }))
+      const postsAfterFirst = posts.length
+      const second = await $.command.run(Fixtures.record({ event: 'x' }))
+
+      expect(first.text).toContain('transient')
+      expect(postsAfterFirst).toBe(0)
+      expect(second.text).toBe('sent')
+      expect(posts).toHaveLength(1)
+    },
+  )
+})

mods/telemetry/types/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The `$.telemetry` noun as every caller sees it: the one contract for the
+ * noun, its types exported here and the noun declared on `EngineInterface`.
+ *
+ * The telemetry mod adds the noun in the `engine.create` fold and checks its
+ * return against `EngineInterface['telemetry']`; its hooks import these types
+ * from this folder, a mod that calls the noun and a test that answers it read
+ * them by including it in their tsconfig, and the engine's repository imports
+ * the folder by path. Nothing here is imported, so it stands on its own.
+ */
+
+/**
+ * A plugin's analytics, sent one event at a time through `$.telemetry`.
+ *
+ * Internal builds alone: the telemetry mod adds the noun in the
+ * `engine.create` fold, so a plugin on an external build, or one where the
+ * mod is off, finds no `$.telemetry` and its call throws.
+ */
+export type Telemetry = {
+  /**
+   * Sends one event, `tengu_plugin_<event>`, as one first-party row;
+   * resolves once the ingest accepted it.
+   *
+   * The calling mod names itself in `event`; one already named `tengu_…` is
+   * sent as named. A value is a finite number, a boolean or a
+   * TelemetryChoice; free text is refused. One input, as every op on `$`
+   * takes.
+   *
+   * @param entry the event's name, a snake_case token, and its properties by
+   *   snake_case key
+   * @example
+   * await $.telemetry.log({
+   *   event: "suggest_learning_survey_answered",
+   *   props: {
+   *     answer: 2,
+   *     page: { value: "ready", of: ["ready", "later"] },
+   *   },
+   * })
+   */
+  log: (entry: TelemetryLogEntry) => Promise<void>
+
+  /**
+   * Marks one use of a feature as the CLI's own feature events do, one
+   * `tengu_feature_<kind>` row; resolves once the ingest accepted it.
+   *
+   * The row carries `feature_name`, `error_code` on sad or bad (`reason`,
+   * required there and refused on ok) and the entry's `props`, checked as
+   * `log`'s are; it joins the product-wide feature surface, so no prefix.
+   *
+   * @param entry the feature, how it went, why when not ok, and the row's
+   *   properties by snake_case key
+   * @example
+   * await $.telemetry.mark({ feature: "learn_page", kind: "ok" })
+   * await $.telemetry.mark({
+   *   feature: "learn_page",
+   *   kind: "sad",
+   *   reason: "blocked",
+   * })
+   */
+  mark: (entry: TelemetryMarkEntry) => Promise<void>
+}
+
+/**
+ * What `$.telemetry.log` takes: the event's name after the prefix, and its
+ * properties by snake_case key.
+ */
+export type TelemetryLogEntry = {
+  event: string
+  props?: Readonly<Record<string, TelemetryProp>>
+}
+
+/**
+ * What `$.telemetry.mark` takes: the feature, how it went, why when not
+ * ok, and the properties the row carries beside them by snake_case key.
+ */
+export type TelemetryMarkEntry = {
+  feature: string
+  kind: TelemetryMarkKind
+  reason?: string
+  props?: Readonly<Record<string, TelemetryProp>>
+}
+
+/**
+ * How a feature went, as the CLI's own feature events count it.
+ *
+ * `ok`: used, the person got what they asked. `sad`: degraded, a fallback
+ * or a partial, the person still got something. `bad`: failed, the person
+ * got nothing.
+ */
+export type TelemetryMarkKind = 'ok' | 'sad' | 'bad'
+
+/**
+ * A property's value: a finite number, a boolean, or a TelemetryChoice;
+ * never free text.
+ */
+export type TelemetryProp = number | boolean | TelemetryChoice
+
+/**
+ * A string property: the value and the list it is chosen from, declared
+ * beside it, so no free text reaches the row.
+ *
+ * Every member of `of` is a lowercase token of letters, digits, `_` and
+ * `-`, which may start with a digit, at most 32 of them; `value` is one of
+ * them.
+ */
+export type TelemetryChoice = { value: string; of: readonly string[] }
+
+declare module 'claude-code' {
+  interface EngineInterface {
+    /**
+     * A plugin's analytics, one first-party row per call; present only where
+     * the telemetry mod is seated (internal builds), absent everywhere else.
+     */
+    telemetry: Telemetry
+  }
+}

mods/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "types": [],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment"
+  },
+  "include": ["types", "*/types/**/*.d.ts", "*/hooks", "*/tests"]
+}

plugins/README.md

@@ -0,0 +1,77 @@
+# Claude Code Plugins
+
+This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.
+
+## What are Claude Code Plugins?
+
+Claude Code plugins are extensions that enhance Claude Code with custom slash commands, specialized agents, hooks, and MCP servers. Plugins can be shared across projects and teams, providing consistent tooling and workflows.
+
+Learn more in the [official plugins documentation](https://docs.claude.com/en/docs/claude-code/plugins).
+
+## Plugins in This Directory
+
+| Name | Description | Contents |
+|------|-------------|----------|
+| [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
+| [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
+| [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
+| [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |
+| [explanatory-output-style](./explanatory-output-style/) | Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style) | **Hook:** SessionStart - Injects educational context at the start of each session |
+| [feature-dev](./feature-dev/) | Comprehensive feature development workflow with a structured 7-phase approach | **Command:** `/feature-dev` - Guided feature development workflow<br>**Agents:** `code-explorer`, `code-architect`, `code-reviewer` - For codebase analysis, architecture design, and quality review |
+| [frontend-design](./frontend-design/) | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics | **Skill:** `frontend-design` - Auto-invoked for frontend work, providing guidance on bold design choices, typography, animations, and visual details |
+| [hookify](./hookify/) | Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or explicit instructions | **Commands:** `/hookify`, `/hookify:list`, `/hookify:configure`, `/hookify:help`<br>**Agent:** `conversation-analyzer` - Analyzes conversations for problematic behaviors<br>**Skill:** `writing-rules` - Guidance on hookify rule syntax |
+| [learning-output-style](./learning-output-style/) | Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style) | **Hook:** SessionStart - Encourages users to write meaningful code (5-10 lines) at decision points while receiving educational insights |
+| [plugin-dev](./plugin-dev/) | Comprehensive toolkit for developing Claude Code plugins with 7 expert skills and AI-assisted creation | **Command:** `/plugin-dev:create-plugin` - 8-phase guided workflow for building plugins<br>**Agents:** `agent-creator`, `plugin-validator`, `skill-reviewer`<br>**Skills:** Hook development, MCP integration, plugin structure, settings, commands, agents, and skill development |
+| [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification | **Command:** `/pr-review-toolkit:review-pr` - Run with optional review aspects (comments, tests, errors, types, code, simplify, all)<br>**Agents:** `comment-analyzer`, `pr-test-analyzer`, `silent-failure-hunter`, `type-design-analyzer`, `code-reviewer`, `code-simplifier` |
+| [ralph-wiggum](./ralph-wiggum/) | Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly until completion | **Commands:** `/ralph-loop`, `/cancel-ralph` - Start/stop autonomous iteration loops<br>**Hook:** Stop - Intercepts exit attempts to continue iteration |
+| [security-guidance](./security-guidance/) | Security reminder hook that warns about potential security issues when editing files | **Hook:** PreToolUse - Monitors 9 security patterns including command injection, XSS, eval usage, dangerous HTML, pickle deserialization, and os.system calls |
+
+## Installation
+
+These plugins are included in the Claude Code repository. To use them in your own projects:
+
+1. Install Claude Code globally:
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+2. Navigate to your project and run Claude Code:
+```bash
+claude
+```
+
+3. Use the `/plugin` command to install plugins from marketplaces, or configure them in your project's `.claude/settings.json`.
+
+For detailed plugin installation and configuration, see the [official documentation](https://docs.claude.com/en/docs/claude-code/plugins).
+
+## Plugin Structure
+
+Each plugin follows the standard Claude Code plugin structure:
+
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata
+├── commands/                # Slash commands (optional)
+├── agents/                  # Specialized agents (optional)
+├── skills/                  # Agent Skills (optional)
+├── hooks/                   # Event handlers (optional)
+├── .mcp.json                # External tool configuration (optional)
+└── README.md                # Plugin documentation
+```
+
+## Contributing
+
+When adding new plugins to this directory:
+
+1. Follow the standard plugin structure
+2. Include a comprehensive README.md
+3. Add plugin metadata in `.claude-plugin/plugin.json`
+4. Document all commands and agents
+5. Provide usage examples
+
+## Learn More
+
+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview)
+- [Plugin System Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
+- [Agent SDK Documentation](https://docs.claude.com/en/api/agent-sdk/overview)

scripts/auto-close-duplicates.ts

@@ -0,0 +1,277 @@
+#!/usr/bin/env bun
+
+declare global {
+  var process: {
+    env: Record<string, string | undefined>;
+  };
+}
+
+interface GitHubIssue {
+  number: number;
+  title: string;
+  user: { id: number };
+  created_at: string;
+}
+
+interface GitHubComment {
+  id: number;
+  body: string;
+  created_at: string;
+  user: { type: string; id: number };
+}
+
+interface GitHubReaction {
+  user: { id: number };
+  content: string;
+}
+
+async function githubRequest<T>(endpoint: string, token: string, method: string = 'GET', body?: any): Promise<T> {
+  const response = await fetch(`https://api.github.com${endpoint}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "auto-close-duplicates-script",
+      ...(body && { "Content-Type": "application/json" }),
+    },
+    ...(body && { body: JSON.stringify(body) }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `GitHub API request failed: ${response.status} ${response.statusText}`
+    );
+  }
+
+  return response.json();
+}
+
+function extractDuplicateIssueNumber(commentBody: string): number | null {
+  // Try to match #123 format first
+  let match = commentBody.match(/#(\d+)/);
+  if (match) {
+    return parseInt(match[1], 10);
+  }
+  
+  // Try to match GitHub issue URL format: https://github.com/owner/repo/issues/123
+  match = commentBody.match(/github\.com\/[^\/]+\/[^\/]+\/issues\/(\d+)/);
+  if (match) {
+    return parseInt(match[1], 10);
+  }
+  
+  return null;
+}
+
+
+async function closeIssueAsDuplicate(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  duplicateOfNumber: number,
+  token: string
+): Promise<void> {
+  await githubRequest(
+    `/repos/${owner}/${repo}/issues/${issueNumber}`,
+    token,
+    'PATCH',
+    {
+      state: 'closed',
+      state_reason: 'duplicate',
+      labels: ['duplicate']
+    }
+  );
+
+  await githubRequest(
+    `/repos/${owner}/${repo}/issues/${issueNumber}/comments`,
+    token,
+    'POST',
+    {
+      body: `This issue has been automatically closed as a duplicate of #${duplicateOfNumber}.
+
+If this is incorrect, please re-open this issue or create a new one.
+
+🤖 Generated with [Claude Code](https://claude.ai/code)`
+    }
+  );
+
+}
+
+async function autoCloseDuplicates(): Promise<void> {
+  console.log("[DEBUG] Starting auto-close duplicates script");
+
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error("GITHUB_TOKEN environment variable is required");
+  }
+  console.log("[DEBUG] GitHub token found");
+
+  const owner = process.env.GITHUB_REPOSITORY_OWNER || "anthropics";
+  const repo = process.env.GITHUB_REPOSITORY_NAME || "claude-code";
+  console.log(`[DEBUG] Repository: ${owner}/${repo}`);
+
+  const threeDaysAgo = new Date();
+  threeDaysAgo.setDate(threeDaysAgo.getDate() - 3);
+  console.log(
+    `[DEBUG] Checking for duplicate comments older than: ${threeDaysAgo.toISOString()}`
+  );
+
+  console.log("[DEBUG] Fetching open issues created more than 3 days ago...");
+  const allIssues: GitHubIssue[] = [];
+  let page = 1;
+  const perPage = 100;
+  
+  while (true) {
+    const pageIssues: GitHubIssue[] = await githubRequest(
+      `/repos/${owner}/${repo}/issues?state=open&per_page=${perPage}&page=${page}`,
+      token
+    );
+    
+    if (pageIssues.length === 0) break;
+    
+    // Filter for issues created more than 3 days ago
+    const oldEnoughIssues = pageIssues.filter(issue => 
+      new Date(issue.created_at) <= threeDaysAgo
+    );
+    
+    allIssues.push(...oldEnoughIssues);
+    page++;
+    
+    // Safety limit to avoid infinite loops
+    if (page > 20) break;
+  }
+  
+  const issues = allIssues;
+  console.log(`[DEBUG] Found ${issues.length} open issues`);
+
+  let processedCount = 0;
+  let candidateCount = 0;
+
+  for (const issue of issues) {
+    processedCount++;
+    console.log(
+      `[DEBUG] Processing issue #${issue.number} (${processedCount}/${issues.length}): ${issue.title}`
+    );
+
+    console.log(`[DEBUG] Fetching comments for issue #${issue.number}...`);
+    const comments: GitHubComment[] = await githubRequest(
+      `/repos/${owner}/${repo}/issues/${issue.number}/comments`,
+      token
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} has ${comments.length} comments`
+    );
+
+    const dupeComments = comments.filter(
+      (comment) =>
+        comment.body.includes("Found") &&
+        comment.body.includes("possible duplicate") &&
+        comment.user.type === "Bot"
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} has ${dupeComments.length} duplicate detection comments`
+    );
+
+    if (dupeComments.length === 0) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} - no duplicate comments found, skipping`
+      );
+      continue;
+    }
+
+    const lastDupeComment = dupeComments[dupeComments.length - 1];
+    const dupeCommentDate = new Date(lastDupeComment.created_at);
+    console.log(
+      `[DEBUG] Issue #${
+        issue.number
+      } - most recent duplicate comment from: ${dupeCommentDate.toISOString()}`
+    );
+
+    if (dupeCommentDate > threeDaysAgo) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} - duplicate comment is too recent, skipping`
+      );
+      continue;
+    }
+    console.log(
+      `[DEBUG] Issue #${
+        issue.number
+      } - duplicate comment is old enough (${Math.floor(
+        (Date.now() - dupeCommentDate.getTime()) / (1000 * 60 * 60 * 24)
+      )} days)`
+    );
+
+    const commentsAfterDupe = comments.filter(
+      (comment) => new Date(comment.created_at) > dupeCommentDate
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} - ${commentsAfterDupe.length} comments after duplicate detection`
+    );
+
+    if (commentsAfterDupe.length > 0) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} - has activity after duplicate comment, skipping`
+      );
+      continue;
+    }
+
+    console.log(
+      `[DEBUG] Issue #${issue.number} - checking reactions on duplicate comment...`
+    );
+    const reactions: GitHubReaction[] = await githubRequest(
+      `/repos/${owner}/${repo}/issues/comments/${lastDupeComment.id}/reactions`,
+      token
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} - duplicate comment has ${reactions.length} reactions`
+    );
+
+    const authorThumbsDown = reactions.some(
+      (reaction) =>
+        reaction.user.id === issue.user.id && reaction.content === "-1"
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} - author thumbs down reaction: ${authorThumbsDown}`
+    );
+
+    if (authorThumbsDown) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} - author disagreed with duplicate detection, skipping`
+      );
+      continue;
+    }
+
+    const duplicateIssueNumber = extractDuplicateIssueNumber(lastDupeComment.body);
+    if (!duplicateIssueNumber) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} - could not extract duplicate issue number from comment, skipping`
+      );
+      continue;
+    }
+
+    candidateCount++;
+    const issueUrl = `https://github.com/${owner}/${repo}/issues/${issue.number}`;
+    
+    try {
+      console.log(
+        `[INFO] Auto-closing issue #${issue.number} as duplicate of #${duplicateIssueNumber}: ${issueUrl}`
+      );
+      await closeIssueAsDuplicate(owner, repo, issue.number, duplicateIssueNumber, token);
+      console.log(
+        `[SUCCESS] Successfully closed issue #${issue.number} as duplicate of #${duplicateIssueNumber}`
+      );
+    } catch (error) {
+      console.error(
+        `[ERROR] Failed to close issue #${issue.number} as duplicate: ${error}`
+      );
+    }
+  }
+
+  console.log(
+    `[DEBUG] Script completed. Processed ${processedCount} issues, found ${candidateCount} candidates for auto-close`
+  );
+}
+
+autoCloseDuplicates().catch(console.error);
+
+// Make it a module
+export {};

scripts/backfill-duplicate-comments.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env bun
+
+declare global {
+  var process: {
+    env: Record<string, string | undefined>;
+  };
+}
+
+interface GitHubIssue {
+  number: number;
+  title: string;
+  state: string;
+  state_reason?: string;
+  user: { id: number };
+  created_at: string;
+  closed_at?: string;
+}
+
+interface GitHubComment {
+  id: number;
+  body: string;
+  created_at: string;
+  user: { type: string; id: number };
+}
+
+async function githubRequest<T>(endpoint: string, token: string, method: string = 'GET', body?: any): Promise<T> {
+  const response = await fetch(`https://api.github.com${endpoint}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "backfill-duplicate-comments-script",
+      ...(body && { "Content-Type": "application/json" }),
+    },
+    ...(body && { body: JSON.stringify(body) }),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `GitHub API request failed: ${response.status} ${response.statusText}`
+    );
+  }
+
+  return response.json();
+}
+
+async function triggerDedupeWorkflow(
+  owner: string,
+  repo: string,
+  issueNumber: number,
+  token: string,
+  dryRun: boolean = true
+): Promise<void> {
+  if (dryRun) {
+    console.log(`[DRY RUN] Would trigger dedupe workflow for issue #${issueNumber}`);
+    return;
+  }
+
+  await githubRequest(
+    `/repos/${owner}/${repo}/actions/workflows/claude-dedupe-issues.yml/dispatches`,
+    token,
+    'POST',
+    {
+      ref: 'main',
+      inputs: {
+        issue_number: issueNumber.toString()
+      }
+    }
+  );
+}
+
+async function backfillDuplicateComments(): Promise<void> {
+  console.log("[DEBUG] Starting backfill duplicate comments script");
+
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error(`GITHUB_TOKEN environment variable is required
+
+Usage:
+  GITHUB_TOKEN=your_token bun run scripts/backfill-duplicate-comments.ts
+
+Environment Variables:
+  GITHUB_TOKEN - GitHub personal access token with repo and actions permissions (required)
+  DRY_RUN - Set to "false" to actually trigger workflows (default: true for safety)
+  MAX_ISSUE_NUMBER - Only process issues with numbers less than this value (default: 4050)`);
+  }
+  console.log("[DEBUG] GitHub token found");
+
+  const owner = "anthropics";
+  const repo = "claude-code";
+  const dryRun = process.env.DRY_RUN !== "false";
+  const maxIssueNumber = parseInt(process.env.MAX_ISSUE_NUMBER || "4050", 10);
+  const minIssueNumber = parseInt(process.env.MIN_ISSUE_NUMBER || "1", 10);
+  
+  console.log(`[DEBUG] Repository: ${owner}/${repo}`);
+  console.log(`[DEBUG] Dry run mode: ${dryRun}`);
+  console.log(`[DEBUG] Looking at issues between #${minIssueNumber} and #${maxIssueNumber}`);
+
+  console.log(`[DEBUG] Fetching issues between #${minIssueNumber} and #${maxIssueNumber}...`);
+  const allIssues: GitHubIssue[] = [];
+  let page = 1;
+  const perPage = 100;
+  
+  while (true) {
+    const pageIssues: GitHubIssue[] = await githubRequest(
+      `/repos/${owner}/${repo}/issues?state=all&per_page=${perPage}&page=${page}&sort=created&direction=desc`,
+      token
+    );
+    
+    if (pageIssues.length === 0) break;
+    
+    // Filter to only include issues within the specified range
+    const filteredIssues = pageIssues.filter(issue => 
+      issue.number >= minIssueNumber && issue.number < maxIssueNumber
+    );
+    allIssues.push(...filteredIssues);
+    
+    // If the oldest issue in this page is still above our minimum, we need to continue
+    // but if the oldest issue is below our minimum, we can stop
+    const oldestIssueInPage = pageIssues[pageIssues.length - 1];
+    if (oldestIssueInPage && oldestIssueInPage.number >= maxIssueNumber) {
+      console.log(`[DEBUG] Oldest issue in page #${page} is #${oldestIssueInPage.number}, continuing...`);
+    } else if (oldestIssueInPage && oldestIssueInPage.number < minIssueNumber) {
+      console.log(`[DEBUG] Oldest issue in page #${page} is #${oldestIssueInPage.number}, below minimum, stopping`);
+      break;
+    } else if (filteredIssues.length === 0 && pageIssues.length > 0) {
+      console.log(`[DEBUG] No issues in page #${page} are in range #${minIssueNumber}-#${maxIssueNumber}, continuing...`);
+    }
+    
+    page++;
+    
+    // Safety limit to avoid infinite loops
+    if (page > 200) {
+      console.log("[DEBUG] Reached page limit, stopping pagination");
+      break;
+    }
+  }
+  
+  console.log(`[DEBUG] Found ${allIssues.length} issues between #${minIssueNumber} and #${maxIssueNumber}`);
+
+  let processedCount = 0;
+  let candidateCount = 0;
+  let triggeredCount = 0;
+
+  for (const issue of allIssues) {
+    processedCount++;
+    console.log(
+      `[DEBUG] Processing issue #${issue.number} (${processedCount}/${allIssues.length}): ${issue.title}`
+    );
+
+    console.log(`[DEBUG] Fetching comments for issue #${issue.number}...`);
+    const comments: GitHubComment[] = await githubRequest(
+      `/repos/${owner}/${repo}/issues/${issue.number}/comments`,
+      token
+    );
+    console.log(
+      `[DEBUG] Issue #${issue.number} has ${comments.length} comments`
+    );
+
+    // Look for existing duplicate detection comments (from the dedupe bot)
+    const dupeDetectionComments = comments.filter(
+      (comment) =>
+        comment.body.includes("Found") &&
+        comment.body.includes("possible duplicate") &&
+        comment.user.type === "Bot"
+    );
+
+    console.log(
+      `[DEBUG] Issue #${issue.number} has ${dupeDetectionComments.length} duplicate detection comments`
+    );
+
+    // Skip if there's already a duplicate detection comment
+    if (dupeDetectionComments.length > 0) {
+      console.log(
+        `[DEBUG] Issue #${issue.number} already has duplicate detection comment, skipping`
+      );
+      continue;
+    }
+
+    candidateCount++;
+    const issueUrl = `https://github.com/${owner}/${repo}/issues/${issue.number}`;
+    
+    try {
+      console.log(
+        `[INFO] ${dryRun ? '[DRY RUN] ' : ''}Triggering dedupe workflow for issue #${issue.number}: ${issueUrl}`
+      );
+      await triggerDedupeWorkflow(owner, repo, issue.number, token, dryRun);
+      
+      if (!dryRun) {
+        console.log(
+          `[SUCCESS] Successfully triggered dedupe workflow for issue #${issue.number}`
+        );
+      }
+      triggeredCount++;
+    } catch (error) {
+      console.error(
+        `[ERROR] Failed to trigger workflow for issue #${issue.number}: ${error}`
+      );
+    }
+
+    // Add a delay between workflow triggers to avoid overwhelming the system
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  console.log(
+    `[DEBUG] Script completed. Processed ${processedCount} issues, found ${candidateCount} candidates without duplicate comments, ${dryRun ? 'would trigger' : 'triggered'} ${triggeredCount} workflows`
+  );
+}
+
+backfillDuplicateComments().catch(console.error);
+
+// Make it a module
+export {};

scripts/comment-on-duplicates.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+#
+# Comments on a GitHub issue with a list of potential duplicates.
+# Usage: ./comment-on-duplicates.sh --potential-duplicates 456 789 101
+#
+# The base issue number is read from the workflow event payload.
+#
+
+set -euo pipefail
+
+REPO="anthropics/claude-code"
+
+# Read from event payload so the issue number is bound to the triggering event.
+# Falls back to workflow_dispatch inputs for manual runs.
+BASE_ISSUE=$(jq -r '.issue.number // .inputs.issue_number // empty' "${GITHUB_EVENT_PATH:?GITHUB_EVENT_PATH not set}")
+if ! [[ "$BASE_ISSUE" =~ ^[0-9]+$ ]]; then
+  echo "Error: no issue number in event payload" >&2
+  exit 1
+fi
+
+DUPLICATES=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --potential-duplicates)
+      shift
+      while [[ $# -gt 0 && ! "$1" =~ ^-- ]]; do
+        DUPLICATES+=("$1")
+        shift
+      done
+      ;;
+    *)
+      echo "Error: unknown argument (only --potential-duplicates is accepted)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate duplicates
+if [[ ${#DUPLICATES[@]} -eq 0 ]]; then
+  echo "Error: --potential-duplicates requires at least one issue number" >&2
+  exit 1
+fi
+
+if [[ ${#DUPLICATES[@]} -gt 3 ]]; then
+  echo "Error: --potential-duplicates accepts at most 3 issues" >&2
+  exit 1
+fi
+
+for dup in "${DUPLICATES[@]}"; do
+  if ! [[ "$dup" =~ ^[0-9]+$ ]]; then
+    echo "Error: duplicate issue must be a number, got: $dup" >&2
+    exit 1
+  fi
+done
+
+# Validate that base issue exists
+if ! gh issue view "$BASE_ISSUE" --repo "$REPO" &>/dev/null; then
+  echo "Error: issue #$BASE_ISSUE does not exist in $REPO" >&2
+  exit 1
+fi
+
+# Validate that all duplicate issues exist
+for dup in "${DUPLICATES[@]}"; do
+  if ! gh issue view "$dup" --repo "$REPO" &>/dev/null; then
+    echo "Error: issue #$dup does not exist in $REPO" >&2
+    exit 1
+  fi
+done
+
+# Build comment body
+COUNT=${#DUPLICATES[@]}
+if [[ $COUNT -eq 1 ]]; then
+  HEADER="Found 1 possible duplicate issue:"
+else
+  HEADER="Found $COUNT possible duplicate issues:"
+fi
+
+BODY="$HEADER"$'\n\n'
+INDEX=1
+for dup in "${DUPLICATES[@]}"; do
+  BODY+="$INDEX. https://github.com/$REPO/issues/$dup"$'\n'
+  ((INDEX++))
+done
+
+BODY+=$'\n'"This issue will be automatically closed as a duplicate in 3 days."$'\n\n'
+BODY+="- If your issue is a duplicate, please close it and 👍 the existing issue instead"$'\n'
+BODY+="- To prevent auto-closure, add a comment or 👎 this comment"$'\n\n'
+BODY+="🤖 Generated with [Claude Code](https://claude.ai/code)"
+
+# Post the comment
+gh issue comment "$BASE_ISSUE" --repo "$REPO" --body "$BODY"
+
+echo "Posted duplicate comment on issue #$BASE_ISSUE"

scripts/edit-issue-labels.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# Edits labels on a GitHub issue.
+# Usage: ./edit-issue-labels.sh --add-label bug --add-label needs-triage --remove-label untriaged
+#
+# The issue number is read from the workflow event payload.
+#
+
+set -euo pipefail
+
+# Read from event payload so the issue number is bound to the triggering event.
+# Falls back to workflow_dispatch inputs for manual runs.
+ISSUE=$(jq -r '.issue.number // .inputs.issue_number // empty' "${GITHUB_EVENT_PATH:?GITHUB_EVENT_PATH not set}")
+if ! [[ "$ISSUE" =~ ^[0-9]+$ ]]; then
+  echo "Error: no issue number in event payload" >&2
+  exit 1
+fi
+
+ADD_LABELS=()
+REMOVE_LABELS=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --add-label)
+      ADD_LABELS+=("$2")
+      shift 2
+      ;;
+    --remove-label)
+      REMOVE_LABELS+=("$2")
+      shift 2
+      ;;
+    *)
+      echo "Error: unknown argument (only --add-label and --remove-label are accepted)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ${#ADD_LABELS[@]} -eq 0 && ${#REMOVE_LABELS[@]} -eq 0 ]]; then
+  exit 1
+fi
+
+# Fetch valid labels from the repo
+VALID_LABELS=$(gh label list --limit 500 --json name --jq '.[].name')
+
+# Filter to only labels that exist in the repo
+FILTERED_ADD=()
+for label in "${ADD_LABELS[@]}"; do
+  if echo "$VALID_LABELS" | grep -qxF "$label"; then
+    FILTERED_ADD+=("$label")
+  fi
+done
+
+FILTERED_REMOVE=()
+for label in "${REMOVE_LABELS[@]}"; do
+  if echo "$VALID_LABELS" | grep -qxF "$label"; then
+    FILTERED_REMOVE+=("$label")
+  fi
+done
+
+if [[ ${#FILTERED_ADD[@]} -eq 0 && ${#FILTERED_REMOVE[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# Build gh command arguments
+GH_ARGS=("issue" "edit" "$ISSUE")
+
+for label in "${FILTERED_ADD[@]}"; do
+  GH_ARGS+=("--add-label" "$label")
+done
+
+for label in "${FILTERED_REMOVE[@]}"; do
+  GH_ARGS+=("--remove-label" "$label")
+done
+
+gh "${GH_ARGS[@]}"
+
+if [[ ${#FILTERED_ADD[@]} -gt 0 ]]; then
+  echo "Added: ${FILTERED_ADD[*]}"
+fi
+if [[ ${#FILTERED_REMOVE[@]} -gt 0 ]]; then
+  echo "Removed: ${FILTERED_REMOVE[*]}"
+fi

scripts/gh.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Wrapper around gh CLI that only allows specific subcommands and flags.
+# All commands are scoped to the current repository via GH_REPO or GITHUB_REPOSITORY.
+#
+# Usage:
+#   ./scripts/gh.sh issue view 123
+#   ./scripts/gh.sh issue view 123 --comments
+#   ./scripts/gh.sh issue list --state open --limit 20
+#   ./scripts/gh.sh search issues "search query" --limit 10
+#   ./scripts/gh.sh label list --limit 100
+
+export GH_HOST=github.com
+
+REPO="${GH_REPO:-${GITHUB_REPOSITORY:-}}"
+if [[ -z "$REPO" || "$REPO" == */*/* || "$REPO" != */* ]]; then
+  echo "Error: GH_REPO or GITHUB_REPOSITORY must be set to owner/repo format (e.g., GITHUB_REPOSITORY=anthropics/claude-code)" >&2
+  exit 1
+fi
+export GH_REPO="$REPO"
+
+ALLOWED_FLAGS=(--comments --state --limit --label)
+FLAGS_WITH_VALUES=(--state --limit --label)
+
+SUB1="${1:-}"
+SUB2="${2:-}"
+CMD="$SUB1 $SUB2"
+case "$CMD" in
+  "issue view"|"issue list"|"search issues"|"label list")
+    ;;
+  *)
+    echo "Error: only 'issue view', 'issue list', 'search issues', 'label list' are allowed (e.g., ./scripts/gh.sh issue view 123)" >&2
+    exit 1
+    ;;
+esac
+
+shift 2
+
+# Separate flags from positional arguments
+POSITIONAL=()
+FLAGS=()
+skip_next=false
+for arg in "$@"; do
+  if [[ "$skip_next" == true ]]; then
+    FLAGS+=("$arg")
+    skip_next=false
+  elif [[ "$arg" == -* ]]; then
+    flag="${arg%%=*}"
+    matched=false
+    for allowed in "${ALLOWED_FLAGS[@]}"; do
+      if [[ "$flag" == "$allowed" ]]; then
+        matched=true
+        break
+      fi
+    done
+    if [[ "$matched" == false ]]; then
+      echo "Error: only --comments, --state, --limit, --label flags are allowed (e.g., ./scripts/gh.sh issue list --state open --limit 20)" >&2
+      exit 1
+    fi
+    FLAGS+=("$arg")
+    # If flag expects a value and isn't using = syntax, skip next arg
+    if [[ "$arg" != *=* ]]; then
+      for vflag in "${FLAGS_WITH_VALUES[@]}"; do
+        if [[ "$flag" == "$vflag" ]]; then
+          skip_next=true
+          break
+        fi
+      done
+    fi
+  else
+    POSITIONAL+=("$arg")
+  fi
+done
+
+if [[ "$CMD" == "search issues" ]]; then
+  QUERY="${POSITIONAL[0]:-}"
+  QUERY_LOWER=$(echo "$QUERY" | tr '[:upper:]' '[:lower:]')
+  if [[ "$QUERY_LOWER" == *"repo:"* || "$QUERY_LOWER" == *"org:"* || "$QUERY_LOWER" == *"user:"* ]]; then
+    echo "Error: search query must not contain repo:, org:, or user: qualifiers (e.g., ./scripts/gh.sh search issues \"bug report\" --limit 10)" >&2
+    exit 1
+  fi
+  gh "$SUB1" "$SUB2" "$QUERY" --repo "$REPO" "${FLAGS[@]}"
+elif [[ "$CMD" == "issue view" ]]; then
+  if [[ ${#POSITIONAL[@]} -ne 1 ]] || ! [[ "${POSITIONAL[0]}" =~ ^[0-9]+$ ]]; then
+    echo "Error: issue view requires exactly one numeric issue number (e.g., ./scripts/gh.sh issue view 123)" >&2
+    exit 1
+  fi
+  gh "$SUB1" "$SUB2" "${POSITIONAL[0]}" "${FLAGS[@]}"
+else
+  if [[ ${#POSITIONAL[@]} -ne 0 ]]; then
+    echo "Error: issue list and label list do not accept positional arguments (e.g., ./scripts/gh.sh issue list --state open, ./scripts/gh.sh label list --limit 100)" >&2
+    exit 1
+  fi
+  gh "$SUB1" "$SUB2" "${FLAGS[@]}"
+fi

scripts/issue-lifecycle.ts

@@ -0,0 +1,38 @@
+// Single source of truth for issue lifecycle labels, timeouts, and messages.
+
+export const lifecycle = [
+  {
+    label: "invalid",
+    days: 3,
+    reason: "this doesn't appear to be about Claude Code",
+    nudge: "This doesn't appear to be about [Claude Code](https://github.com/anthropics/claude-code). For general Anthropic support, visit [support.anthropic.com](https://support.anthropic.com).",
+  },
+  {
+    label: "needs-repro",
+    days: 7,
+    reason: "we still need reproduction steps to investigate",
+    nudge: "We weren't able to reproduce this. Could you provide steps to trigger the issue — what you ran, what happened, and what you expected?",
+  },
+  {
+    label: "needs-info",
+    days: 7,
+    reason: "we still need a bit more information to move forward",
+    nudge: "We need more information to continue investigating. Can you make sure to include your Claude Code version (`claude --version`), OS, and any error messages or logs?",
+  },
+  {
+    label: "stale",
+    days: 14,
+    reason: "inactive for too long",
+    nudge: "This issue has been automatically marked as stale due to inactivity.",
+  },
+  {
+    label: "autoclose",
+    days: 14,
+    reason: "inactive for too long",
+    nudge: "This issue has been marked for automatic closure.",
+  },
+] as const;
+
+export type LifecycleLabel = (typeof lifecycle)[number]["label"];
+
+export const STALE_UPVOTE_THRESHOLD = 10;

scripts/lifecycle-comment.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+
+// Posts a comment when a lifecycle label is applied to an issue,
+// giving the author a heads-up and a chance to respond before auto-close.
+
+import { lifecycle } from "./issue-lifecycle.ts";
+
+const DRY_RUN = process.argv.includes("--dry-run");
+const token = process.env.GITHUB_TOKEN;
+const repo = process.env.GITHUB_REPOSITORY; // owner/repo
+const label = process.env.LABEL;
+const issueNumber = process.env.ISSUE_NUMBER;
+
+if (!DRY_RUN && !token) throw new Error("GITHUB_TOKEN required");
+if (!repo) throw new Error("GITHUB_REPOSITORY required");
+if (!label) throw new Error("LABEL required");
+if (!issueNumber) throw new Error("ISSUE_NUMBER required");
+
+const entry = lifecycle.find((l) => l.label === label);
+if (!entry) {
+  console.log(`No lifecycle entry for label "${label}", skipping`);
+  process.exit(0);
+}
+
+const body = `${entry.nudge} This issue will be closed automatically if there's no activity within ${entry.days} days.`;
+
+// --
+
+if (DRY_RUN) {
+  console.log(`Would comment on #${issueNumber} for label "${label}":\n\n${body}`);
+  process.exit(0);
+}
+
+const response = await fetch(
+  `https://api.github.com/repos/${repo}/issues/${issueNumber}/comments`,
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github.v3+json",
+      "Content-Type": "application/json",
+      "User-Agent": "lifecycle-comment",
+    },
+    body: JSON.stringify({ body }),
+  }
+);
+
+if (!response.ok) {
+  const text = await response.text();
+  throw new Error(`GitHub API ${response.status}: ${text}`);
+}
+
+console.log(`Commented on #${issueNumber} for label "${label}"`);

scripts/sweep.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env bun
+
+import { lifecycle, STALE_UPVOTE_THRESHOLD } from "./issue-lifecycle.ts";
+
+// --
+
+const NEW_ISSUE = "https://github.com/anthropics/claude-code/issues/new/choose";
+const DRY_RUN = process.argv.includes("--dry-run");
+
+const CLOSE_MESSAGE = (reason: string) =>
+  `Closing for now — ${reason}. Please [open a new issue](${NEW_ISSUE}) if this is still relevant.`;
+
+// --
+
+async function githubRequest<T>(
+  endpoint: string,
+  method = "GET",
+  body?: unknown
+): Promise<T> {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) throw new Error("GITHUB_TOKEN required");
+
+  const response = await fetch(`https://api.github.com${endpoint}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "sweep",
+      ...(body && { "Content-Type": "application/json" }),
+    },
+    ...(body && { body: JSON.stringify(body) }),
+  });
+
+  if (!response.ok) {
+    if (response.status === 404) return {} as T;
+    const text = await response.text();
+    throw new Error(`GitHub API ${response.status}: ${text}`);
+  }
+
+  return response.json();
+}
+
+// --
+
+async function markStale(owner: string, repo: string) {
+  const staleDays = lifecycle.find((l) => l.label === "stale")!.days;
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - staleDays);
+
+  let labeled = 0;
+
+  console.log(`\n=== marking stale (${staleDays}d inactive) ===`);
+
+  for (let page = 1; page <= 10; page++) {
+    const issues = await githubRequest<any[]>(
+      `/repos/${owner}/${repo}/issues?state=open&sort=updated&direction=asc&per_page=100&page=${page}`
+    );
+    if (issues.length === 0) break;
+
+    for (const issue of issues) {
+      if (issue.pull_request) continue;
+      if (issue.locked) continue;
+      if (issue.assignees?.length > 0) continue;
+
+      const updatedAt = new Date(issue.updated_at);
+      if (updatedAt > cutoff) return labeled;
+
+      const alreadyStale = issue.labels?.some(
+        (l: any) => l.name === "stale" || l.name === "autoclose"
+      );
+      if (alreadyStale) continue;
+
+      const thumbsUp = issue.reactions?.["+1"] ?? 0;
+      if (thumbsUp >= STALE_UPVOTE_THRESHOLD) continue;
+
+      const base = `/repos/${owner}/${repo}/issues/${issue.number}`;
+
+      if (DRY_RUN) {
+        const age = Math.floor((Date.now() - updatedAt.getTime()) / 86400000);
+        console.log(`#${issue.number}: would label stale (${age}d inactive) — ${issue.title}`);
+      } else {
+        await githubRequest(`${base}/labels`, "POST", { labels: ["stale"] });
+        console.log(`#${issue.number}: labeled stale — ${issue.title}`);
+      }
+      labeled++;
+    }
+  }
+
+  return labeled;
+}
+
+async function closeExpired(owner: string, repo: string) {
+  let closed = 0;
+
+  for (const { label, days, reason } of lifecycle) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    console.log(`\n=== ${label} (${days}d timeout) ===`);
+
+    for (let page = 1; page <= 10; page++) {
+      const issues = await githubRequest<any[]>(
+        `/repos/${owner}/${repo}/issues?state=open&labels=${label}&sort=updated&direction=asc&per_page=100&page=${page}`
+      );
+      if (issues.length === 0) break;
+
+      for (const issue of issues) {
+        if (issue.pull_request) continue;
+        if (issue.locked) continue;
+
+        const thumbsUp = issue.reactions?.["+1"] ?? 0;
+        if (thumbsUp >= STALE_UPVOTE_THRESHOLD) continue;
+
+        const base = `/repos/${owner}/${repo}/issues/${issue.number}`;
+
+        const events = await githubRequest<any[]>(`${base}/events?per_page=100`);
+
+        const labeledAt = events
+          .filter((e) => e.event === "labeled" && e.label?.name === label)
+          .map((e) => new Date(e.created_at))
+          .pop();
+
+        if (!labeledAt || labeledAt > cutoff) continue;
+
+        // Skip if a non-bot user commented after the label was applied.
+        // The triage workflow should remove lifecycle labels on human
+        // activity, but check here too as a safety net.
+        const comments = await githubRequest<any[]>(
+          `${base}/comments?since=${labeledAt.toISOString()}&per_page=100`
+        );
+        const hasHumanComment = comments.some(
+          (c) => c.user && c.user.type !== "Bot"
+        );
+        if (hasHumanComment) {
+          console.log(
+            `#${issue.number}: skipping (human activity after ${label} label)`
+          );
+          continue;
+        }
+
+        if (DRY_RUN) {
+          const age = Math.floor((Date.now() - labeledAt.getTime()) / 86400000);
+          console.log(`#${issue.number}: would close (${label}, ${age}d old) — ${issue.title}`);
+        } else {
+          await githubRequest(`${base}/comments`, "POST", { body: CLOSE_MESSAGE(reason) });
+          await githubRequest(base, "PATCH", { state: "closed", state_reason: "not_planned" });
+          console.log(`#${issue.number}: closed (${label})`);
+        }
+        closed++;
+      }
+    }
+  }
+
+  return closed;
+}
+
+// --
+
+const owner = process.env.GITHUB_REPOSITORY_OWNER;
+const repo = process.env.GITHUB_REPOSITORY_NAME;
+if (!owner || !repo)
+  throw new Error("GITHUB_REPOSITORY_OWNER and GITHUB_REPOSITORY_NAME required");
+
+if (DRY_RUN) console.log("DRY RUN — no changes will be made\n");
+
+const labeled = await markStale(owner, repo);
+const closed = await closeExpired(owner, repo);
+
+console.log(`\nDone: ${labeled} ${DRY_RUN ? "would be labeled" : "labeled"} stale, ${closed} ${DRY_RUN ? "would be closed" : "closed"}`);